mcp-git-coord

Cut your $200/mo Claude Max token usage in half. Every AI coding session wastes tokens re-exploring code your last session already understood. mcp-git-coord fixes this — plus stops your team's agents from stepping on each other.

Two problems, one tool

1. Token waste — agents re-explore the same code every session

Every time you start a new Claude Code / Cursor session, the agent reads hundreds of files to understand your codebase. That's thousands of tokens burned on knowledge that was already built in the last session — then thrown away.

.mi context files fix this. Each subdirectory maintains a .mi/ folder with pre-built understanding: architecture, data flow, key files, gotchas. Your agent reads a 200-line context doc instead of re-exploring 50 source files. Hooks remind the agent to read before coding and update after changing.

2. Coordination — agents working in silos create conflicts

When multiple developers use AI coding tools on the same repo, agents don't know about each other's work. They modify the same files, produce conflicting changes, and resolve merge conflicts by guessing — silently deleting features other people built.

Coordination tools fix this. Agents register their intent before working, detect conflicts before code is written, and provide human-controlled merge resolution with full team context.

Install

npm install -g mcp-git-coord

Or paste this into Claude Code, Cursor, or any MCP-compatible AI tool:

Install mcp-git-coord by following the instructions at https://raw.githubusercontent.com/OperatingSystem-1/mcp-git-coord/main/llms-full.txt

Manual setup

Add to your MCP server config (.claude/settings.json for Claude Code, .cursor/mcp.json for Cursor):

{
  "mcpServers": {
    "git-coord": {
      "command": "npx",
      "args": ["-y", "mcp-git-coord"]
    }
  }
}

Quick start — set up .mi context files

After installing, run this in your AI coding tool:

Set up .mi context files for this project using mi_setup

This will:

1. Scan your codebase — find directories with meaningful source code
2. Create .mi/CONTEXT.md in each one — scaffolded with file listings and recent git history
3. Install hooks — SessionStart (remind to read), PreToolUse on Read (nudge before changes), PostToolUse on Edit (remind to update), Stop (warn about stale docs)

Then fill in the _TODO_ sections in each generated context file. The more you invest in these docs, the fewer tokens every future session burns.

How .mi context files work

your-project/
├── src/
│   ├── .mi/
│   │   └── CONTEXT.md          ← "src/ architecture: API routes, DB layer, auth..."
│   ├── auth/
│   │   ├── .mi/
│   │   │   └── CONTEXT.md      ← "auth: OAuth flow, session management, JWT..."
│   │   ├── middleware.ts
│   │   └── session.ts
│   └── billing/
│       ├── .mi/
│       │   └── CONTEXT.md      ← "billing: Stripe integration, credit system..."
│       ├── stripe.ts
│       └── credits.ts
└── .claude/
    ├── hooks/                   ← auto-installed by mi_setup
    │   ├── mi-session-start.sh
    │   ├── mi-read-context.sh
    │   ├── mi-doc-reminder.sh
    │   └── mi-stop-check.sh
    └── settings.json            ← hooks registered here

The lifecycle:

1. Session starts → hook lists available .mi files, agent reads the relevant ones
2. Agent reads a file → hook reminds about .mi docs in that directory
3. Agent edits a file → hook reminds to update the .mi doc if the change affects it
4. Session ends → hook warns if source files changed but .mi docs weren't updated

The payoff: Instead of the agent spending 2,000+ tokens exploring src/auth/ from scratch, it reads a 150-line context doc that tells it everything: how OAuth works, where sessions are stored, what the JWT structure is, and what not to touch. That's a ~10x token reduction for that exploration, every single session.

How coordination works

Register intent before working

Agent → coord_register("Refactoring auth middleware", files: ["src/auth/middleware.ts"])
Server → "Registered. No conflicts."

Detect conflicts before code is written

Agent → coord_register("Adding rate limiting to auth", files: ["src/auth/middleware.ts"])
Server → "⚠️ Conflict: cursor-alex is refactoring auth middleware in the same file."

Plan around conflicts

Agent → coord_plan(my_intent, conflict)
Server → "Start with non-overlapping files. Defer auth/middleware.ts until their session completes."

Merge with full team context

Agent → coord_merge_check(target_branch: "dev")
Server →
  "2 file(s) have conflicting changes.
   src/auth/middleware.ts:
     Ours:   +15/-3 lines (refactored middleware signature)
     Theirs: +8/-2 lines (added rate limiter)
     Why:    cursor-alex was working on 'Adding rate limiting'

   Ask the user to resolve each conflict."

All tools

Context intelligence (.mi)

Tool	What it does
mi_setup	Scan codebase, create .mi/ context files, install hooks. Run once per project.
mi_scan	List all .mi context files with size and last modified.
mi_status	Check which .mi files are stale — source changed but docs not updated.

Coordination

Tool	What it does
coord_register	Register intent + files. Returns conflicts immediately.
coord_check	Check if files or scopes have active work.
coord_active	List all active sessions in the repo.
coord_complete	Mark session as done.
coord_plan	Given a conflict, suggest a non-overlapping approach.

Merge resolution

Tool	What it does
coord_merge_check	Analyze conflicts with target branch. Returns human-readable summaries with team context.
coord_merge_resolve	Resolve a single conflict: keep ours, accept theirs, or apply custom content.

Add coordination rules to your project

Add this to your CLAUDE.md, .cursorrules, or equivalent:

## Coordination (mcp-git-coord)

Before starting work, always:
1. Call `mi_scan` to see available context files, read the relevant ones
2. Call `coord_register` with your intent and the files you plan to modify
3. If conflicts are returned, call `coord_plan` to find a non-overlapping approach
4. When done, call `coord_complete` with a summary
5. Update any .mi context files affected by your changes

Before merging, always:
1. Call `coord_merge_check` with the target branch
2. If conflicts exist, present each one to the user with the TL;DR
3. Do NOT resolve any conflict without explicit user approval
4. Use `coord_merge_resolve` for each file after the user decides

Development

git clone https://github.com/OperatingSystem-1/mcp-git-coord
cd mcp-git-coord
npm install
npm run dev

License

MIT

---

Open sourced by Mitosis Labs — autonomous AI agents that persist, reproduce, and evolve.