{"id":50777841,"url":"https://github.com/v2matosevic/agent-coord","last_synced_at":"2026-06-12T01:03:30.475Z","repository":{"id":362159157,"uuid":"1257377778","full_name":"v2matosevic/agent-coord","owner":"v2matosevic","description":"Machine-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.","archived":false,"fork":false,"pushed_at":"2026-06-10T10:39:36.000Z","size":465,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T12:20:36.272Z","etag":null,"topics":["ai-agents","claude","claude-code","codex","coding-agents","coordination","cursor","developer-tools","git-hooks","mcp","model-context-protocol","multi-agent","sqlite"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/v2matosevic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-02T16:11:06.000Z","updated_at":"2026-06-10T10:39:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/v2matosevic/agent-coord","commit_stats":null,"previous_names":["v2matosevic/version2-agent-coordination","v2matosevic/agent-coord"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/v2matosevic/agent-coord","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/v2matosevic%2Fagent-coord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/v2matosevic%2Fagent-coord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/v2matosevic%2Fagent-coord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/v2matosevic%2Fagent-coord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/v2matosevic","download_url":"https://codeload.github.com/v2matosevic/agent-coord/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/v2matosevic%2Fagent-coord/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34224103,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude","claude-code","codex","coding-agents","coordination","cursor","developer-tools","git-hooks","mcp","model-context-protocol","multi-agent","sqlite"],"created_at":"2026-06-12T01:03:30.220Z","updated_at":"2026-06-12T01:03:30.446Z","avatar_url":"https://github.com/v2matosevic.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-coord\n\n[![CI](https://github.com/v2matosevic/agent-coord/actions/workflows/ci.yml/badge.svg)](https://github.com/v2matosevic/agent-coord/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![Node ≥ 22](https://img.shields.io/badge/node-%E2%89%A5%2022-brightgreen.svg)](https://nodejs.org)\n![Platforms](https://img.shields.io/badge/platform-windows%20%7C%20macos%20%7C%20linux-8a8076.svg)\n\n**A machine-wide coordination layer so multiple AI coding agents running at once\ndon't step on each other.** Shared presence, file locks, a universal git commit\nguard, agent-to-agent messaging, and duplicate-work detection — across every\nterminal, window, and repo on your machine.\n\n![The live dashboard: agents grouped by repo, the file each one holds, resource leases, and the activity feed](./docs/assets/dashboard.png)\n\nBuilt on Node's built-in `node:sqlite` (WAL). The hooks and CLI are **zero-dependency**;\nonly the MCP server pulls one package (`@modelcontextprotocol/sdk`). No native\nbuild, no daemon, no SPOF — it fails *open but loud*, so a glitch never freezes\nyour work.\n\n---\n\n## Why\n\nEvery AI coding agent is an island: a Claude Code session, a Codex session, and a\nCursor agent each see only their own context and their own working tree. Run a few\nat once on one repo — or sharing one dev port / DB / deploy — and they edit the\nsame file simultaneously, duplicate each other's work, make contradictory\ndecisions, and collide on shared singletons. That's a distributed-systems failure\nwith **no coordination primitive**. This adds one.\n\n---\n\n## Install\n\n### Option A — let your coding agent do it (recommended)\n\nClone the repo, open it in your agent (Claude Code, Codex, Cursor, …), and paste:\n\n\u003e **Read `AGENTS.md` in this repo and set up agent-coord for me: install it, run\n\u003e the health check, and tell me what's live and what I need to do next.**\n\nThe agent follows the [`AGENTS.md`](./AGENTS.md) runbook — installs, verifies\n(`doctor` 9/9), and reports back. That's it.\n\n```bash\ngit clone https://github.com/v2matosevic/agent-coord.git\ncd agent-coord\n# then open this folder in your agent and paste the message above\n```\n\n### Option B — one command yourself\n\n```bash\nnode setup.mjs        # any OS — Windows / macOS / Linux\n```\nor, on Windows (also builds the VS Code Fleet panel):\n```powershell\n./setup.ps1\n```\n\nBoth are **idempotent** (safe to re-run) and **fail-soft** (skip a step if a CLI\nisn't installed). They wire Claude Code hooks + statusline, the global git\npre-commit net, and the MCP server into Claude and Codex, then run the health\ncheck. **Requires Node ≥ 22.** Open new agent sessions afterward to pick it up.\n\nVerify any time:\n```bash\nnode cli/doctor.mjs        # expect: 9/9 checks passed\n```\n\n---\n\n## What you get\n\n| Agent | What it gets |\n|---|---|\n| **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. |\n| **Codex** | MCP awareness + model-invoked claims; enforced at commit by the global pre-commit net. |\n| **Any committer** (Codex / Cursor / Aider / manual) | The **global git pre-commit** rejects a commit that stages a file another live agent is actively editing. |\n\n### How it works\n\n```mermaid\nflowchart LR\n    subgraph agents [Agents on one machine]\n        CC[\"Claude Code\u003cbr/\u003e(hooks: pre-write block)\"]\n        CX[\"Codex / Cursor / …\u003cbr/\u003e(MCP awareness)\"]\n        GIT[\"Any committer\u003cbr/\u003e(global git pre-commit net)\"]\n    end\n    STORE[(\"~/.agent-coord\u003cbr/\u003eSQLite (WAL)\u003cbr/\u003epresence · leases · messages · tasks\")]\n    CC \u003c--\u003e STORE\n    CX \u003c--\u003e STORE\n    GIT \u003c--\u003e STORE\n    STORE --\u003e OBS[\"statusline · terminal watch · browser dashboard\u003cbr/\u003eVS Code panel · macOS menu bar\"]\n```\n\nNo daemon — every hook, CLI, and MCP call opens the same SQLite store directly\n(WAL, `BEGIN IMMEDIATE` for atomic claims) and exits. If anything breaks, the\nguards fail **open but loud**: you lose coordination, never your work.\n\n### The coordination model\n\n- **Rooms \u0026 resources.** A *room* = a repo (branch-independent), the unit of file\n  conflict. *Resources* = machine-wide singletons (`port:3000`, `db:dev`,\n  `deploy:primary`) — two agents in different repos still contend for them.\n- **Self-healing locks (warm/cold).** A file lock only blocks while it's *warm* —\n  the holder edited that file in the last few minutes. Once they move on it goes\n  *cold* and a waiting agent takes it **automatically** — no force-release, no\n  asking the human to unlock. Active concurrent edits still block.\n- **Talk that reaches heads-down agents.** Agents leave each other messages\n  (`post_message`, workspace-scoped). Unread messages surface not just at the next\n  prompt but **between tool calls**, so a peer can reach an agent mid-build.\n- **Shared task board.** Agents `claim_task` discrete units of work (atomic — one\n  winner under a race), so a peer simply *sees* a task is taken instead of two\n  agents building the same thing. Title dedup, dead-owner auto-reclaim, and a\n  `depends_on` list that marks tasks blocked/ready. `node cli/tasks.mjs` shows it.\n- **Duplicate-work de-confliction.** Beyond the board, `announce_intent` warns the\n  later starter that a peer is already on similar work (text-similarity). The\n  deterministic tiebreaker (who started first) decides who yields; the later\n  starter is advised, then auto-blocked if it keeps duplicating. Ask a peer to\n  stand down with `request_yield` instead of fighting locks.\n- **One identity per session.** Each agent is a single, stable identity across its\n  hooks and its MCP tools — so locks, messages, and commit provenance all line up\n  (no ghost twins, and the statusline tells you which terminal is which agent).\n- **Autonomous push hand-off.** Told to push a history with other agents' commits,\n  an agent runs `pending_push_review` (author + live status + verdict per commit)\n  instead of asking you.\n- **Decisions stay decided.** `record_decision` pins a project-level choice\n  (\"httpOnly JWT cookies, no localStorage\") — broadcast to live peers, shown to\n  every arriving agent, latest-per-topic. The failure it kills: two agents making\n  contradictory architectural choices in *different* files, which no file lock\n  can see.\n- **Searchable memory.** Everything above accumulates into the store, and\n  `search` (FTS5 full-text) answers \"has this been discussed / decided / built\n  already?\" across messages, decisions, and tasks — best match first, not just\n  chronological dumps.\n\n---\n\n## Commands\n\n```bash\nnode cli/doctor.mjs                 # 9-point health check\nnode cli/status.mjs                 # one-shot fleet table\nnode cli/watch.mjs                  # live fleet in the terminal (2s)\nnode cli/dashboard.mjs [port]       # live browser dashboard (default :7777)\nnode cli/tasks.mjs                  # shared task board (--add \"title\" | --done \u003cid\u003e)\nnode cli/worktree.mjs new           # isolate an agent: own worktree + branch + port\nnode cli/insights.mjs [--since 7d]  # retro: files edited by 2+ agents + conflicts\nnode cli/digest.mjs [--since 7d]    # write a durable per-project hotspot digest (~/.agent-coord/digests/)\nnode cli/pending-push.mjs           # who authored the unpushed commits + push verdicts\nnode cli/search.mjs \"\u003cquery\u003e\"       # full-text search messages/decisions/tasks (--kinds, --limit)\nnode cli/release.mjs --file \u003cp\u003e | --resource \u003cid\u003e | --agent \u003cid\u003e | --all\n```\nAll CLIs run under `node --disable-warning=ExperimentalWarning \u003cscript\u003e`.\n\n## MCP tools (Claude + Codex)\n\n`whoami`, `announce_intent`, `list_active_agents`, `get_global_state`,\n`check_conflicts`, `claim_files`, `release_files`, `claim_resource`,\n`release_resource`, `log_activity`, `post_message`, `read_messages`,\n`pending_push_review`, `ask_agent`, `check_replies`, `reply`, `request_yield`,\n`query_history`, `list_tasks`, `claim_task`, `claim_next_task`, `update_task`,\n`record_decision`, `list_decisions`, `search`.\n\n## VS Code extension (optional)\n\nAn Activity Bar **Fleet** panel — every agent across every repo (who, file held,\nleases, queue, activity) + an \"Open in Tab\" view. `setup.ps1` builds and installs\nit; see [`vscode-extension/README.md`](./vscode-extension/README.md). It reads the\nstore via your system `node` (no extension dependencies).\n\n## macOS menu bar (optional)\n\nThe Mac-native counterpart to the VS Code panel: a **SwiftBar/xbar plugin** that\nlives in the menu bar showing the live fleet — agent count (🟢 / 🔴 when files are\ncontended / ⚠️ when degraded), a dropdown of agents grouped by repo with the file\neach holds, contended files, resource leases, the task board, and a link to the\ndashboard. `node setup.mjs` generates it on macOS; or run it directly:\n\n```bash\nnode cli/install-macos-menubar.mjs   # generates the plugin + installs it if SwiftBar/xbar is found\n```\n\nNeeds [SwiftBar](https://swiftbar.app) (`brew install --cask swiftbar`) or xbar.\nThe plugin is read-only and resolves `node` itself (GUI apps don't inherit your\nfnm/Homebrew PATH), so it works regardless of how Node is installed.\n\n## Desktop notifications (macOS)\n\nNative banners when you're **blocked** on a file, a **peer messages** you, or asks\nyou to **yield** — so a heads-down *human* hears what the system already tells\nheads-down *agents*. On by default on macOS (`AGENT_COORD_NOTIFY=0` mutes, `=1`\nforces on); uses `terminal-notifier` if installed, else the built-in `osascript`.\nFired from the hooks, non-blocking and fail-safe, with same-event alerts deduped\nwithin a short window so a retried edit never spams.\n\n## Tests\n\n```bash\nnpm test                          # full suite, each test in an isolated throwaway store\nnode test/run-all.mjs messages    # filter by name\n```\n\nCI runs the suite on Windows, macOS, and Linux (Node 22 + 24) on every push and PR.\n\n## Uninstall\n\n```bash\ngit config --global --unset core.hooksPath   # prior value in ~/.agent-coord/git-hookspath.prior\nclaude mcp remove agent-coord --scope user\ncodex mcp remove agent-coord\n# restore a ~/.claude/settings.json.bak.*  and delete ~/.agent-coord/\n```\n\n## How it compares\n\nMost multi-agent tooling solves concurrency by **isolation**: a git worktree or\ncontainer per agent (claude-squad, container-use, vibe-kanban, ccmanager…).\nThat works — until the agents are supposed to be working on the *same* tree, or\nthey share a dev port, a database, a deploy target. The few projects that do\nshared-tree coordination (mcp_agent_mail, swarm-protocol) keep their file\nleases **advisory**: the agent is *asked* to check before writing.\n\nagent-coord's stance is **enforcement at the chokepoints**: the `PreToolUse`\nhook *blocks* the write (exit 2) while a peer's lease is warm, risky shell\ncommands claim machine-wide resources before they run, and the git\npre-commit/pre-push hooks catch every committer — including agents with no\nhook support at all. Awareness (presence, messages, board, decisions, search)\nrides on top of that floor, and the locks self-heal so enforcement never needs\na human with a key. Isolation tools and agent-coord compose, by the way: a\nworktree-per-agent setup still shares ports, DBs, and pushes.\n\n## Honest limits\n\nCoordination is advisory-by-default; the only **hard** blocks are Claude Code\n`PreToolUse` (pre-write) and the git pre-commit hook (at commit, every committer).\nNon-Claude agents get awareness via MCP + the commit net, not pre-write blocking.\nLocks are whole-file. A single-user machine is assumed — there's no auth boundary\nin the store. See [`DESIGN.md` §9](./DESIGN.md) for the full list.\n\n## Docs\n\n- [`AGENTS.md`](./AGENTS.md) — install/operation runbook for AI agents.\n- [`docs/SYSTEM.md`](./docs/SYSTEM.md) — complete as-built reference.\n- [`docs/AGENT-PROTOCOL.md`](./docs/AGENT-PROTOCOL.md) — how agents should coordinate.\n- [`DESIGN.md`](./DESIGN.md) — original architecture \u0026 rationale.\n- [`docs/FUTURE.md`](./docs/FUTURE.md) — roadmap beyond the macOS expansion.\n- [`CHANGELOG.md`](./CHANGELOG.md) — what's been built.\n- [`docs/LIVE-TEST.md`](./docs/LIVE-TEST.md) — first live two-agent validation.\n\n## Contributing \u0026 security\n\nPRs welcome — read [`CONTRIBUTING.md`](./CONTRIBUTING.md) first (zero-dependency\nrule, fail-open invariant, test expectations). Security model and how to report\na vulnerability: [`SECURITY.md`](./SECURITY.md). Licensed [MIT](./LICENSE).\n\n---\n\nPlatform: developed on **Windows 11 + PowerShell 7** and also installed \u0026 proven on\n**macOS (Apple Silicon)** — both with Claude Code and Codex. The core (Node +\n`node:sqlite` + the hooks/MCP/CLI) is portable; `node setup.mjs` runs on\nWindows/macOS/Linux (doctor 9/9, suite 17/17 on macOS). The few Windows-specific\nruntime paths branch on `process.platform`, so each OS keeps its native behaviour.\nSingle-user machine by design.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fv2matosevic%2Fagent-coord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fv2matosevic%2Fagent-coord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fv2matosevic%2Fagent-coord/lists"}