agent-chat

Peer AI agents chat in a shared folder — no human relay, no orchestrator, works on Windows, waits at zero tokens.

Multiple agent sessions (Claude Code, Codex, Cursor, OpenCode — same tool or mixed) coordinate as equals by exchanging markdown messages in shared channel folders. The folder is the whole state: git-committable, human-readable, replayable. A crashed session loses nothing.

One dependency-free file (chat.py, Python stdlib) runs identically on Windows, WSL, and Linux. Waiting for a reply blocks in-process — an agent that is waiting spends zero model tokens.

Distributed as agent-chat-plugin on PyPI and as a Claude Code plugin (the short name agent-chat was taken on PyPI). The command and skill are still agent-chat.

Why this exists

Claude Code now has a native cross-session messaging path for Claude Code sessions on supported platforms. The peer case this project targets is broader: N equal sessions across Claude Code, Codex, Cursor, OpenCode, or mixed tools coordinating through a file-backed, auditable folder of messages and autonomously waiting on each other. This is that cross-tool answer. (Honest scope: this is a young space; see COMPARISON.md for the native Claude Code overlap and the exact differences.)

Claude Code native overlap

Claude Code v2.1.224+ provides Cross-session messaging through ListAgents and SendMessage on macOS/Linux, including WSL2; native Windows is not currently supported. That feature is Claude-Code-only and delivers messages directly between sessions. This project remains distinct through mixed-tool coordination, native Windows support, Markdown channels that are git-committable and replayable, atomic claims/cursors, and zero-token in-process waiting. On supported Claude Code platforms, the native path may make this plugin's optional unread-notification hooks redundant; it does not replace the file-backed protocol.

Quickstart

# a channel = a group chat
python chat.py init review --members alice,bob --topic "code review"

# alice posts to bob
python chat.py post review --from alice --to bob --title "Schema v0.2" --body-file msg.md

# bob reads what's new for him (only messages addressed to him or the group)
python chat.py read review --as bob

# alice waits for bob's reply — burns 0 tokens while blocked
python chat.py wait review --as alice --timeout 900

Root defaults to ~/agent-chat; override with $AGENT_CHAT_ROOT or --root. Run python chat.py <cmd> --help for all flags.

How it works

• Channels — one folder per group chat; make as many as you need (init).
• Messages — NNNN-<from>-<slug>.md with frontmatter (from, to, reply_to, status, title). to: all broadcasts.
• Cursors — read/wait show only what's new for you and never re-scan the thread.
• Atomic — sequence numbers are allocated under a lock (no duplicate -11); task claiming uses atomic rename (lose the race -> move on).

Six rules keep peers from stepping on each other: one channel per topic; claim before you act; message don't chatter; wait don't poll-with-the-model; read since your cursor; reply in a new file. Full protocol in SPEC.md.

Two modes, two budgets

• Live swarm — N sessions running concurrently, wait-ing on each other. Buys wall-clock parallelism + fault tolerance; costs more tokens. For abundant budgets.
• Async handoff / audit — post a summary when a session ends; the next session reads it. Nearly free — usable on a tight budget.

Install & distribution

• As a CLI — pipx install agent-chat-plugin then run agent-chat (or uvx --from agent-chat-plugin agent-chat).
• As a skill — drop SKILL.md + chat.py into your agent's skills directory; works across tools that read the Agent Skills / SKILL.md standard.
• As a Claude Code plugin — via a plugin marketplace.

Status

Early (v0). The reference implementation is tested end-to-end; the protocol may still change. Feedback and interop with tap / TICK.md welcome.

License

Apache-2.0.