concord-mcp

Purpose

Concord MCP is an open-source, local-first communication and coordination layer for AI coding agents. It enables coding agents running in different harnesses (such as Claude Code, Codex, Cursor, Gemini CLI, Grok Build, Goose) to discover each other, exchange messages in real time, and divide work within the same repository, without a human relaying context in between.

It is explicitly positioned as a shared layer around agents, not another autonomous agent or orchestrator. Its core goal is: after a message is delivered, keep collaboration reliable through shared work state.

Main capabilities

• Real-time messaging: Send real-time messages across harnesses. Prompts use update_work of operation: "prompt", specifying the target to_agent_id, content, and idempotency_key; replies use operation: "reply" and reply_to_message_id.
• Work scope declaration and overlap detection: Detect overlapping work before agents edit.inspect_work shows which agents are currently present and flags stale claims (that is, active claims whose owner has left and has not handed off).
• Shared decisions and task memory: Retain decisions and support task handoff with evidence.
• Ownership and handoff: Lifecycle change operations use the task's monotonic version as expected_version; when two agents operate on the same version, only the first transition succeeds. After assignment, work remains in assigned state until accepted by the designated agent using transfer_work of action: "accept" ; handoff proposals likewise retain the sender's ownership until the receiver accepts. Every ownership change is retained in an append-only audit history.
• Online status: Write operations accept agent_id, and staying online can be maintained through work alone.
• Local TUI dashboard:concord dashboard is a read-only full-screen local TUI that refreshes every second from the shared SQLite workspace, displaying agents, tasks, alerts, context, and timeline within a fixed terminal viewport. Use Tab to switch panels, j / k or the arrow keys to select work, / to filter, ? to view help, and q to quit.
• Update checks: Concord checks daily and prompts about available updates in the CLI, MCP tools, and dashboard;concord setup can install after confirmation, andCONCORD_NO_UPDATE_CHECK=1 can disable checks.

Usage

Installation and configuration

Running concord setup creates a local .concord/ workspace, registers the MCP server for Claude, Cursor, Gemini, Grok, and Codex (.mcp.json、.cursor/mcp.json、.gemini/settings.json、.grok/config.toml and ~/.codex/config.toml), and writes Concord's tool instructions into the client configuration (CLAUDE.md、AGENTS.md、.codex/、.cursor/rules/). It merges into existing configuration rather than replacing it, and can be safely run repeatedly.

Setup also detects supported clients and attempts to independently install their global Concord adapters. Use --no-adapters to skip that step, or use --require-adapters in managed installations so that it fails when degradation is supported. Passing --no-mcp writes only the workspace and instructions, leaving MCP registration for you to manage yourself.

On the first interactive run of concord setup , it asks whether to let agents use Concord in repositories where setup has never been run (default yes). The answer is saved in ~/.concord/config.json；concord setup --global or --no-global and can be changed.

When global mode is enabled, Concord registers itself at the user level for each installed agent and adds a brief Concord section to its user instructions file (~/.claude/CLAUDE.md、~/.codex/AGENTS.md、~/.gemini/GEMINI.md, Goose's .goosehints; Cursor receives it through its global session hook). It does not write into these repositories: its work is kept in ~/.concord/global.db, one project per repository, named by git remote. Sessions not in any repository share a common project. Repositories that have already been set up keep everything in their own .concord/ . Turning off global mode removes exactly what it added.

Usage flow

Restart the agent clients, then have two of them work in the same repository. Concord provides them with a shared workspace and makes reachable sessions available for direct prompting and replies.

Live delivery depends on the receiving harness and session state. Run concord adapters status to see which installed agents are reachable and how messages will be delivered.

Adapters with receipts will steer a busy turn or start an idle turn. Hook-only integrations leave a persistent pull message and state that limitation in the result. When the specified agent has no reachable endpoint, delivery fails immediately; Concord does not silently reroute.

concord adapters status reports each harness separately, including its monitor/controller type, verified reachability, required actions, and version probe results.concord adapters install、doctor and uninstall provide the same global lifecycle outside of repository setup.

Workspace resolution

Concord automatically resolves the repository workspace. Operations return its workspace_id and repository root so clients can detect misrouted calls; when one server coordinates multiple roots, that id can be passed explicitly.

SQLite is the local source of truth, stored in the .concord/ at the root of the repository where the work is done. The MCP server resolves that root in the following order:CONCORD_REPO_ROOT(if set), Claude Code's CLAUDE_PROJECT_DIR(Claude Code sets this automatically, even for user-level servers), then its working directory—so every agent in the same repository shares one store. When the working directory of the location where the server runs is not inside a repository, set CONCORD_REPO_ROOT.

Linked Git worktrees follow Git's commondir metadata to point to the main checkout, so the main checkout and all linked worktrees intentionally share one Concord database and workspace id.

To restrict explicit workspace selection, set CONCORD_ALLOWED_ROOTS to a path-separated list of allowed repository roots. Without an allowlist, the decoded root must still exist and be a directory.

Git ignore

concord setup writes .concord/.gitignore, with the content *, so the generated workspace ignores itself and stays local without editing the repository's shared .gitignore. Teams that want selected artifacts included in a PR can add negation rules in that file (setup preserves existing rules and only ensures the * wildcard), or force-add human-readable files. Repositories set up by Concord 0.10.5 or earlier also have a .gitignore rule in the root .concord/ ; it must be removed before negation rules in .concord/.gitignore take effect.

CLI

Concord supports both typed MCP tools and a regular CLI. Agents that support MCP can call the tools directly; humans and CLI-oriented agents can use the same shared workspace through the concord command.

--repo and --workspace are globally mutually exclusive options. The CLI uses the same CONCORD_REPO_ROOT → CLAUDE_PROJECT_DIR → Working directory priority, and identical link worktree normalization.

Applicable scenarios

• Multiple coding agents work in parallel in the same repository and need to avoid edit conflicts.
• Agents from different harnesses need to communicate with each other, divide work, and hand off tasks.
• You want to retain decision records, ownership change audits, and handoffs with evidence.
• You need a local-first coordination solution that does not depend on a hosted synchronization service.

Limitations

• It is not an orchestrator, code reviewer, hosted synchronization service, memory vector database, or autonomous coding agent.
• There is no universal /concord slash command—commands vary by client. Concord works on any MCP-capable client through MCP tools plus installed instructions.
• Real-time delivery depends on the receiving harness and session state; hook-only integrations can only leave persistent pull messages.
• When the specified agent has no reachable endpoint, delivery fails immediately and is not silently rerouted.
• Telemetry: Concord sends product and coordination telemetry to getconcord.ai, including random installation/invocation identifiers, irreversible per-installation workspace and task-flow pseudonyms, Concord/Node/platform versions, normalized client metadata, operation names/results/durations, aggregate overlap/edit protection results, message delivery stages and latency, task lifecycle transitions and elapsed time, and explicitly reported acceptance, integration, human intervention, and rework outcomes. Concord never sends code, raw files or repository paths, remotes, usernames, raw task or agent identifiers, message identifiers or content, command arguments, tool inputs/outputs, or task content. The receiving server stores the request IP address and derives/stores a country code; these server-side fields currently have no automatic expiration. Setting CONCORD_TELEMETRY_DISABLED=1(or DO_NOT_TRACK=1) disables telemetry. Delivery is best-effort and never causes a Concord operation to fail.