agent-chat

agent-chat

Overview

Peer agent sessions coordinate by exchanging markdown files in shared channel folders — no supervisor, no message broker, no RAM shared between them. Each channel is one "group chat". The whole thread is plain markdown: git-committable, human-readable, replayable. A crashed session loses nothing — the files are the state.

One CLI (chat.py, Python stdlib only) runs identically on Windows, WSL and Linux. wait blocks with a sleep-poll loop, so an agent waiting for a reply burns zero model tokens while idle.

Core principle: talk through files, not through each other. Summaries as artifacts, not full transcripts passed back and forth.

When to use

• Multiple claude sessions (or Cursor/Codex/OpenCode) working the same problem as equals.
• One session needs another to do something, then waits for the result.
• You want an auditable record of an agent negotiation.
• You need several independent group chats (one per topic/team) — make one channel each.

When NOT to use: a single agent with cheap subagents is cheaper and simpler — this pattern trades tokens for parallelism, fault tolerance, and auditability. If token budget is tight, use only the async/handoff path (post a summary at end of session; the next session reads it) — that mode costs almost nothing.

Quick reference

As a Claude Code plugin, run python ${CLAUDE_PLUGIN_ROOT}/chat.py <cmd> (standalone: python chat.py <cmd>). Root = $AGENT_CHAT_ROOT or ~/agent-chat (override with --root).

Outside Claude Code, ${CLAUDE_PLUGIN_ROOT} does not resolve. Point chat.py at a real checkout path (python /path/to/agent-chat-plugin/chat.py <cmd>) or install the CLI (pipx install agent-chat-plugin, then agent-chat <cmd>; same flags). The hooks/*.py inbox scripts are harness-neutral as well — wire them by absolute path; each exits 0 with a one-line stderr note when it cannot resolve its plugin root.

Do this	Command
Create a group chat	chat.py init review --members alice,bob --topic "..."
List all group chats	chat.py channels
Post a message	chat.py post review --from alice --to bob --title "Schema v0.2" --body-file msg.md
Broadcast to the group	chat.py post review --from alice --to all --title "..." (or omit --to)
Read what's new for me	chat.py read review --as bob
Wait for a reply (0 tokens)	chat.py wait review --as alice --timeout 900
Peek recent, keep cursor	chat.py peek review -n 3
Claim a task marker	chat.py claim work task-12.md --as bob
Lock workspace paths	chat.py lock review src/main.py --as alice --lease-seconds 300
Check path conflicts	chat.py check review src/main.py
Release path lock	chat.py unlock review <lock-id-or-path> --as alice
Recover stale lock	chat.py recover review <lock-id-or-path> --as bob --reason "stale"
Recover pending path transaction	chat.py recover-pending review --as alice
Post capability/status event	chat.py event post review --from alice --type capability --harness omp
Read adapter events	chat.py event read review --type capability