mcp-context-sync

Synchronize work context between AI coding agents. One agent saves progress, another picks up exactly where it left off.

Supports: Claude Code · Codex · Gemini CLI · Cursor

Quick Start

Install

npm install -g mcp-context-sync

Configure all AI clients

context-sync install --all

Verify

context-sync doctor

Supported Platforms

| Node version | macOS / Linux | Windows | |-------------|---------------|---------| | 18 LTS | ✓ | ✓ | | 20 LTS | ✓ recommended | ✓ recommended | | 22 LTS | ✓ recommended | ✓ recommended | | 23+ | ✓ (may compile from source) | ✗ requires Build Tools¹ |

¹ Node 23+ on Windows has no prebuilt better-sqlite3 binary. The installer will abort with a clear message instead of leaving broken shims. Fix: use Node 20/22 LTS, or install Visual Studio Build Tools with "Desktop development with C++".

What gets installed

Two binaries:

• mcp-context-sync — MCP server (stdio transport, used by AI clients)
• context-sync — CLI for manual operations and diagnostics

Concepts

MCP Tools (used by AI agents)

These are the tools the MCP server exposes. AI agents call them automatically:

| Tool | Description | |------|-------------| | sync | Save a structured snapshot of current work state | | resume | Load the latest snapshot for a project | | log-decision | Record an architectural decision | | get-history | View timeline of snapshots and handoffs | | list-projects | List all synced projects | | search-snapshots | Full-text search across snapshots | | amend-snapshot | Update the most recent snapshot |

MCP Resources (read by AI agents)

| Resource | Description | |----------|-------------| | status | Server status and stats | | project-snapshot | Latest snapshot for a project | | project-decisions | Decision log for a project |

CLI Commands (used by you in terminal)

context-sync resume     [--project <path>] [--agent <name>] [--brief] [--json] [--peek]
context-sync sync       --file <path> | --json '<json>' | stdin | --interactive
context-sync auto-sync  [--project <path>] [--agent <name>]
context-sync list
context-sync history    [--project <path>] [--limit <n>]
context-sync doctor
context-sync install    [--claude] [--codex] [--gemini] [--cursor] [--all]

If --project is omitted, the git repository root is auto-detected. Falls back to the current working directory when not inside a git repo.

Flags

| Flag | Commands | Description | |------|----------|-------------| | --project <path> | resume, history, auto-sync | Project directory override | | --agent <name> | resume, sync, auto-sync | Agent name for handoff tracking | | --peek | resume | Read-only mode — prints the snapshot without recording a handoff | | --brief | resume | Compact human-readable summary (implies --peek) | | --json | resume, sync | Raw JSON output for resume; inline JSON input for sync | | --file <path> | sync | Read JSON input from a file (recommended for PowerShell) | | --interactive, -i | sync | Guided step-by-step snapshot creation | | --limit <n> | history | Max entries to show (default 10) |

Slash Commands / Skills (optional, per-client)

Skills like /resume-project and /sync-project are NOT part of this package. They are client-specific configurations (e.g., Claude Code skills in ~/.agents/skills/). The MCP tools work without them.

Client Configuration

Claude Code

Add to ~/.claude.json (or use claude mcp add):

{
  "mcpServers": {
    "context-sync": {
      "type": "stdio",
      "command": "mcp-context-sync",
      "args": [],
      "env": {}
    }
  }
}

Or via CLI:

claude mcp add --scope user context-sync -- mcp-context-sync

Codex

Add to ~/.codex/mcp.json:

{
  "mcpServers": {
    "context-sync": {
      "command": "mcp-context-sync"
    }
  }
}

Gemini CLI

Add to ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "context-sync": {
      "command": "mcp-context-sync"
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "context-sync": {
      "type": "stdio",
      "command": "mcp-context-sync",
      "args": [],
      "env": {}
    }
  }
}

Storage

• Database: ~/.agents/context-sync/data/context-sync.sqlite
• WAL mode enabled for concurrent access
• Projects identified by SHA-256 hash of normalized absolute path (lowercase, forward slashes, no trailing slash)
• All agents resolve to the same project as long as they use the same absolute path to the project root

Troubleshooting

Windows + Node 24: better-sqlite3 build fails

better-sqlite3 uses native binaries. Node 24 may not have prebuilt binaries yet.

Fix (recommended): Use Node 20 or 22 LTS:

nvm install 22
nvm use 22
npm install -g mcp-context-sync

Fix (alternative): Install Visual Studio Build Tools:

1. Download from https://visualstudio.microsoft.com/visual-cpp-build-tools/
2. Install "Desktop development with C++"
3. Retry: npm install -g mcp-context-sync

MCP shows "Failed to connect"

1. Ensure mcp-context-sync is in your PATH:
   • Linux/macOS: which mcp-context-sync
   • Windows: where mcp-context-sync
2. If using npx, switch to global install -- npx adds 2-3s latency that can exceed MCP health check timeouts
3. Restart your AI client after installing

"command not found" after install

On Windows, close and reopen your terminal after npm i -g to refresh PATH.

Project not found on resume

• Projects are matched by exact absolute path (normalized to lowercase with forward slashes)
• If you're in a subdirectory, the CLI auto-detects git root via git rev-parse --show-toplevel, then walks up parent directories to find a known project in the database
• Run context-sync list to see all synced projects and their paths
• Use --project flag to specify the path explicitly

CLI Examples

# Resume latest snapshot (auto-detects project from cwd or git root)
context-sync resume --agent codex

# Peek at snapshot without recording a handoff
context-sync resume --peek

# Print a compact summary for fast reading
context-sync resume --brief

# Emit raw JSON for piping into other tools
context-sync resume --json

# Save a snapshot from a JSON file
context-sync sync --file snapshot.json

# Create a snapshot interactively (step-by-step prompts)
context-sync sync --interactive --agent codex

# Auto-save remaining context on session exit
context-sync auto-sync --agent claude-code

# List all synced projects
context-sync list

# View last 5 handoffs
context-sync history --limit 5

Development

git clone https://github.com/Pueyo10/context-sync-mcp.git
cd context-sync-mcp
npm install
npm run build
npm test
npm run release   # test + build + bump patch + publish + push

License

MIT