AgentWorkforce · khaliqgant · Dec 21, 2025 · Dec 21, 2025 · Dec 21, 2025 · Dec 21, 2025
diff --git a/docs/FEDERATION_PROPOSAL.md b/docs/FEDERATION_PROPOSAL.md
diff --git a/docs/FEDERATION_PROPOSAL_REVIEW.md b/docs/FEDERATION_PROPOSAL_REVIEW.md
diff --git a/docs/HOOKS_API.md b/docs/HOOKS_API.md
diff --git a/docs/MEMORY_STACK_DECISION.md b/docs/MEMORY_STACK_DECISION.md
diff --git a/docs/competitive-analysis-ai-maestro.md b/docs/competitive-analysis-ai-maestro.md
@@ -0,0 +1,249 @@
+# Competitive Analysis: ai-maestro vs agent-relay
+
+**Date:** 2025-12-21
+**Source:** https://github.com/23blocks-OS/ai-maestro (v0.17.7)
+
+## Executive Summary
+
+ai-maestro is a mature orchestration dashboard for multi-agent coordination. It takes a **human-as-orchestrator** approach with rich visualization, while agent-relay focuses on **automatic agent-to-agent communication**. Both use tmux for agent sessions, but differ fundamentally in message delivery and autonomy.
+
+---
+
+## Architecture Comparison
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           AI-MAESTRO                                         │
+│                                                                              │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                    Web Dashboard (localhost:23000)                   │   │
+│  │                    Next.js + TypeScript + Tailwind                   │   │
+│  └────────────────────────────────┬────────────────────────────────────┘   │
+│                                   │ WebSocket                               │
+│                                   ▼                                         │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                         Manager Node                                 │   │
+│  │              (Coordinates workers, proxies connections)              │   │
+│  └────────────────────────────────┬────────────────────────────────────┘   │
+│                                   │ Tailscale VPN / Local                   │
+│          ┌────────────────────────┼────────────────────────┐               │
+│          ▼                        ▼                        ▼               │
+│  ┌──────────────┐        ┌──────────────┐        ┌──────────────┐         │
+│  │ Worker Node  │        │ Worker Node  │        │ Worker Node  │         │
+│  │ (tmux agents)│        │ (tmux agents)│        │ (tmux agents)│         │
+│  └──────────────┘        └──────────────┘        └──────────────┘         │
+│                                                                              │
+│  Communication: FILE-BASED (read from disk, human relays)                   │
+│  Human Role: ORCHESTRATOR (assigns tasks, relays messages)                  │
+└─────────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           AGENT-RELAY                                        │
+│                                                                              │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                     Dashboard (localhost:3888)                       │   │
+│  │                         + CLI Interface                              │   │
+│  └────────────────────────────────┬────────────────────────────────────┘   │
+│                                   │                                         │
+│                                   ▼                                         │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                      Daemon (per server)                             │   │
+│  │        Unix socket (local) + WebSocket (federation - planned)        │   │
+│  └────────────────────────────────┬────────────────────────────────────┘   │
+│                                   │ tmux send-keys                          │
+│          ┌────────────────────────┼────────────────────────┐               │
+│          ▼                        ▼                        ▼               │
+│  ┌──────────────┐        ┌──────────────┐        ┌──────────────┐         │
+│  │ tmux: Alice  │◄──────►│ tmux: Bob    │◄──────►│ tmux: Carol  │         │
+│  │ (auto-inject)│        │ (auto-inject)│        │ (auto-inject)│         │
+│  └──────────────┘        └──────────────┘        └──────────────┘         │
+│                                                                              │
+│  Communication: REAL-TIME (daemon routes, auto-injects via tmux)            │
+│  Human Role: OBSERVER (agents communicate autonomously)                     │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Feature Comparison
+
+| Feature | ai-maestro | agent-relay | Notes |
+|---------|------------|-------------|-------|
+| **Message Delivery** | File-based, human relays | Auto-inject via tmux | agent-relay is truly autonomous |
+| **Web Dashboard** | ✅ Rich (Next.js) | ⚠️ Basic (Ink) | ai-maestro more mature |
+| **Mobile App** | ❌ None | 📋 Planned | Opportunity for agent-relay |
+| **Distributed** | ✅ Tailscale VPN | 📋 Federation planned | Both support multi-server |
+| **Agent Sessions** | tmux (read-only) | tmux (read + inject) | agent-relay has write access |
+| **Code Intelligence** | ✅ Code Graphs | 📋 Planned | Learn from ai-maestro |
+| **Conversation Memory** | ✅ CozoDB + search | 📋 Trajectories planned | Similar goals |
+| **Agent Portability** | ✅ .zip export/import | 📋 Planned | Useful feature to adopt |
+| **Health Monitoring** | ✅ Green/red/yellow | ⚠️ Basic | Adopt their status model |
+| **Task Distribution** | Manual (human assigns) | Manual → Lead Agent | agent-relay planning automation |
+| **Hierarchical Naming** | ✅ project-backend-api | ❌ Flat names | Consider adopting |
+
+---
+
+## Key Differentiators
+
+### agent-relay's Advantages
+
+1. **Automatic Message Injection**
+   ```
+   ai-maestro:  Agent writes to file → Human reads → Human types to other agent
+   agent-relay: Agent outputs @relay:Bob → Daemon injects → Bob sees immediately
+   ```
+   This is the core differentiator. Agents can truly collaborate without human relay.
+
+2. **Real-Time Communication**
+   - ai-maestro: Polling-based file reads
+   - agent-relay: Push-based via daemon + WebSocket
+
+3. **Simpler Local Setup**
+   - ai-maestro: Manager + workers + VPN for distributed
+   - agent-relay: Single daemon, federation opt-in
+
+### ai-maestro's Advantages
+
+1. **Mature Web Dashboard**
+   - Rich visualizations
+   - Hierarchical agent tree with color coding
+   - Code graph browser
+   - Conversation search
+
+2. **Code Intelligence**
+   - Multi-language code graphs (Ruby, TypeScript, Python)
+   - Delta indexing (~100ms vs 1000ms+ full re-index)
+   - Relationship visualization
+
+3. **Agent Portability**
+   - Export agent as .zip
+   - Full config + message history + git associations
+   - Import with conflict detection
+
+4. **Health Monitoring**
+   - Visual status indicators (green/red/yellow)
+   - Per-agent resource tracking
+   - Stuck detection
+
+---
+
+## What We Should Learn from ai-maestro
+
+### 1. Hierarchical Agent Naming
+```
+Current:    Alice, Bob, Carol (flat)
+ai-maestro: project-backend-api, project-frontend-ui (hierarchical)
+Proposed:   federation/network/peer-connection (namespace/role/task)
+```
+
+### 2. Code Graph Visualization
+- Shared codebase understanding across agents
+- Delta indexing for performance
+- Multi-language support
+- Add as `ctrl-010` task
+
+### 3. Agent Health Status
+```typescript
+type AgentStatus = 'healthy' | 'degraded' | 'offline';
+
+interface AgentHealth {
+  status: AgentStatus;
+  lastHeartbeat: number;
+  cpuUsage?: number;
+  memoryUsage?: number;
+  errorRate?: number;
+  isStuck?: boolean;  // No output for N minutes
+}
+```
+
+### 4. Agent Portability
+```
+agent-export.zip
+├── config.json        # Agent configuration
+├── messages.jsonl     # Message history
+├── trajectory.json    # Work history (ours)
+├── git-associations/  # Linked repos
+└── skills.json        # Capability registry
+```
+
+### 5. Conversation Memory
+- ai-maestro uses CozoDB for semantic search
+- We can leverage trajectories + embeddings
+- Cross-agent knowledge sharing
+
+---
+
+## What ai-maestro Could Learn from Us
+
+### 1. Automatic Message Injection
+Their file-based messaging requires human relay. Our tmux send-keys approach enables true agent autonomy.
+
+### 2. End-to-End Delivery Confirmation
+We're planning delivery confirmation via capture-pane. They have no delivery guarantees.
+
+### 3. Peer-to-Peer Federation
+Our federation proposal is peer-to-peer mesh. They require central manager + VPN.
+
+### 4. Trajectories
+Our trajectory format captures complete work history with reasoning, decisions, and retrospectives—richer than their conversation memory.
+
+---
+
+## Integration Opportunities
+
+### Could We Integrate?
+
+1. **Use ai-maestro's Dashboard**
+   - Their web UI is more mature
+   - We provide the messaging backbone
+   - They display, we deliver
+
+2. **Share Code Intelligence**
+   - Their Code Graphs + our Trajectories
+   - Unified knowledge layer
+
+3. **Complementary Roles**
+   ```
+   ai-maestro: Human observation & control (read-mostly)
+   agent-relay: Agent-to-agent messaging (write-inject)
+   ```
+
+### Technical Compatibility
+
+- Both use tmux for agent sessions ✅
+- Both use WebSocket for real-time ✅
+- Different message formats (file vs protocol) ⚠️
+- Different authentication models ⚠️
+
+---
+
+## Roadmap Impact
+
+Based on this analysis, prioritize these additions:
+
+| Priority | Task | Source |
+|----------|------|--------|
+| High | Agent health monitoring | ai-maestro |
+| High | Code Graph integration | ai-maestro |
+| Medium | Hierarchical naming | ai-maestro |
+| Medium | Agent portability | ai-maestro |
+| Medium | Delta indexing | ai-maestro |
+| Low | CozoDB integration | ai-maestro |
+
+These are captured in `ctrl-010`, `ctrl-011`, `ctrl-012` tasks.
+
+---
+
+## Conclusion
+
+**ai-maestro** excels at human observation and visualization but lacks autonomous agent communication.
+
+**agent-relay** excels at automatic agent-to-agent messaging but needs richer dashboards and intelligence features.
+
+The ideal system combines:
+- agent-relay's automatic message injection
+- ai-maestro's visualization and code intelligence
+- Our proposed federation for distributed deployment
+- Our proposed control plane for human oversight
+
+We're building the messaging backbone; ai-maestro shows what the UI layer should look like.
diff --git a/src/cli/index.test.ts b/src/cli/index.test.ts
@@ -1,9 +1,9 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { exec } from 'node:child_process';
 import { promisify } from 'node:util';
 import path from 'node:path';
 import fs from 'node:fs';
 import os from 'node:os';

 const execAsync = promisify(exec);

@@ -114,6 +114,42 @@
     });
   });
 
+  describe('attach', () => {
+    it('should show help for attach command', async () => {
+      const { stdout } = await runCli('attach --help');
+      expect(stdout).toContain('Attach to a running agent session');
+      expect(stdout).toContain('<name>');
+    });
+
+    it('should error when session does not exist', async () => {
+      const { stderr, code } = await runCli('attach nonexistent-agent');
+      expect(code).not.toBe(0);
+      expect(stderr).toContain('No session found');
+    });
+  });
+
+  describe('kill', () => {
+    it('should show help for kill command', async () => {
+      const { stdout } = await runCli('kill --help');
+      expect(stdout).toContain('Stop a detached agent');
+      expect(stdout).toContain('<name>');
+      expect(stdout).toContain('--force');
+    });
+
+    it('should handle killing nonexistent agent gracefully', async () => {
+      const { stdout } = await runCli('kill nonexistent-agent-12345');
+      expect(stdout).toContain('No running agent found');
+    });
+  });
+
+  describe('detach flag', () => {
+    it('should show -d/--detach in help', async () => {
+      const { stdout } = await runCli('--help');
+      expect(stdout).toContain('-d, --detach');
+      expect(stdout).toContain('background');
+    });
+  });
+
   describe('history', () => {
     it('should show history or empty message', async () => {
       const { stdout, code } = await runCli('history --limit 5');