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 (OMP, 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.

The dependency-free CLI (chat.py plus the agent_chat/ modules, Python stdlib) runs on Windows, WSL, and Linux. Waiting for a reply blocks in-process — the wait loop makes no model calls and consumes no 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

Run these commands from a complete repository checkout. With the installed CLI, replace python chat.py with agent-chat (see Install & distribution).

# 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 "Ready for review."

# bob reads what's new for him
python chat.py read review --as bob

# create dependent work
python chat.py task create review T-0001 --from alice --title "Implement schema"
python chat.py task create review T-0002 --from alice --title "Review schema" --depends-on T-0001

# claim, renew and complete a ready task
python chat.py task claim review T-0001 --as alice --lease-seconds 900
python chat.py task renew review T-0001 --as alice --lease-seconds 900
python chat.py task done review T-0001 --as alice

# coordinate paths and state
python chat.py lock review src/schema.py --as alice --lease-seconds 900
python chat.py unlock review src/schema.py --as alice
python chat.py state review
python chat.py compact review --as alice

# capability handshake without claiming host-native execution
python chat.py event post review --from alice --type capability --harness generic-shell

Root precedence is --root > $AGENT_CHAT_ROOT > ~/agent-chat. Put the global flag before the subcommand: python chat.py --root "/shared/chat" channels. Run python chat.py <cmd> --help for all flags.

How it works

• Channels — one folder per group chat; make as many as needed with init.
• Messages — numbered Markdown files with frontmatter and immutable replies.
• Cursors — read/wait show only new relevant messages.
• Tasks — JSON records with dependencies, readiness, status and acceptance.
• Leases — owner-bound claims with expiry and explicit stale recovery.
• Path locks — normalized workspace-relative ownership records with conflict checks.
• State — deterministic derived state.md; compaction never replaces source records.
• Events — versioned capability/status JSON carried through ordinary messages.
• Atomicity — filesystem transactions, audit events and recovery markers protect concurrent work.

Agent Chat is a coordination data layer. It does not execute agents, assign models, approve permissions, run MCP/ACP, or wake another process. No command or hook calls an LLM, embedding/rerank provider, graph service, relay, or Cloudflare gateway. state/compact derive summaries from local records, not model-generated text; capability/status events describe a peer and do not invoke it.

Two modes, two budgets

• Live swarm — N sessions run concurrently and use wait for wall-clock parallelism.
• Async handoff / audit — a session posts an artifact summary for the next session.

Both modes use the same file-backed protocol and remain auditable.

Install & distribution

• As a CLI — pipx install agent-chat-plugin, then run agent-chat <cmd>. For one-off execution use uvx --from agent-chat-plugin agent-chat <cmd> on each invocation; uvx does not install a persistent agent-chat command.
• As a standalone Skill — copy the root SKILL.md, chat.py, and the entire agent_chat/ directory together into a compatible Skills directory. Copying only chat.py breaks task, lease, path-lock, and state commands.
• As a Claude Code plugin — install the marketplace package from claude-plugins. Keep .claude-plugin/, hooks/, commands/, skills/, chat.py, and agent_chat/ together; the plugin skill is skills/agent-chat/SKILL.md.

PyPI installs the CLI and its Python modules, not the skill, slash command, or lifecycle hooks. Use the checkout/plugin distribution for those assets.

All participants must address the same channel root on a filesystem with the required atomic replacement and locking semantics. Separate home/company ~/agent-chat directories are separate inboxes; this package does not sync machines or install a background service. Give each participant a distinct AGENT_CHAT_NAME for hooks; CLI identities are explicit --from/--as flags. Set environment values before starting the host, not by changing its model or MCP configuration.

Optional inbox hooks

hooks/hooks.json registers three Claude Code lifecycle commands. Python hook scripts can be invoked by absolute checkout path in another host, but that host must explicitly support or adapt their lifecycle/output contract:

Set AGENT_CHAT_ROOT and optionally comma-separated AGENT_CHAT_CHANNELS to restrict checks to relevant channels (empty means all discovered channels). Malformed channel names are skipped without suppressing other configured inboxes. Hooks only print when unread messages are relevant to the current identity, bound each notice to a small stdout budget, and never advance cursors, read message bodies into notices, reply, block a turn, or wake a peer. read and successful wait advance cursors.

The scripts prefer non-empty CLAUDE_PLUGIN_ROOT; otherwise they resolve chat.py beside their own hooks/ directory. An unresolved plugin root skips with a one-line stderr diagnostic; hook failures always exit 0. Quote paths: python "/path/to/agent-chat-plugin/hooks/session_inbox.py".

A portable script is not an installed OMP/native integration. Verify each host's explicit invocation and rendered notice; CLI installation or a successful source check alone does not prove hooks are loaded on home or company.

See CONTRIBUTING.md for developer setup and runtime layout.

Status

The reference implementation covers file-backed messages, cursors, token-free wait, structured tasks/dependencies, leases, normalized path locks, derived state and adapter-neutral capability/status events. MCP wrappers, ACP/wake bridges and agent execution remain separate future designs.

License

Apache-2.0.