ai-collab

# ai-collab — Autonomous Multi-Agent Collaboration Two OpenClaw agents working in parallel on shared tasks, coordinated via a structured chat log and daemon inbox protocol. ## Architecture Overview ``` ┌─────────────────────────────────────────────────────────┐ │ User (Jeremy) │ │ Telegram / Direct Message │ └──────────────────────┬──────────────────────────────────┘ │ ┌─────────────┴──────────────┐ ▼ ▼ ┌─────────────────┐ ┌──────────────────┐ │ AGENT A │ │ AGENT B │ │ (Jim / main) │◄───────►│ (Clawdy / daemon)│ │ claude code │ │ claude --print │ │ port: main │ │ inbox: filesystem │ └────────┬────────┘ └────────┬─────────┘ │ │ └──────────┬────────────────┘ ▼ ┌──────────────────┐ │ chat.log │ ← THE shared record │ collab/inbox/ │ ← A→B messages └──────────────────┘ ``` **Agent A (Primary):** Interactive Claude Code session. Handles browser, complex tasks, user-facing responses. **Agent B (Daemon):** `claude --print` subprocess. Handles background tasks, monitoring, quick lookups. Triggered by messages dropped in inbox. --- ## Configuration All settings via environment variables — no hardcoded values: ```bash # ~/.openclaw/workspace/collab/.ai-collab.env export AGENT_A_NAME=Jim export AGENT_B_NAME=Clawdy export AGENT_B_MODEL=claude-haiku-4-5-20251001 # Any claude --print compatible model export AGENT_B_SESSION=clawdy-session # tmux session name export COLLAB_INBOX=$HOME/.openclaw/workspace/collab/inbox export COLLAB_LOG=$HOME/.openclaw/workspace/collab/chat.log ``` Supported models for `AGENT_B_MODEL`: - `claude-haiku-4-5-20251001` — fastest, cheapest (recommended for daemon) - `claude-sonnet-4-6` — more capable, higher cost - Any OpenAI model if using the GPT daemon variant (see `examples/claude-gpt.md`) ## Quick Setup ```bash # 1. Source config source ~/.openclaw/workspace/collab/.ai-collab.env # 2. Create the collab workspace mkdir -p "$COLLAB_INBOX" # 3. Start Agent B daemon (in a tmux session) tmux new-session -d -s "$AGENT_B_SESSION" \ "source ~/.openclaw/workspace/collab/.ai-collab.env && \ bash ~/.openclaw/workspace/skills/ai-collab/scripts/daemon.sh" # 4. Start message polling (Agent B → Agent A routing, runs every 60s via cron) bash ~/.openclaw/workspace/skills/ai-collab/scripts/poll_chatlog.sh & # 5. Test the link bash ~/.openclaw/workspace/skills/ai-collab/scripts/send.sh "Hello from Agent A" ``` --- ## Communication Protocol Every message between agents follows this format. **No open loops.** | Tag | Direction | Meaning | |-----|-----------|---------| | `[TASK:name]` | A→B or B→A | Assign a task | | `[ACK:name]` | receiver | Acknowledged, starting work | | `[DONE:name]` | executor | Task complete + one-line result | | `[BLOCKED:name]` | executor | Can't complete + reason | | `[HANDOFF:name]` | either | "Do X, reply [DONE:name] when finished" | | `[STATUS:update]` | either | Async update on long-running task | | `[QUESTION:topic]` | either | Needs info before proceeding | **Rules:** 1. Answer questions before asking new ones 2. Close tasks before starting new ones 3. Every message moves work forward or closes a loop 4. Never: "let me know", "ready when you are", "standing by" **Example exchange:** ``` A → B: [TASK:price-check] Get BTC price from CoinGecko B → A: [ACK:price-check] Checking now. B → A: [DONE:price-check] BTC $94,230 as of 03:15 UTC ``` --- ## Daemon Script (Agent B) `scripts/daemon.sh` — drop in your collab directory: ```bash #!/bin/bash PIDFILE="/tmp/agentb_daemon.pid" if [ -f "$PIDFILE" ] && kill -0 "$(cat $PIDFILE)" 2>/dev/null; then echo "Daemon already running (PID $(cat $PIDFILE)). Exiting." >&2 exit 1 fi echo $$ > "$PIDFILE" trap "rm -f $PIDFILE" EXIT # Required: unset so nested claude --print works unset CLAUDECODE INBOX="$HOME/.openclaw/workspace/collab/inbox" LOG="$HOME/.openclaw/workspace/collab/chat.log" mkdir -p "$INBOX" logline() { printf "%s %s\n" "$(date '+%Y-%m-%d %H:%M:%S')" "$1" >> "$LOG" } logline "SYSTEM: Agent B daemon started" inotifywait -m -e moved_to "$INBOX" 2>/dev/null | while read dir event file; do FULLPATH="$INBOX/$file" [ ! -f "$FULLPATH" ] && continue MSG=$(cat "$FULLPATH") rm "$FULLPATH" logline "A -> B: $MSG" # Run Agent B (claude --print) RESPONSE=$(claude --print --model claude-haiku-4-5-20251001 \ "You are Agent B. Agent A says: $MSG Respond in under 100 words. Use [DONE:taskname] or [BLOCKED:taskname] to close loops. Context: shared collab system. Chat log: $LOG" 2>/dev/null) logline "B -> A: $RESPONSE" # Route response back to Agent A openclaw agent --agent main -m "[AgentB]: $RESPONSE" --json > /dev/null 2>&1 done ``` --- ## Sending Messages (A → B) ```bash # From Agent A, send to Agent B daemon inbox bash ~/.openclaw/workspace/skills/ai-collab/scripts/send.sh "your message" ``` **Atomic write pattern (prevents partial reads):** ```bash INBOX="$HOME/.openclaw/workspace/collab/inbox" TMPFILE=$(mktemp "$INBOX/.msg.XXXXXX") echo "$*" > "$TMPFILE" mv "$TMPFILE" "$INBOX/msg_$(date +%s%N).txt" ``` Always use `mktemp` + `mv` — never write directly to inbox. inotifywait fires on `moved_to`, not `close_write`. --- ## Chat Log Polling (B → A) `scripts/poll_chatlog.sh` — run via cron every 60s: ```bash #!/bin/bash LOG="$HOME/.openclaw/workspace/collab/chat.log" PTR_FILE="/tmp/chatlog_ptr" [ ! -f "$LOG" ] && exit 0 TOTAL=$(wc -l < "$LOG") LAST=$(cat "$PTR_FILE" 2>/dev/null || echo "0") [ "$TOTAL" -le "$LAST" ] && echo "$TOTAL" > "$PTR_FILE" && exit 0 NEW=$(tail -n +"$((LAST + 1))" "$LOG" | grep "B -> A:" | sed 's/.*B -> A: //') echo "$TOTAL" > "$PTR_FILE" [ -z "$NEW" ] && exit 0 while IFS= read -r line; do [ -z "$line" ] && continue openclaw agent --agent main -m "[AgentB]: $line" --json > /dev/null 2>&1 done <<< "$NEW" ``` Add to crontab: ``` * * * * * /bin/bash ~/.openclaw/workspace/collab/poll_chatlog.sh ``` --- ## Shared Filesystem Conventions ``` ~/.openclaw/workspace/collab/ chat.log # THE shared record — all messages logged here inbox/ # A→B message queue (atomic mv only) .env # Shared secrets (chmod 600, never log) task_queue.md # Optional: structured task backlog status_tracker.md # Optional: current task status per agent ``` **Logging to chat.log:** ```bash printf "%s %s\n" "$(date '+%Y-%m-%d %H:%M:%S')" "A -> B: [TASK:name] Description" >> "$LOG" ``` **Rules:** - Never log secrets from `.env` - Always timestamp every line - Prefix with sender: `A -> B:` or `B -> A:` or `SYSTEM:` or `JEREMY ->` --- ## Telegram Bridge (Optional) Route user Telegram messages into Agent B's inbox. Full setup guide: `references/telegram-bridge.md` **Quick summary:** 1. Create a bot via [@BotFather](https://t.me/BotFather) → get `BOT_TOKEN` 2. Add bot to your group → get `GROUP_ID` (negative number, e.g. `-1001234567890`) 3. Disable Group Privacy Mode in BotFather so bot can read all messages 4. Get your Telegram `USER_ID` from [@userinfobot](https://t.me/userinfobot) 5. Set in `~/.openclaw/.env`: `TELEGRAM_BOT_TOKEN`, `TELEGRAM_GROUP_ID`, `TELEGRAM_USER_ID` 6. Run the bridge in tmux: `tmux new-session -d -s tg-bridge "bash references/telegram-bridge.md"` ```bash # Minimal bridge loop (inline version): source ~/.openclaw/.env OFFSET_FILE="/tmp/tg_offset" while true; do OFFSET=$(cat "$OFFSET_FILE" 2>/dev/null || echo "0") UPDATES=$(curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getUpdates?offset=$((OFFSET+1))&timeout=20") # Parse updates, drop user messages into inbox with USER: prefix # See references/telegram-bridge.md for full parsing implementation sleep 1 done ``` See `references/telegram-bridge.md` for the complete production-ready implementation with message parsing, offset tracking, and error handling. --- ## Agent Configurations See `examples/` for full configs: ### Claude ↔ Claude (Jim + Clawdy) - Agent A: `claude code` (interactive, full tool access) - Agent B: `claude --print claude-haiku-4-5-20251001` (fast, scripting-optimized) - Best for: heavy task parallelism, one agent researches while other implements ### Claude ↔ GPT - Agent A: Claude Code (full tool use) - Agent B: `openai api chat.completions.create` via script - Best for: cross-model verification, Claude builds → GPT reviews ### GPT ↔ GPT - Agent A: GPT-4o via `openai` CLI - Agent B: GPT-4o-mini for fast background checks - Best for: speed + cost optimization when all context is OpenAI --- ## Task Handoff Pattern When Agent A needs Agent B to own a task completely: ``` A → B: [HANDOFF:data-fetch] Fetch all BTC trades from Kraken API last 7 days. Save to ~/.openclaw/workspace/collab/kraken_trades.json. Reply [DONE:data-fetch] when finished. B → A: [ACK:data-fetch] Fetching now. B → A: [DONE:data-fetch] 847 trades saved to kraken_trades.json. Date range: 2026-02-15 to 2026-02-22. ``` Agent A does not check on progress — waits for DONE or BLOCKED. --- ## Approval Pattern When Agent B's daemon needs user approval for a terminal command: ```bash # From Agent A / user terminal: bash ~/.openclaw/workspace/skills/ai-collab/scripts/approve.sh "Yes" # or for numbered selections: bash ~/.openclaw/workspace/skills/ai-collab/scripts/approve.sh "2" ``` `approve.sh` sends keystrokes to the tmux session running Agent B: ```bash SESSION=$(tmux ls | grep agentb-session | head -1 | cut -d: -f1) tmux send-keys -t "$SESSION" "$1" Enter ``` --- ## Rate Limiting Agent B should implement a rate governor to prevent runaway API calls: ```bash # In daemon loop, before calling claude --print: CALLS_FILE="/tmp/agentb_calls" WINDOW=60 # seconds MAX_CALLS=10 # Count calls in last window RECENT=$(awk -v cutoff="$(($(date +%s) - WINDOW))" '$1 > cutoff' "$CALLS_FILE" 2>/dev/null | wc -l) if [ "$RECENT" -ge "$MAX_CALLS" ]; then logline "SYSTEM: Rate limited — $RECENT calls in ${WINDOW}s" sleep 10 continue fi date +%s >> "$CALLS_FILE" ``` --- ## Financial Gate Protocol (TIERED — updated 2026-02-22) **Three tiers based on amount:** | Tier | Amount | Rule | |------|--------|------| | 1 | Under $20 | Either agent acts independently — no approval needed | | 2 | $20–$50 | Both agents PROPOSE + APPROVE before acting | | 3 | Over $50 | Requires `[AUTHORIZED:financial:amount:timestamp:Jeremy]` tag | ```bash # Tier 3 tag format (Jeremy must write to chat.log): [AUTHORIZED:financial:buy:BTC:$100:2026-02-22:Jeremy] # Tier 2 example flow: # Clawdy proposes: "PROPOSE: buy $35 of SOL for DePIN gas — approve?" # Jim approves: "APPROVED: buy $35 SOL" # Then Clawdy acts. ``` **Daemon tiered gate logic:** ```bash # <$20: proceed. $20-50: flag as tier2. >$50: block without AUTHORIZED tag. AMOUNT=$(echo "$MSG" | grep -oP '[$]?\d+' | head -1 | tr -d '$') if [ -n "$AMOUNT" ] && [ "$AMOUNT" -gt 50 ] && ! echo "$MSG" | grep -q "\[AUTHORIZED:financial:"; then logline "BLOCKED:financial-gate:tier3 — amount>$50, no AUTHORIZED tag"; continue elif [ -n "$AMOUNT" ] && [ "$AMOUNT" -ge 20 ]; then logline "FINANCIAL:tier2 — propose before acting" fi ``` If Tier 3 blocked: log `[BLOCKED:financial-gate:tier3]`, send Telegram alert, do NOT execute. --- ## Daemon Watchdog Pattern Check daemon health every 15 minutes. If silent >15 min, restart: ```bash # check_daemon.sh (add to crontab: */15 * * * *) PIDFILE="/tmp/agentb_daemon.pid" LOG="$HOME/.openclaw/workspace/collab/chat.log" # Check PID alive pid_alive=0 [ -f "$PIDFILE" ] && kill -0 "$(cat $PIDFILE)" 2>/dev/null && pid_alive=1 # Check last activity within 15 min last_ts=$(grep -oP '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}' "$LOG" 2>/dev/null | tail -1) recent=0 if [ -n "$last_ts" ]; then age=$(( ($(date +%s) - $(date -d "$last_ts" +%s 2>/dev/null || echo 0)) / 60 )) [ "$age" -lt 15 ] && recent=1 fi if [ "$pid_alive" = "0" ] || [ "$recent" = "0" ]; then tmux send-keys -t agentb-session "bash daemon.sh" Enter fi ``` --- ## Task Takeover Threshold If Agent A (Jim) blocks on the same task **twice**, Agent B (Clawdy) takes it over: ``` B → A: [TASK:fetch-data] Fetch X. Reply [DONE:fetch-data]. # 10 min timer... A → B: [BLOCKED:fetch-data] Can't access endpoint. B → A: [RETRY:fetch-data] Try alternate: curl -s https://backup-endpoint.com/x # Another 10 min... A → B: [BLOCKED:fetch-data] Still failing. # Clawdy takes over immediately: B: *executes task directly, logs [DONE:fetch-data] to chat.log* ``` Rule: **Blocked 2x on same task → take it over, don't reassign.** --- ## Daemon Error Diagnosis When daemon produces blank/error responses: 1. Check `/tmp/clawdy_last_err` — contains last stderr from `claude --print` 2. Check ANSI-stripped chat.log for `CLAWDY_ERR:` lines 3. Verify RESPONSE trimming line not corrupted (common issue: accidentally set to `RESPONSE=""`) 4. Restart daemon: `kill $(cat /tmp/clawdy_daemon.pid) && sleep 1 && bash clawdy_daemon.sh` **Auto-approve**: Use `Bash(*)` in `~/.claude/settings.local.json`. **NEVER** use tmux send-keys cron — it sends keypresses blindly to the wrong sessions.