agent-relay 1.0.7 → 1.0.9

package/docs/PROTOCOL.md

@@ -290,15 +290,15 @@ Client should send fresh HELLO.
 ### Inline Format (single line only)
 
 ```
-@relay:codex-1 Your turn to play
-@thinking:* Considering the Queen...
+->relay:codex-1 Your turn to play
+->thinking:* Considering the Queen...
 ```
 
 ### Rules
 
 1. Block: Only parse when `[[RELAY]]` at start of line
 2. Inline: Only at start of line, not in code fences
-3. Escape: `\@relay:` outputs literal `@relay:`
+3. Escape: `\->relay:` outputs literal `->relay:`
 
 ---
 

package/docs/SCALING_ANALYSIS.md

@@ -0,0 +1,280 @@
+# Scaling Analysis: Is the TUI Dashboard Worth It?
+
+## The Question
+
+The proposed changes add significant complexity:
+- TUI dashboard with `blessed` library
+- Daemon event streaming
+- Activity state reporting from wrappers
+- New CLI commands
+
+**Is this the right approach, or is there a simpler path?**
+
+---
+
+## Behavior Comparison
+
+### Current (2-3 Agents)
+
+```bash
+# Terminal 1
+agent-relay -n Alice claude
+# You're IN Alice's tmux, working
+
+# Terminal 2
+agent-relay -n Bob claude
+# You're IN Bob's tmux
+
+# To switch: Alt+Tab between terminal windows
+# To see status: mentally track what each is doing
+```
+
+**Works fine because:** You can hold 2-3 contexts in your head.
+
+### Proposed (5-10 Agents)
+
+```bash
+# Terminal 1
+agent-relay up        # Start daemon
+agent-relay watch     # TUI dashboard
+
+┌─ Agent Relay ───────────────────────────────┐
+│ ● Alice     active   12↑ 8↓                 │
+│ ● Bob       typing   5↑ 14↓                 │
+│ ○ Charlie   offline  queued: 3              │
+│ ...                                         │
+└─────────────────────────────────────────────┘
+
+# Press 'a' → attach to native tmux
+# Ctrl+B d → back to TUI
+```
+
+**Adds complexity:**
+- blessed dependency (~500KB)
+- Event stream protocol
+- Activity reporting
+- More state to track in daemon
+
+---
+
+## Alternative: Just Use tmux Better
+
+tmux already has multi-pane and multi-window support. Why not leverage it?
+
+### Simpler Approach: Native tmux Layout
+
+```bash
+# Start all agents in one tmux session with multiple windows
+agent-relay team start
+
+# Creates tmux session "relay-team" with:
+# - Window 0: Alice (claude)
+# - Window 1: Bob (claude)
+# - Window 2: Charlie (claude)
+# - Window 3: Status pane (tail -f on logs)
+
+# Switch windows: Ctrl+B 0, Ctrl+B 1, Ctrl+B 2...
+# Or use: Ctrl+B w (window list)
+```
+
+**Implementation (50 lines, not 500):**
+
+```bash
+#!/bin/bash
+# agent-relay team start
+
+TEAM_SESSION="relay-team"
+AGENTS=$(cat teams.json | jq -r '.agents[].name')
+
+tmux new-session -d -s "$TEAM_SESSION"
+
+i=0
+for agent in $AGENTS; do
+  if [ $i -eq 0 ]; then
+    tmux send-keys -t "$TEAM_SESSION" "agent-relay -n $agent claude" Enter
+  else
+    tmux new-window -t "$TEAM_SESSION"
+    tmux send-keys -t "$TEAM_SESSION" "agent-relay -n $agent claude" Enter
+  fi
+  ((i++))
+done
+
+# Add status window
+tmux new-window -t "$TEAM_SESSION" -n "status"
+tmux send-keys -t "$TEAM_SESSION:status" "watch -n1 agent-relay agents" Enter
+
+tmux attach -t "$TEAM_SESSION"
+```
+
+**User experience:**
+```
+Ctrl+B w  →  Shows window list:
+  0: Alice (attached)
+  1: Bob
+  2: Charlie
+  3: status
+
+Ctrl+B 1  →  Jump to Bob
+Ctrl+B 3  →  See status (agent-relay agents output)
+```
+
+---
+
+## Comparison: TUI vs Native tmux
+
+| Aspect | TUI Dashboard (blessed) | Native tmux Windows |
+|--------|------------------------|---------------------|
+| **Lines of code** | ~500 | ~50 |
+| **Dependencies** | blessed (~500KB) | None (tmux built-in) |
+| **Learning curve** | New UI to learn | tmux you already know |
+| **Real-time updates** | Yes (event stream) | Yes (watch command) |
+| **Quick switch** | Press 'a', select | Ctrl+B {number} |
+| **See all at once** | TUI list | Ctrl+B w (window list) |
+| **Native experience** | Detach TUI → attach tmux | Already in tmux |
+| **Maintenance** | blessed updates, bugs | tmux is stable |
+
+---
+
+## What We Actually Need for Scaling
+
+Let's separate "nice to have" from "essential":
+
+### Essential (for 5-10 agents)
+
+1. **Quick overview of all agents** → `agent-relay agents` (already proposed)
+2. **Know who's busy vs idle** → Activity state in agents output
+3. **Message history** → `agent-relay history` (already proposed)
+4. **Quick attach** → `agent-relay attach Alice`
+5. **Group messaging** → `->relay:@backend` (already proposed)
+
+### Nice to Have (but complex)
+
+1. **Real-time TUI dashboard** → Use `watch` instead
+2. **Event streaming** → Poll daemon status instead
+3. **Typing indicators** → Not critical for coordination
+
+---
+
+## Recommended Simpler Approach
+
+### Phase 5 Revised: Minimal Scaling
+
+```bash
+# 1. Better status command (essential)
+$ agent-relay agents
+NAME       STATUS   MESSAGES   LAST SEEN
+Alice      active   12↑ 8↓     now
+Bob        idle     5↑ 14↓     30s ago
+Charlie    offline  queued: 3  5m ago
+
+# 2. Quick attach (essential)
+$ agent-relay attach Alice
+# Attaches to relay-Alice-* session
+
+# 3. Team layout (essential)
+$ agent-relay team start
+# Creates multi-window tmux session
+# Use Ctrl+B w to see all, Ctrl+B {n} to switch
+
+# 4. Live status (nice to have, zero code)
+$ watch -n2 agent-relay agents
+# Updates every 2 seconds
+
+# 5. Message history (essential)
+$ agent-relay history --last 20
+14:23:01 Alice → Bob: Can you check the API?
+14:23:15 Bob → Alice: On it
+...
+```
+
+### Implementation Effort
+
+| Feature | Complex TUI Approach | Simpler Approach |
+|---------|---------------------|------------------|
+| TUI dashboard | 2 days + blessed dep | 0 (use `watch`) |
+| Event stream | 1 day + protocol change | 0 (poll status) |
+| Activity reporting | 1 day | 0.5 day (just in status) |
+| Team layout | Already proposed | Same (0.5 day) |
+| Better agents cmd | Same | Same (0.5 day) |
+| History command | Same | Same (0.5 day) |
+| **Total** | **5+ days** | **2 days** |
+
+---
+
+## Verdict: Skip the TUI, Use tmux
+
+The TUI dashboard is over-engineered. tmux already provides:
+- Multi-window switching (Ctrl+B w)
+- Split panes (Ctrl+B %)
+- Session persistence
+- Window list
+
+**What we actually need:**
+
+1. **`agent-relay agents`** - Show status with activity state
+2. **`agent-relay attach <name>`** - Quick attach helper
+3. **`agent-relay team start`** - Multi-window tmux layout
+4. **`agent-relay history`** - Query past messages
+
+**What we DON'T need:**
+
+1. ❌ blessed TUI dependency
+2. ❌ Event streaming from daemon
+3. ❌ Complex activity reporting protocol
+4. ❌ Real-time typing indicators
+
+---
+
+## Updated Design Recommendation
+
+### Keep from Phase 5:
+- Agent groups (`->relay:@backend`)
+- Message priority (`!`, `?`)
+- `agent-relay agents` command
+- `agent-relay history` command
+
+### Replace TUI with:
+```bash
+# Multi-window tmux session
+agent-relay team start    # Creates relay-team session
+agent-relay team attach   # Attach to existing
+agent-relay team add Bob  # Add agent to running team
+
+# Quick attach to single agent
+agent-relay attach Alice
+
+# Live status (zero code, just docs)
+watch -n2 agent-relay agents
+```
+
+### Effort Saved:
+- No blessed dependency
+- No event streaming protocol
+- No TUI code maintenance
+- 3+ days of implementation saved
+
+---
+
+## Behavior Impact Summary
+
+| Scenario | TUI Approach | Simpler Approach |
+|----------|--------------|------------------|
+| See all agents | Open TUI, see list | `agent-relay agents` or `Ctrl+B w` |
+| Switch to Bob | Press 'a', select Bob | `Ctrl+B 1` or `agent-relay attach Bob` |
+| Check if Alice is busy | See "typing..." in TUI | Check status column in agents |
+| Send message to group | Same | Same (`->relay:@backend`) |
+| View history | Press 'h' in TUI | `agent-relay history` |
+
+**The simpler approach does everything the TUI does, with 80% less code.**
+
+---
+
+## Final Recommendation
+
+1. **Don't build the TUI dashboard** - It's solving a problem tmux already solves
+2. **Do add `agent-relay team`** - Leverages tmux's native multi-window
+3. **Do improve `agent-relay agents`** - Add activity state, message counts
+4. **Do add `agent-relay history`** - Query past messages
+5. **Document `watch` trick** - Free live updates
+
+This keeps the simplicity advantage while scaling to 10+ agents.

package/docs/TMUX_IMPLEMENTATION_NOTES.md

@@ -47,7 +47,7 @@ The previous tmux implementation had these issues:
 │  TmuxWrapper (this process)      │
 │  - Polls capture-pane @ 100ms    │
 │  - Detects new output (diff)     │
-│  - Parses @relay: commands       │
+│  - Parses ->relay: commands       │
 │  - Writes to stdout for user     │
 │  - Injects messages via send-keys│
 │  - Forwards user stdin to tmux   │
@@ -103,12 +103,12 @@ process.stdin.on('data', (data) => {
    - Solution: Use -S - to get full scrollback, diff against last capture
 
 2. **Binary/escape sequences**: Output might contain control characters
-   - Solution: Strip ANSI codes before parsing @relay:
+   - Solution: Strip ANSI codes before parsing ->relay:
 
 3. **Session death**: tmux session might exit
    - Solution: Monitor with `tmux has-session -t session`
 
-4. **Multiple messages**: Several @relay: in one capture
+4. **Multiple messages**: Several ->relay: in one capture
    - Solution: Track last processed line/position
 
 5. **Stdin race conditions**: User types while we inject
@@ -119,7 +119,7 @@ process.stdin.on('data', (data) => {
 1. **Basic session start**: Does claude actually launch in tmux?
 2. **Output capture**: Can we see claude's output?
 3. **Input injection**: Can we send text and get response?
-4. **@relay detection**: Does parser find @relay: commands?
+4. **->relay detection**: Does parser find ->relay: commands?
 5. **Full game**: Two agents playing tic-tac-toe
 
 ## Rollback Plan
@@ -194,10 +194,10 @@ node dist/cli/index.js send -f Coordinator -t PlayerX -m "Hello from Coordinator
 node dist/cli/index.js start -f
 
 # Terminal 2: PlayerX
-node dist/cli/index.js wrap --tmux2 -n PlayerX -- claude -p "You are PlayerX playing tic-tac-toe. Use @relay:PlayerO to send moves. Start with your first move."
+node dist/cli/index.js wrap --tmux2 -n PlayerX -- claude -p "You are PlayerX playing tic-tac-toe. Use ->relay:PlayerO to send moves. Start with your first move."
 
 # Terminal 3: PlayerO
-node dist/cli/index.js wrap --tmux2 -n PlayerO -- claude -p "You are PlayerO playing tic-tac-toe. Use @relay:PlayerX to send moves. Wait for PlayerX to start."
+node dist/cli/index.js wrap --tmux2 -n PlayerO -- claude -p "You are PlayerO playing tic-tac-toe. Use ->relay:PlayerX to send moves. Wait for PlayerX to start."
 ```
 
 ### Debugging
@@ -253,7 +253,7 @@ The message was successfully typed into the bash terminal via tmux send-keys.
 
 1. Test with Claude CLI (replace bash with claude)
 2. Test full tic-tac-toe game between two agents
-3. Verify @relay: command parsing works in both directions
+3. Verify ->relay: command parsing works in both directions
 4. Check if multi-round injection remains stable (previous implementations failed after 2-3 rounds)
 
 ### Critical Question
@@ -306,10 +306,10 @@ The critical test is whether injection remains stable over multiple rounds:
 node dist/cli/index.js start -f
 
 # Terminal 2: PlayerX
-node dist/cli/index.js wrap --tmux2 -n PlayerX -- claude -p "Play tic-tac-toe. Use @relay:PlayerO to send moves."
+node dist/cli/index.js wrap --tmux2 -n PlayerX -- claude -p "Play tic-tac-toe. Use ->relay:PlayerO to send moves."
 
 # Terminal 3: PlayerO
-node dist/cli/index.js wrap --tmux2 -n PlayerO -- claude -p "Play tic-tac-toe. Use @relay:PlayerX to send moves."
+node dist/cli/index.js wrap --tmux2 -n PlayerO -- claude -p "Play tic-tac-toe. Use ->relay:PlayerX to send moves."
 ```
 
 If this works for a full game (5-9 moves), we've solved the problem.