<div align="center">

Synapse

Distributed Agent Swarm Control System

Plan, dispatch, and monitor parallel AI agent swarms from a native desktop app.

Synapse decomposes complex tasks into independent units, dispatches multiple agents simultaneously,<br>tracks dependencies between them, and gives you a live dashboard to watch it all happen in real-time.

Getting Started · Usage Guide · Features · Commands · Best Practices · How It Works

</div>

---

<div align="center">

What changes with Synapse

| Without | With Synapse | |:---:|:---:| | 1 agent, sequential tasks | N agents, parallel execution | | Context exhaustion on large tasks | Context distributed across workers | | No visibility into progress | Live dashboard with dependency graph | | Manual retry on failure | Circuit breaker with automatic replanning | | Terminal-only interaction | Native desktop GUI with built-in chat, code editor, git UI, and live preview |

</div>

---

Getting Started

Prerequisites

Before installing Synapse, make sure you have:

| Requirement | Details | |---|---| | Node.js 18+ | Required for Electron and native module compilation. Check with node --version | | npm | Comes with Node.js. Check with npm --version | | Claude Code CLI | Must be installed and authenticated. The claude command should be available on your PATH. Install Claude Code | | macOS | Synapse is an Electron desktop app currently targeting macOS |

Step 1: Clone and Install

git clone https://github.com/DeanCruz/Synapse.git
cd Synapse
npm install

The postinstall script automatically runs electron-rebuild to compile node-pty (the native terminal emulator) for your Electron version. If this fails, ensure you have Xcode Command Line Tools installed: xcode-select --install.

Step 2: Launch the App

npm start

This does two things:

1. Builds the React UI with Vite into dist/
2. Launches the Electron app which loads the built UI

The app opens with the Claude Chat view ready for input. No separate server process needed -- everything runs inside Electron.

Step 3: Connect Your Project

Synapse is fully standalone -- it works with any project, no special directory structure required. Each dashboard has its own project configuration, so you can work on multiple projects simultaneously.

Setting a project directory

When you create a new dashboard, click the Project button in the sidebar to open the project selector. Choose a directory -- this becomes the dashboard's project root, where agents will read and write code.

Each dashboard remembers its own project independently. You can have five dashboards open, each pointing at a different repo.

Adding additional context directories

In the same project selector, you can add additional context directories -- read-only reference paths that agents can read for context but will never modify. Use these for:

• Shared libraries or monorepo packages your project depends on
• Documentation repos with specs, designs, or API references
• Other related projects agents should understand but not touch

Additional context is injected into worker prompts as clearly marked READ-ONLY material. Agents can reference files from these directories to inform their work, but all code changes go exclusively to the project root.

Quick start

1. Click "+" in the sidebar to create a dashboard
2. Click the Project button → select your project directory
3. (Optional) Add additional context directories for reference material
4. Start working: !p_track Implement user authentication with JWT tokens

Full initialization (recommended for new projects)

# After selecting your project directory, run full setup in chat
!initialize

# This detects your tech stack, creates .synapse/, scaffolds CLAUDE.md, generates TOC

!initialize does the following automatically:

1. Detects your tech stack (package.json, tsconfig.json, go.mod, Cargo.toml, pyproject.toml, etc.)
2. Creates a .synapse/ directory in your project with configuration and a semantic table of contents
3. Scaffolds a CLAUDE.md in your project root if one doesn't exist (tech-stack-aware template)
4. Generates a full TOC index of your codebase for faster agent context gathering

Just scaffold a CLAUDE.md

# If you only need agent instructions for your project
!scaffold

Your project's CLAUDE.md tells agents about your tech stack, conventions, file structure, and coding standards. The better this file, the better your swarm results.

Scripts Reference

| Command | What It Does | |---|---| | npm start | Build UI + launch the desktop app | | npm run dev | Vite watch mode + Electron (concurrent -- useful for Synapse development) | | npm run dist | Package a signed .dmg for macOS distribution |

---

Usage Guide

Running Your First Swarm

1. Enter your task in Claude Chat

Type a !p_track command with a detailed description of what you want done:

!p_track Add a complete user settings page with profile editing,
password change, notification preferences, and account deletion.
Use the existing auth system and follow the project's component patterns.

2. The master agent reads your codebase

Synapse reads your project's CLAUDE.md, scans relevant files, and builds a deep understanding of your codebase. This takes a minute or two -- it's intentional. Well-informed plans produce well-informed workers.

3. Review the plan

The dashboard displays a task graph showing:

• Each task with its title, assigned wave, and dependencies
• Dependency arrows between tasks
• Wave groupings (tasks in the same wave run in parallel)

Review the breakdown. Check that dependencies make sense and no tasks overlap on the same files within a wave. You'll be asked to approve before dispatch begins.

4. Watch parallel execution

Once approved, workers dispatch immediately -- all independent tasks launch at once. The dashboard updates in real-time:

• Stage badges show each agent's current phase (reading context -> planning -> implementing -> testing -> finalizing)
• Milestone markers appear as agents complete subtasks
• Deviation badges (yellow) appear if a worker diverges from the plan
• Dependency lines highlight on hover -- blue for upstream needs, red for downstream blocks

5. Get the summary

When all tasks complete, you get a summary report with what was accomplished, any deviations, and metrics (elapsed time, parallel efficiency).

Choosing the Right Execution Mode

| | !p_track | !p | !master_plan_track | |---|---|---|---| | Dashboard | Full live dashboard with dependency graph | Minimal -- plan snapshot + final results | Multi-stream across multiple dashboards | | Progress files | Workers write real-time progress | Workers report only on completion | Child masters run full !p_track per stream | | History | Saved to archive for future reference | No persistent history | Per-stream archives | | Best for | 3+ tasks, complex dependencies, cross-file work | Quick jobs under 3 tasks, single wave | Large bodies of work (multiple independent swarms) | | Overhead | More setup, richer monitoring | Minimal, faster startup | Meta-planner + child masters |

Rule of thumb: Use !p_track for anything you'd want to monitor or review later. Use !p for quick parallel jobs where you just want results. Use !master_plan_track when work decomposes into multiple independent swarms.

Monitoring a Running Swarm

From the dashboard (visual):

• Agent cards show live stage, elapsed time, and current milestone
• Click any agent card to see full details: timeline, milestones, deviations, logs
• Dependency lines highlight upstream/downstream relationships on hover
• Stats bar shows completed/total, failures, and elapsed time

From the chat or terminal (commands):

!status                    # Progress summary with per-agent table
!logs                      # Full event log
!logs --level error        # Only errors
!logs --task 2.3           # Logs for a specific task
!logs --last 10            # Most recent 10 entries
!inspect 2.3               # Deep-dive on task 2.3: timeline, deps, deviations, worker logs
!deps                      # Dependency graph overview
!deps --blocked            # Show only blocked chains

Handling Failures

Yellow deviation badge -- A worker diverged from the original plan. This isn't necessarily a failure -- workers sometimes find a better approach. Review the deviation to decide if it's acceptable.

Red failed card -- A task failed. What to do:

1. Inspect the failure: !inspect {id} shows what happened, where it failed, and the worker's error logs
2. Retry with context: !retry {id} dispatches a fresh agent that receives the previous failure's error output, so it can avoid the same mistake
3. Manual dispatch: !dispatch {id} to manually trigger a pending task if auto-dispatch didn't pick it up

Automatic circuit breaker -- If 3+ tasks fail in the same wave, or a single failure blocks 3+ downstream tasks (or >50% of remaining tasks), Synapse automatically enters replanning mode. It analyzes the root cause, rewires dependencies, creates repair tasks if needed, and resumes dispatch -- no manual intervention required.

**Repair task