The shared nervous system for Vibe Coders and their Agents.
Synapse is a lightweight, local-first, Git-backed issue tracker designed to serve as persistent "long-term memory" for AI agents. It enables multiple AI agents to coordinate work through a shared task graph with dependency tracking.
- Git-Friendly Storage: JSONL format for clean diffs and easy merging
- Dependency Tracking: Block tasks on other tasks, automatic ready-state detection
- Sub-Agent Support: Assign tasks to roles (
@qa,@coder,@architect) - Global
--jsonFlag: Structured JSON output from every command for agent consumption - MCP Integration: JSON-RPC 2.0 server for Claude Code and other AI tools
- DAG Visualization: Web-based Mermaid.js task graph with auto-refresh
- Pure Go: No CGO dependencies, single binary deployment
- Breadcrumb System: Key-value storage for cross-session context persistence
- Claim Locking: Multi-agent coordination with automatic timeout release
- Agent Identity: Track which agent claimed and completed each task
- Rich Metadata: Notes, labels, priority, and discovery tracking
- Agentic Skills: One-command skill install for Claude Code, Gemini CLI, Codex, Antigravity, OpenCode
go install github.com/swiftj/synapse/cmd/synapse@latestOr build from source:
git clone https://github.com/swiftj/synapse.git
cd synapse
go build -o synapse ./cmd/synapse/# Initialize in your project
synapse init
# Manually add tasks
synapse add "Design API endpoints" --priority 3
synapse add "Implement handlers" --blocks 1 --label backend
synapse add "Write tests" --blocks 2 --assignee @qa --label testing
# View ready tasks
synapse ready
# Claim and complete work
synapse claim 1
synapse done 1
# Check what's ready now
synapse ready # Task 2 is now unblocked!
# Optionally instruct Claude Code to use Synapse (CLAUDE.md or AGENTS.md)
echo "Use 'synapse' for task tracking" >> CLAUDE.md| Flag | Description |
|---|---|
--json |
Output structured JSON from any command. Can appear anywhere in the argument list. |
synapse --json ready # flag before command
synapse list --json --status open # flag after command (backward compatible)| Command | Description |
|---|---|
init |
Initialize .synapse directory in current project |
add <title> |
Create a new task with optional flags (see below) |
list |
List all tasks (filter with --status, --label) |
ready |
List tasks ready to work on (unblocked, open status) |
get <id> |
Get details of a specific task |
claim <id> |
Mark task as in-progress |
done <id> |
Mark task as done |
all-done |
Mark all tasks as done (cleanup/reset command) |
skill install <agent> |
Install agentic skill for an agent (--level user|project) |
skill uninstall <agent> |
Remove skill for an agent (--level user|project) |
skill list |
Show installation status for all agents |
skill update [agent] |
Update installed skill(s) to current version |
skill show |
Print the embedded SKILL.md content |
serve |
Start MCP server (JSON-RPC over stdio) |
view |
Start visualization server (--port N, default 8080) |
Add command flags:
--blocks N- Task is blocked by task N--parent N- Task is a subtask of task N--assignee X- Assign to role (e.g.,@qa,@coder)--priority N- Set priority (higher = more important)--label X- Add a label (can be used multiple times)--note "text"- Add a note (can be used multiple times)--discovered-from N- Link to task where this was discovered
Breadcrumbs are key-value pairs for storing cross-session context:
| Command | Description |
|---|---|
breadcrumb set <key> <value> |
Store a breadcrumb |
breadcrumb get <key> |
Retrieve a breadcrumb |
breadcrumb list [prefix] |
List breadcrumbs (optionally filter by prefix) |
breadcrumb delete <key> |
Delete a breadcrumb |
bc |
Alias for breadcrumb |
Example usage:
# Store context for later sessions
synapse bc set "auth.strategy" "JWT with refresh tokens"
synapse bc set "db.migration.pending" "add_user_roles"
synapse bc set "blocked.reason.3" "Waiting for API spec from team"
# Retrieve context
synapse bc get "auth.strategy"
# List all breadcrumbs
synapse bc list
# List breadcrumbs with prefix
synapse bc list "auth."open -> in-progress -> done
| |
v v
blocked -> review
Tasks automatically transition from blocked to ready when all their blockers are marked done.
Synapse includes a Model Context Protocol server for AI agent integration:
// Add to Claude Code MCP config
{
"mcpServers": {
"synapse": {
"command": "synapse",
"args": ["serve"]
}
}
}Task Management Tools:
create_task- Create new tasks with dependencies, priority, labels, notesupdate_task- Modify task status, assignee, blockers, or metadataget_task- Retrieve task detailslist_tasks- List tasks with optional filtersget_next_task- Get highest priority ready taskcomplete_task- Mark task as done
Multi-Agent Coordination Tools:
claim_task- Claim a task with your agent ID (30-min timeout)release_claim- Release your claim on a taskcomplete_task_as- Mark task done and record completing agentmy_tasks- List all tasks claimed by your agentget_context_window- Get tasks modified within a time window
Breadcrumb Tools:
set_breadcrumb- Store a key-value pair (optionally linked to a task)get_breadcrumb- Retrieve a breadcrumb by keylist_breadcrumbs- List breadcrumbs with optional prefix filterdelete_breadcrumb- Remove a breadcrumb
The --json flag turns Synapse into a fully machine-readable CLI that agents like Claude Code can drive directly via shell commands — no MCP server required. This is the simplest integration path: add a few lines to CLAUDE.md and agents can use Synapse immediately.
CLI mode (--json) |
MCP server (serve) |
|
|---|---|---|
| Setup | Zero config — just add instructions to CLAUDE.md | Requires MCP server config in settings.json |
| Agent support | Any agent that can run shell commands | Agents with MCP client support |
| Latency | Process spawn per call (~5ms) | Persistent connection, slightly lower per-call |
| Best for | Quick setup, single-agent workflows, any agent | Multi-agent coordination, claim locking, context windows |
Add the following to your project's CLAUDE.md (or equivalent agent instructions file):
## Task Tracking
Use synapse CLI with --json for all task operations. Parse the JSON output to confirm results.
Workflow:
- Start of session: `synapse --json ready` to see available work
- Starting a task: `synapse --json claim <id>`
- Finishing a task: `synapse --json done <id>`
- Discovered a bug: `synapse --json add "Bug description" --blocks <id>`
- Store context: `synapse --json bc set <key> <value>`
- Recall context: `synapse --json bc get <key>`Every command returns structured JSON when --json is passed:
# Task objects
synapse --json add "Fix login bug" # → full Synapse object
synapse --json get 1 # → full Synapse object
synapse --json claim 1 # → Synapse object (status: in-progress)
synapse --json done 1 # → Synapse object (status: done)
synapse --json delete 1 # → Synapse object (pre-deletion snapshot)
# Task lists
synapse --json list # → array of Synapse objects
synapse --json list --status open # → filtered array
synapse --json ready # → array of ready tasks
# Bulk operations
synapse --json all-done # → {"count": N}
synapse --json delete --all # → {"deleted": N}
synapse --json delete --done # → {"deleted": N}
# Breadcrumbs
synapse --json bc set key value # → Breadcrumb object
synapse --json bc get key # → Breadcrumb object
synapse --json bc list # → array of Breadcrumb objects
synapse --json bc delete key # → {"deleted": "key"}
# Meta
synapse --json version # → {"version": "1.0.6"}
synapse --json init # → InitResult objectStart the web-based DAG viewer:
synapse view --port 8080Open http://localhost:8080 to see your task graph with:
- Color-coded status (white=open, yellow=in-progress, gray=blocked, blue=review, green=done)
- Solid arrows for blocking dependencies
- Dotted arrows for parent-child relationships
- Priority indicators (
P3= priority 3) - Claimed-by indicators (
@agent-name) - Label badges (
[backend,api]) - Auto-refresh every 5 seconds
Synapse stores data in .synapse/:
| File | Description | Git |
|---|---|---|
memory.jsonl |
Task data (source of truth) | ✅ Track |
breadcrumbs.jsonl |
Key-value context storage | ✅ Track |
Task format example:
{"id":1,"title":"Design API","status":"done","priority":3,"labels":["backend"],"created_at":"..."}
{"id":2,"title":"Implement handlers","status":"in-progress","blocked_by":[1],"claimed_by":"agent-1","claimed_at":"..."}Breadcrumb format example:
{"key":"auth.strategy","value":"JWT with refresh tokens","created_at":"...","updated_at":"..."}
{"key":"blocked.reason.3","value":"Waiting for API spec","task_id":3,"created_at":"..."}Best Practices:
- Commit
.synapse/memory.jsonland.synapse/breadcrumbs.jsonlto Git
Assign tasks to roles for multi-agent workflows:
synapse add "Review security" --assignee @security
synapse add "Fix vulnerabilities" --blocks 3 --assignee @coder
synapse add "Deploy to staging" --blocks 4 --assignee @devopsQuery by assignee:
synapse list --assignee @coder --jsonPrevent multiple agents from working on the same task:
# Agent claims task (30-minute timeout)
synapse claim 5
# Task is now "in-progress" and locked
# Other agents will see it as unavailable
# When done, mark complete
synapse done 5Via MCP Tools:
claim_task- Claims with agent ID and timeoutrelease_claim- Releases if stuck or reassigningcomplete_task_as- Records completing agentmy_tasks- Shows all tasks claimed by an agent
Claims automatically expire after 30 minutes if not completed or renewed, preventing deadlocks from crashed agents.
Get tasks modified within a time window for session context:
# MCP tool: get_context_window
# Parameters: minutes (e.g., 60 for last hour)This is useful for agents resuming work to understand recent activity.
To get Claude Code to automatically use Synapse MCP to its fullest, add the following to your project's CLAUDE.md file:
📋 Click to expand recommended CLAUDE.md content
# Task Management with Synapse
This project uses Synapse for persistent task tracking and agent coordination.
## Required Behavior
**Always use Synapse MCP tools for task management:**
- Before starting work: Check `get_next_task` or `list_tasks` to understand current priorities
- When discovering issues: Use `create_task` to log them immediately (prevents lost work)
- When starting a task: Use `claim_task` with your agent ID to prevent collisions
- When completing work: Use `complete_task_as` to record completion
- For cross-session context: Use breadcrumbs (`set_breadcrumb`, `get_breadcrumb`)
## Task Workflow
1. **Session Start:**
- Call `list_tasks` with status "in-progress" to see active work
- Call `get_context_window` with minutes=60 to see recent activity
- Check `my_tasks` if resuming previous work
2. **During Work:**
- Log discovered bugs/issues immediately with `create_task` (use `discovered_from` to link to current task)
- Add observations with `update_task` to append notes
- Use `set_breadcrumb` for important context that should persist across sessions
3. **Task Completion:**
- Use `complete_task_as` to mark done and record your agent ID
- Check `get_next_task` for the next priority item
## Task Creation Guidelines
When creating tasks, always include:
- Clear, actionable title
- `priority` (1-5, higher = more important)
- `labels` for categorization (e.g., "bug", "feature", "refactor")
- `blocked_by` if dependent on other tasks
- `assignee` if role-specific (@qa, @coder, @architect)
Example:
\`\`\`
create_task({
title: "Fix authentication token expiry",
priority: 3,
labels: ["bug", "security"],
blocked_by: [5],
assignee: "@coder"
})
\`\`\`
## Breadcrumb Usage
Use breadcrumbs to persist important context:
- `arch.*` - Architectural decisions (e.g., "arch.auth" = "JWT with refresh tokens")
- `blocked.*` - Blocking reasons (e.g., "blocked.task.5" = "Waiting for API spec")
- `context.*` - Session context (e.g., "context.current_focus" = "refactoring auth module")
- `decision.*` - Key decisions made (e.g., "decision.database" = "PostgreSQL for ACID compliance")
## Multi-Agent Coordination
- Claims timeout after 30 minutes automatically
- Always claim before starting work on a task
- Release claims if switching to different work
- Check `my_tasks` to see what you currently ownSynapse supports the Agentic Skills specification, a lightweight open format for teaching AI agents how to use tools. A single skill install command gives any supported agent full knowledge of Synapse's capabilities — no manual CLAUDE.md or AGENTS.md editing required.
| Agent | Format | Skill Path |
|---|---|---|
| Claude Code | SKILL.md + references |
~/.claude/skills/synapse/ or .claude/skills/synapse/ |
| Gemini CLI | SKILL.md + references |
~/.gemini/skills/synapse/ or .gemini/skills/synapse/ |
| Codex | AGENTS.md section |
~/.codex/AGENTS.md or AGENTS.md |
| Antigravity | SKILL.md + references |
~/.gemini/antigravity/skills/synapse/ or .agent/skills/synapse/ |
| OpenCode | SKILL.md + references |
~/.config/opencode/skills/synapse/ or .opencode/skills/synapse/ |
# Install for Claude Code (project-level, default)
synapse skill install claude-code
# Install globally (user-level)
synapse skill install claude-code --level user
# Install for another agent
synapse skill install gemini-cli --level user# Check installation status
synapse skill list
# Update all installed skills after upgrading synapse
synapse skill update
# Update a specific agent
synapse skill update claude-code --level user
# Remove a skill
synapse skill uninstall claude-code --level user
# Preview what gets installed
synapse skill showSKILL.md agents (Claude Code, Gemini CLI, Antigravity, OpenCode) receive:
SKILL.md— Tool quick-reference, workflows, status values, breadcrumb patterns, error recoveryreferences/workflows.md— Multi-session patterns, parallel agent coordination, dependency graph strategiesreferences/tool-reference.md— Complete MCP tool documentation with all parameters and examples
AGENTS.md agents (Codex) receive a marker-delimited section appended to the existing AGENTS.md file. Existing content is preserved; reinstalling replaces only the Synapse section.
# Install git hooks (auto-version bumping)
./scripts/install-hooks.sh
# Run tests
go test ./...
# Build binary
go build -o synapse ./cmd/synapse/
# Run examples
go run ./examples/viz_server/MIT License - see LICENSE file for details.
Contributions welcome! Please read the existing code style and add tests for new features.