Synapse

Synapse is a bridge that lets VS Code Copilot orchestrate Claude Code through MCP (Model Context Protocol).

• Copilot handles planning, review, and decision points.
• Claude Code executes coding tasks in isolated git worktrees.
• Synapse captures results (status, diff, test output) and returns them to Copilot.

Features

• MCP-native task orchestration for Copilot
• Isolated per-task git worktree execution
• Parallel task dispatch support
• Structured task lifecycle and JSON persistence
• Built-in verification hook (run tests + return review report)

Installation

Prerequisites

• Python 3.11+
• Poetry
• Git
• Claude Code CLI (claude command available in PATH)
• VS Code with Copilot and MCP support

Setup

git clone https://github.com/pengkangzhen/synapse.git
cd synapse
poetry install

Quick Start

1. Ensure the repository is a git repo

git rev-parse --is-inside-work-tree

If this fails, run:

git init
git add .
git commit -m "chore: initialize repository"

2. Configure Synapse

Default config is in .synapse/config.yaml.

Important fields:

• claude_cli_path: path to claude
• base_branch: usually main
• max_concurrent_tasks: max parallel Claude runs
• test_command: command used by verify_task

3. Start the MCP server

poetry run python -m synapse.mcp

In VS Code, .vscode/mcp.json can auto-register this server for Copilot.

4. Run a typical workflow in Copilot chat

1. Brainstorm and define a task.
2. Call plan_task to register it.
3. Confirm and call dispatch_task.
4. Poll with get_task_status until completed.
5. Review with get_task_result.
6. Validate with verify_task.
7. Confirm and finish with merge_task.

New Project Integration

If Synapse is already installed in a central location (for example: ~/tools/synapse), you can reuse it from any other repository.

1. Ensure target project prerequisites

• The target project is a git repository
• VS Code + Copilot with MCP support is available
• claude CLI is installed and authenticated

2. Add MCP server config in the target project

Create .vscode/mcp.json in the target project:

{
	"servers": {
		"synapse": {
			"type": "stdio",
			"command": "poetry",
			"args": ["run", "python", "-m", "synapse.mcp"],
			"cwd": "/Users/yourname/tools/synapse",
			"env": {
				"SYNAPSE_CONFIG": "${workspaceFolder}/.synapse/config.yaml"
			}
		}
	}
}

Notes:

• cwd should point to your Synapse installation root
• SYNAPSE_CONFIG should point to the current project config

3. Add project-local Synapse config

Create .synapse/config.yaml in the target project:

claude_cli_path: "claude"
base_branch: "main"
max_concurrent_tasks: 3
default_timeout_seconds: 600
test_command: "poetry run pytest -v"

Adjust test_command to match your stack (for example npm test, pnpm test, etc.).

4. Reload VS Code window

Run command palette action: Developer: Reload Window.

5. Run Synapse workflow in Copilot chat

1. plan_task
2. dispatch_task (after human confirmation)
3. get_task_status (poll)
4. get_task_result
5. verify_task
6. merge_task (after human confirmation)

Troubleshooting Checklist

Use this checklist when task execution fails or hangs.

A. Setup checks

• claude command is available: claude --version
• target project is inside a git worktree: git rev-parse --is-inside-work-tree
• .vscode/mcp.json exists and points to correct cwd
• .synapse/config.yaml exists in the current project

B. Common runtime issues

1. Error: unknown option '--directory'

• Cause: incompatible Claude CLI flag usage
• Fix: use latest Synapse code (no --directory flag)

2. Error: When using --print, --output-format=stream-json requires --verbose

• Cause: newer Claude CLI requires --verbose for stream-json mode
• Fix: use Synapse version that adds --verbose to executor command

3. Task appears stuck in executing

• Check get_task_status repeatedly for is_process_running
• If process is gone, call get_task_result to see final reconciliation message
• If needed, call cancel_task and dispatch again

4. Repeated model/API retries (429 rate limit)

• Cause: provider rate limiting
• Fix: retry later, reduce parallel tasks, or lower request frequency

C. Recovery workflow

1. cancel_task(task_id="...") for stuck tasks
2. Run Developer: Reload Window
3. Re-run from plan_task

D. Verification checklist before merge

• get_task_result has expected diff/summary
• verify_task returns report with expected test status
• acceptance criteria reviewed manually in Copilot chat

Workflow Diagram

flowchart LR
		U[User in VS Code] --> C[Copilot Chat]
		C -->|plan_task / dispatch_task| M[Synapse MCP Server]
		M -->|create worktree + run| CC[Claude Code CLI]
		CC -->|code changes| W[(Task Worktree)]
		W -->|diff + status + logs| M
		M -->|get_task_status / get_task_result / verify_task| C
		C -->|review + human confirmation| G[merge_task]
		G --> R[(main branch)]

Loading

Task Lifecycle

planned -> dispatched -> executing -> completed -> verified -> merged
															\-> failed
planned/executing -> cancelled

Project Structure

src/synapse/
	claude/    # Claude prompt builder and executor
	config/    # settings loader
	core/      # task model, store, worktree, verifier
	mcp/       # MCP server and entrypoint

Notes

• For parallel tasks, prefer non-overlapping files_to_modify.
• Use absolute paths for claude_cli_path if worktree-relative execution causes path issues.
• Runtime artifacts are stored under .synapse/tasks and .synapse/worktrees.