claude-sync

Cross-machine context sharing MCP server for Claude Code. Share decisions, patterns, and knowledge across multiple Claude Code instances running on different machines.

What it does

When you use Claude Code on multiple machines (backend server, frontend laptop, ideas tablet), each instance is isolated. claude-sync gives them a shared memory — push a decision on one machine, search for it on another.

Quick Start

1. Clone and configure

git clone https://github.com/YOUR_USERNAME/claude-sync.git
cd claude-sync
cp .env.example .env

Edit .env and set:

• API_KEY_HASH — see below for generating

2. Generate an API key

# Generate a random key
KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
echo "Your API key: $KEY"

# Hash it for .env
HASH=$(echo -n "$KEY" | shasum -a 256 | cut -d' ' -f1)
echo "API_KEY_HASH=$HASH"

Add the hash to your .env file.

3. Start with Docker Compose

docker compose up -d

The server will be available at http://localhost:3001.

4. Connect Claude Code

Add to your ~/.claude/settings.json:

{
  "mcpServers": {
    "claude-sync": {
      "type": "streamable-http",
      "url": "http://localhost:3001/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

For remote access (e.g., deployed on Railway), replace localhost:3001 with your server URL.

Deploy on Railway

1. Fork this repo
2. Create a new project on Railway
3. Add a PostgreSQL database (select the pgvector template)
4. Add a new service from your forked repo
5. Set environment variables: API_KEY_HASH, DATABASE_URL (auto-set by Railway)
6. Deploy

MCP Tools

Tool	Description
push_context	Store a new context entry (decision, discovery, pattern, etc.)
search_context	Semantic search across all shared entries
list_recent	List recent entries, optionally filtered by machine or type
get_entry	Get full details of a specific entry
delete_entry	Soft-delete an entry
list_machines	See which machines have contributed and their activity

Entry Types

• context — general context
• decision — architectural or design decisions
• discovery — learning about existing systems
• bugfix — something broken, now fixed
• pattern — reusable approaches
• architecture — structural decisions
• gotcha — traps and edge cases
• trade-off — pros/cons analysis

Multi-Key Mode (Teams)

For teams, use database-backed API keys instead of API_KEY_HASH:

1. Remove API_KEY_HASH from .env
2. Run migrations: docker compose up -d
3. Generate keys:

npm run create-key -- --project my-project --label "Alice's laptop"
npm run create-key -- --project my-project --label "Bob's desktop"

Each key is scoped to a project. Team members using the same project see shared context.

Development

npm install
cp .env.example .env  # configure your env

# Start Postgres with pgvector
docker compose up db -d

# Run in development mode
npm run dev

Architecture

• TypeScript + Express + MCP SDK
• PostgreSQL + pgvector for storage and vector similarity search
• Local embeddings via all-MiniLM-L6-v2 (runs in-process, no external API calls)
• Stateless MCP transport — each request is independent
• Bearer token auth — single-key or multi-key modes

License

MIT