agent-coord
v2matosevic/agent-coord
Sincronização de agentes IA para não pisar um no outro
Ver no GitHubMachine-wide coordination layer so multiple AI coding agents (Claude Code, Codex, ...) don't step on each other: shared presence, self-healing file locks, a universal git commit guard, agent-to-agent messaging, and duplicate-work detection.
Instalação
npx convez-ai v2matosevic/agent-coord1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Evitar conflitos ao rodar múltiplos agentes de código na mesma máquina
- Coordenar edições em repositórios compartilhados
- Prevenir commits conflitantes entre agentes simultâneos
Veredito

Solução técnica sólida para um problema real: múltiplos agentes IA pisando um no outro. Bem arquitetado (SQLite + zero deps core), com setup semelhante a instalação de ferramenta legítima. Altamente especializado — útil apenas para quem roda agentes de código em paralelo na mesma máquina.
README
A tradução para o português deste README ainda está na fila.
agent-coord
A machine-wide coordination layer so multiple AI coding agents running at once don't step on each other. Shared presence, file locks, a universal git commit guard, agent-to-agent messaging, and duplicate-work detection — across every terminal, window, and repo on your machine.

Built on Node's built-in node:sqlite (WAL). The hooks and CLI are zero-dependency;
only the MCP server pulls one package (@modelcontextprotocol/sdk). No native
build, no daemon, no SPOF — it fails open but loud, so a glitch never freezes
your work.
Why
Every AI coding agent is an island: a Claude Code session, a Codex session, and a Cursor agent each see only their own context and their own working tree. Run a few at once on one repo — or sharing one dev port / DB / deploy — and they edit the same file simultaneously, duplicate each other's work, make contradictory decisions, and collide on shared singletons. That's a distributed-systems failure with no coordination primitive. This adds one.
Install
Option A — let your coding agent do it (recommended)
Clone the repo, open it in your agent (Claude Code, Codex, Cursor, …), and paste:
Read
AGENTS.mdin this repo and set up agent-coord for me: install it, run the health check, and tell me what's live and what I need to do next.
The agent follows the AGENTS.md runbook — installs, verifies
(doctor 9/9), and reports back. That's it.
git clone https://github.com/v2matosevic/agent-coord.git
cd agent-coord
# then open this folder in your agent and paste the message above
Option B — one command yourself
node setup.mjs # any OS — Windows / macOS / Linux
or, on Windows (also builds the VS Code Fleet panel):
./setup.ps1
Both are idempotent (safe to re-run) and fail-soft (skip a step if a CLI isn't installed). They wire Claude Code hooks + statusline, the global git pre-commit net, and the MCP server into Claude and Codex, then run the health check. Requires Node ≥ 22. Open new agent sessions afterward to pick it up.
Verify any time:
node cli/doctor.mjs # expect: 9/9 checks passed
What you get
| Agent | What it gets |
|---|---|
| Claude Code | Full enforcement — a PreToolUse hook claims the file you're about to edit or blocks it (exit 2) if a peer holds it. Bash guard reserves dev port / DB / deploy. Statusline shows the fleet and your own identity. MCP tools for active coordination. |
| Codex | MCP awareness + model-invoked claims; enforced at commit by the global pre-commit net. |
| Any committer (Codex / Cursor / Aider / manual) | The global git pre-commit rejects a commit that stages a file another live agent is actively editing. |
How it works
flowchart LR
subgraph agents [Agents on one machine]
CC["Claude Code<br/>(hooks: pre-write block)"]
CX["Codex / Cursor / …<br/>(MCP awareness)"]
GIT["Any committer<br/>(global git pre-commit net)"]
end
STORE[("~/.agent-coord<br/>SQLite (WAL)<br/>presence · leases · messages · tasks")]
CC <--> STORE
CX <--> STORE
GIT <--> STORE
STORE --> OBS["statusline · terminal watch · browser dashboard<br/>VS Code panel · macOS menu bar"]
No daemon — every hook, CLI, and MCP call opens the same SQLite store directly
(WAL, BEGIN IMMEDIATE for atomic claims) and exits. If anything breaks, the
guards fail open but loud: you lose coordination, never your work.
The coordination model
- Rooms & resources. A room = a repo (branch-independent), the unit of file
conflict. Resources = machine-wide singletons (
port:3000,db:dev,deploy:primary) — two agents in different repos still contend for them. - Self-healing locks (warm/cold). A file lock only blocks while it's warm — the holder edited that file in the last few minutes. Once they move on it goes cold and a waiting agent takes it automatically — no force-release, no asking the human to unlock. Active concurrent edits still block.
- Talk that reaches heads-down agents. Agents leave each other messages
(
post_message, workspace-scoped). Unread messages surface not just at the next prompt but between tool calls, so a peer can reach an agent mid-build. - Shared task board. Agents
claim_taskdiscrete units of work (atomic — one winner under a race), so a peer simply sees a task is taken instead of two agents building the same thing. Title dedup, dead-owner auto-reclaim, and adepends_onlist that marks tasks blocked/ready.node cli/tasks.mjsshows it. - Duplicate-work de-confliction. Beyond the board,
announce_intentwarns the later starter that a peer is already on similar work (text-similarity). The deterministic tiebreaker (who started first) decides who yields; the later starter is advised, then auto-blocked if it keeps duplicating. Ask a peer to stand down withrequest_yieldinstead of fighting locks. - One identity per session. Each agent is a single, stable identity across its hooks and its MCP tools — so locks, messages, and commit provenance all line up (no ghost twins, and the statusline tells you which terminal is which agent).
- Autonomous push hand-off. Told to push a history with other agents' commits,
an agent runs
pending_push_review(author + live status + verdict per commit) instead of asking you.
Commands
node cli/doctor.mjs # 9-point health check
node cli/status.mjs # one-shot fleet table
node cli/watch.mjs # live fleet in the terminal (2s)
node cli/dashboard.mjs [port] # live browser dashboard (default :7777)
node cli/tasks.mjs # shared task board (--add "title" | --done <id>)
node cli/worktree.mjs new # isolate an agent: own worktree + branch + port
node cli/insights.mjs [--since 7d] # retro: files edited by 2+ agents + conflicts
node cli/digest.mjs [--since 7d] # write a durable per-project hotspot digest (~/.agent-coord/digests/)
node cli/pending-push.mjs # who authored the unpushed commits + push verdicts
node cli/release.mjs --file <p> | --resource <id> | --agent <id> | --all
All CLIs run under node --disable-warning=ExperimentalWarning <script>.
MCP tools (Claude + Codex)
whoami, announce_intent, list_active_agents, get_global_state,
check_conflicts, claim_files, release_files, claim_resource,
release_resource, log_activity, post_message, read_messages,
pending_push_review, ask_agent, check_replies, reply, request_yield,
query_history, list_tasks, claim_task, update_task.
VS Code extension (optional)
An Activity Bar Fleet panel — every agent across every repo (who, file held,
leases, queue, activity) + an "Open in Tab" view. setup.ps1 builds and installs
it; see vscode-extension/README.md. It reads the
store via your system node (no extension dependencies).
macOS menu bar (optional)
The Mac-native counterpart to the VS Code panel: a SwiftBar/xbar plugin that
lives in the menu bar showing the live fleet — agent count (🟢 / 🔴 when files are
contended / ⚠️ when degraded), a dropdown of agents grouped by repo with the file
each holds, contended files, resource leases, the task board, and a link to the
dashboard. node setup.mjs generates it on macOS; or run it directly:
node cli/install-macos-menubar.mjs # generates the plugin + installs it if SwiftBar/xbar is found
Needs SwiftBar (brew install --cask swiftbar) or xbar.
The plugin is read-only and resolves node itself (GUI apps don't inherit your
fnm/Homebrew PATH), so it works regardless of how Node is installed.
Desktop notifications (macOS)
Native banners when you're blocked on a file, a peer messages you, or asks
you to yield — so a heads-down human hears what the system already tells
heads-down agents. On by default on macOS (AGENT_COORD_NOTIFY=0 mutes, =1
forces on); uses terminal-notifier if installed, else the built-in osascript.
Fired from the hooks, non-blocking and fail-safe, with same-event alerts deduped
within a short window so a retried edit never spams.
Tests
npm test # full suite, each test in an isolated throwaway store
node test/run-all.mjs messages # filter by name
CI runs the suite on Windows, macOS, and Linux (Node 22 + 24) on every push and PR.
Uninstall
git config --global --unset core.hooksPath # prior value in ~/.agent-coord/git-hookspath.prior
claude mcp remove agent-coord --scope user
codex mcp remove agent-coord
# restore a ~/.claude/settings.json.bak.* and delete ~/.agent-coord/
Honest limits
Coordination is advisory-by-default; the only hard blocks are Claude Code
PreToolUse (pre-write) and the git pre-commit hook (at commit, every committer).
Non-Claude agents get awareness via MCP + the commit net, not pre-write blocking.
Locks are whole-file. A single-user machine is assumed — there's no auth boundary
in the store. See DESIGN.md §9 for the full list.
Docs
AGENTS.md— install/operation runbook for AI agents.docs/SYSTEM.md— complete as-built reference.docs/AGENT-PROTOCOL.md— how agents should coordinate.DESIGN.md— original architecture & rationale.docs/FUTURE.md— roadmap beyond the macOS expansion.CHANGELOG.md— what's been built.docs/LIVE-TEST.md— first live two-agent validation.
Contributing & security
PRs welcome — read CONTRIBUTING.md first (zero-dependency
rule, fail-open invariant, test expectations). Security model and how to report
a vulnerability: SECURITY.md. Licensed MIT.
Platform: developed on Windows 11 + PowerShell 7 and also installed & proven on
macOS (Apple Silicon) — both with Claude Code and Codex. The core (Node +
node:sqlite + the hooks/MCP/CLI) is portable; node setup.mjs runs on
Windows/macOS/Linux (doctor 9/9, suite 17/17 on macOS). The few Windows-specific
runtime paths branch on process.platform, so each OS keeps its native behaviour.
Single-user machine by design.