agent-comm

agent-comm

Agent-agnostic intercommunication system. Lets AI coding agents — Claude Code, Codex CLI, Gemini CLI, Aider, or any custom tool — talk to each other, share state, and coordinate work in real time.

Light Theme	Dark Theme

Why

When you run multiple AI agents on the same codebase — code review in one terminal, implementation in another, testing in a third — they have no idea the others exist. They duplicate work, create merge conflicts, and miss context.

	Without agent-comm	With agent-comm
Discovery	Agents don't know others exist	Agents register with skills, discover by capability
Coordination	Edit the same file, create conflicts	Lock files/regions, divide work
Communication	None — each agent works blind	Messages, channels, broadcasts
State sharing	Duplicate work, missed context	Shared KV store with atomic CAS
Visibility	No idea what's happening	Real-time dashboard + activity feed shows everything

agent-comm gives them a shared communication layer:

• Agents register with a name, capabilities, and skills so others can discover them
• They discover each other by skill or tag for dynamic task routing
• They exchange messages (direct, broadcast, or channel-based) to coordinate, with importance levels (low/normal/high/urgent) and optional ack
• They poll their inbox with a blocking wait (comm_poll) so mid-flight peer signals are consumed without busy-looping
• They share state (a key-value store with atomic CAS) for locks, flags, and progress
• They log activity events (commits, test results, file edits) to a shared feed
• They detect stuck agents — alive (heartbeat OK) but not making progress
• They serialize file edits via the system-layer file-coord hook (see below) so parallel agents on shared files cannot clobber each other
• A web dashboard shows everything in real time, including an Activity Feed tab

It works with any agent that supports MCP (stdio transport) or can make HTTP requests (REST API).

Why hooks, not just MCP tools

The MCP tools (comm_state, etc.) give agents the primitives to coordinate, but they don't enforce coordination — the agent has to remember to call them. Our bench measured what happens when you rely on the model's discretion: even with strict procedural prompting, Claude follows the protocol on the first claim cycle then drifts back to "be helpful, finish the task." Soft coordination is unreliable.

The fix is a pair of PreToolUse hooks shipped in scripts/hooks/: file-coord intercepts every Edit/Write/MultiEdit and claims the file via REST POST /api/state/file-locks/<path>/cas (blocks the edit if another agent holds the lock); bash-guard intercepts git commit, git push, npm install, npm test, builds, migrations, and dev-server starts and blocks/warns when they would conflict with another session's WIP. The protocol becomes infrastructure, not a prompt the agent might ignore.

The bench's headline pilot is multi-term-commit — directly modeling the daily pain of two terminal sessions on the same project. Session A edits two files but doesn't commit. Session B then edits two other files and runs git commit -am "my work". Without the hook, B's commit silently includes A's WIP. With the hook, B's commit is blocked at the bash layer with an actionable message, and B reacts (selective staging, restore, or coordinate). Bench result: