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.

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 inf

... View full README on GitHub