Synapse

Synapse AI Agent Orchestration Skill

Synapse is a distributed AI agent system that orchestrates three specialized services with configurable models and role-based workflows.

Agent Roles

When to Apply

Use this skill when:

• Breaking down complex tasks into actionable multi-step plans
• Generating implementation code from descriptions or specifications
• Analyzing large codebases or content (especially >200k tokens via Gemini)
• Getting comprehensive code reviews with quality scoring
• Running sandboxed shell commands for builds, tests, or automation
• Executing full plan-analyze-code-review-execute workflows
• Orchestrating parallel or pipeline-based multi-agent workflows

Do NOT use when:

• Simple questions that don't require code generation
• Tasks that only need local file operations
• When Docker/Synapse services are not available

Prerequisites

Docker must be running with Synapse services active.

# Clone Synapse (if not already)
git clone https://github.com/akillness/Synapse.git ~/Synapse
cd ~/Synapse

# Start services
docker compose up -d

# Verify all services are healthy
curl -s http://localhost:8000/health
# Expected: {"status": "healthy", "service": "gateway"}

Installation

Global Installation (Recommended)

# Clone synapse-skill
git clone https://github.com/akillness/synapse-skill.git

# For OpenCode
ln -s $(pwd)/synapse-skill ~/.config/opencode/skills/synapse

# For Claude Code / Other Agents
mkdir -p ~/.agents/skills
ln -s $(pwd)/synapse-skill ~/.agents/skills/synapse

Environment Variables (Optional)

# Custom Synapse location
export SYNAPSE_HOME="$HOME/Synapse"

# Gateway URL (default: http://localhost:8000)
export SYNAPSE_GATEWAY_URL="http://localhost:8000"

For Cursor IDE

Create .cursor/rules/synapse.mdc in your project:

---
description: Synapse AI Agent Orchestration
globs: ["**/*"]
alwaysApply: true
---

# Synapse Skill Integration

When orchestrating multi-agent tasks, use Synapse endpoints:
- Plan: POST http://localhost:8000/api/v1/claude/plan
- Code: POST http://localhost:8000/api/v1/claude/code
- Analyze: POST http://localhost:8000/api/v1/gemini/analyze
- Review: POST http://localhost:8000/api/v1/gemini/review
- Execute: POST http://localhost:8000/api/v1/codex/execute

Use @planner for task breakdown, @reviewer for code review.

For Claude Code (CLAUDE.md)

Add to your ~/.claude/CLAUDE.md:

## Synapse Integration

For multi-agent orchestration, use Synapse skill:
- Health check: curl http://localhost:8000/health
- Ensure Docker containers are running: docker ps | grep synaps
- Use /api/v1/workflow for full pipeline execution

For OpenCode (oh-my-opencode.json)

Add Synapse-optimized agent configuration to ~/.config/opencode/oh-my-opencode.json:

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  "agents": {
    "synapse-planner": {
      "model": "google/antigravity-claude-sonnet-4-5"
    },
    "synapse-analyst": {
      "model": "google/antigravity-gemini-3-pro-high"
    },
    "synapse-coder": {
      "model": "google/antigravity-claude-sonnet-4-5-thinking"
    },
    "synapse-reviewer": {
      "model": "google/antigravity-gemini-3-pro-high"
    },
    "synapse-executor": {
      "model": "openai/gpt-5.2-codex-high"
    }
  }
}

OpenCode Model Provider Configuration

Add to ~/.config/opencode/opencode.json for custom Synapse models:

{
  "provider": {
    "synapse": {
      "name": "Synapse Local",
      "api": "openai",
      "options": {
        "baseURL": "http://localhost:8000/api/v1/"
      },
      "models": {
        "claude-planner": {
          "name": "Claude Planner (Synapse)",
          "limit": { "context": 200000, "output": 64000 }
        },
        "gemini-analyst": {
          "name": "Gemini Analyst (Synapse)",
          "limit": { "context": 1000000, "output": 65536 }
        },
        "codex-executor": {
          "name": "Codex Executor (Synapse)",
          "limit": { "context": 272000, "output": 128000 }
        }
      }
    }
  }
}

OpenCode Skill Integration

The skill is automatically loaded when symlinked to ~/.config/opencode/skills/synapse.

Trigger phrases for OpenCode:

• "orchestrate agents" → Activates Synapse workflow
• "multi-agent workflow" → Starts parallel or pipeline execution
• "run synapse" → Executes full workflow

---

Model Configuration

Claude Service Models (2026)

Claude 4.5 Highlights:

• Opus 4.5: State-of-the-art coding (80%+ SWE-bench), best for agents and computer use
• Sonnet 4.5: 1M token context window (5x increase), extended thinking mode
• Haiku 4.5: Cost-effective with 90% of Sonnet's performance

Gemini Service Models (2026)

Gemini 3 Highlights:

• 35% better at software engineering tasks vs 2.5 Pro
• "Vibe coding" support for rapid prototyping
• Knowledge cutoff: January 2025

Codex Service Models

---

Agentic Workflow Patterns

Pattern 1: Parallel Specialists

Multiple specialists review code simultaneously:

┌─────────────────────────────────────────────────────┐
│                    ORCHESTRATOR                      │
│                   (You / Claude)                     │
└────────────┬───────────┬───────────┬────────────────┘
             │           │           │
     ┌───────▼───┐ ┌─────▼─────┐ ┌───▼───────┐
     │ Security  │ │Performance│ │ Simplicity│
     │ Reviewer  │ │ Reviewer  │ │ Reviewer  │
     │ (Gemini)  │ │ (Gemini)  │ │ (Gemini)  │
     └───────────┘ └───────────┘ └───────────┘

Workflow:

# 1. Spawn parallel reviews
curl -X POST http://localhost:8000/api/v1/gemini/review \
  -d '{"code": "<code>", "language": "python", "review_type": "security"}'

curl -X POST http://localhost:8000/api/v1/gemini/review \
  -d '{"code": "<code>", "language": "python", "review_type": "performance"}'

curl -X POST http://localhost:8000/api/v1/gemini/review \
  -d '{"code": "<code>", "language": "python", "review_type": "simplicity"}'

# 2. Aggregate results and synthesize

Pattern 2: Pipeline (Sequential Dependencies)

Each stage depends on the previous:

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ Research │───▶│   Plan   │───▶│Implement │───▶│   Test   │───▶│  Review  │
│ (Gemini) │    │ (Claude) │    │ (Claude) │    │ (Codex)  │    │ (Gemini) │
└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘

Workflow:

# Step 1: Research (Gemini analyzes requirements)
RESEARCH=$(curl -X POST http://localhost:8000/api/v1/gemini/analyze \
  -d '{"content": "<requirements>", "analysis_type": "documentation"}')

# Step 2: Plan (Claude creates implementation plan)
PLAN=$(curl -X POST http://localhost:8000/api/v1/claude/plan \
  -d "{\"task\": \"Implement based on: $RESEARCH\", \"constraints\": [\"python\", \"tests\"]}")

# Step 3: Implement (Claude generates code)
CODE=$(curl -X POST http://localhost:8000/api/v1/claude/code \
  -d "{\"description\": \"$PLAN\", \"language\": \"python\"}")

# Step 4: Test (Codex executes tests)
TEST=$(curl -X POST http://localhost:8000/api/v1/codex/execute \
  -d '{"command": "python -m pytest tests/", "timeout": 60}')

# Step 5: Review (Gemini reviews final code)
REVIEW=$(curl -X POST http://localhost:8000/api/v1/gemini/review \
  -d "{\"code\": \"$CODE\", \"language\": \"python\"}")

Pattern 3: Swarm (Self-Organizing)

Workers grab available tasks from a pool:

                    ┌─────────────┐
                    │  Task Pool  │
                    │ ┌─┬─┬─┬─┬─┐ │
                    │ │1│2│3│4│5│ │
                    │ └─┴─┴─┴─┴─┘ │
                    └──────┬──────┘
           ┌───────────────┼───────────────┐
           │               │               │
     ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
     │  Worker 1 │   │  Worker 2 │   │  Worker 3 │
     │  (Claude) │   │  (Gemini) │   │  (Codex)  │
     │ claims #1 │   │ claims #2 │   │ claims #3 │
     └───────────┘   └───────────┘   └───────────┘

Workflow:

# Create task pool via workflow endpoint
curl -X POST http://localhost:8000/api/v1/workflow \
  -d '{
    "task": "Review all files in src/",
    "mode": "swarm",
    "workers": 3,
    "constraints": ["parallel", "auto-assign"]
  }'

Pattern 4: Full Workflow (End-to-End)

Use the workflow endpoint for automatic orchestration:

curl -X POST http://localhost:8000/api/v1/workflow \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Build a user authentication module",
    "constraints": ["FastAPI", "JWT", "PostgreSQL"],
    "workflow_type": "pipeline",
    "model_config": {
      "planner": "claude-sonnet-4",
      "analyst": "gemini-2.5-pro",
      "coder": "claude-sonnet-4",
      "executor": "gpt-5.2"
    }
  }'

---

Role-Based Model Assignment

Configuration Schema

{
  "roles": {
    "planner": {
      "service": "claude",
      "model": "claude-sonnet-4.5",
      "description": "Creates task plans and architecture designs"
    },
    "analyst": {
      "service": "gemini",
      "model": "gemini-3-pro-preview",
      "description": "Analyzes content and performs code reviews"
    },
    "coder": {
      "service": "claude",
      "model": "claude-sonnet-4.5",
      "description": "Generates implementation code"
    },
    "reviewer": {
      "service": "gemini",
      "model": "gemini-3-pro-preview",
      "description": "Performs comprehensive code reviews"
    },
    "executor": {
      "service": "codex",
      "model": "gpt-5.2",
      "description": "Executes commands and runs tests"
    }
  }
}

Role Selection by Task Type

---

API Reference

Base URL

http://localhost:8000

Endpoints Summary

---

Quick Reference

---

Running Tasks

1. Health Check (Always Start Here)

# Check all services
curl -s http://localhost:8000/api/v1/claude/health
curl -s http://localhost:8000/api/v1/gemini/health
curl -s http://localhost:8000/api/v1/codex/health

Expected response:

{"status": "SERVING", "version": "1.0.0", "uptime_seconds": 123}

2. Create a Plan (Claude)

curl -X POST http://localhost:8000/api/v1/claude/plan \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Build a REST API with authentication",
    "constraints": ["use FastAPI", "JWT tokens", "PostgreSQL"],
    "model": "claude-sonnet-4"
  }'

3. Generate Code (Claude)

curl -X POST http://localhost:8000/api/v1/claude/code \
  -H "Content-Type: application/json" \
  -d '{
    "description": "A function to validate email addresses using regex",
    "language": "python",
    "model": "claude-sonnet-4"
  }'

4. Analyze Content (Gemini)

curl -X POST http://localhost:8000/api/v1/gemini/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "content": "<large_codebase_content>",
    "analysis_type": "code",
    "model": "gemini-2.5-pro"
  }'

5. Review Code (Gemini)

curl -X POST http://localhost:8000/api/v1/gemini/review \
  -H "Content-Type: application/json" \
  -d '{
    "code": "def add(a, b):\n    return a + b",
    "language": "python",
    "review_type": "comprehensive",
    "model": "gemini-3-pro-preview"
  }'

6. Execute Command (Codex)

curl -X POST http://localhost:8000/api/v1/codex/execute \
  -H "Content-Type: application/json" \
  -d '{
    "command": "python -m pytest tests/",
    "working_dir": "/tmp",
    "timeout": 60,
    "model": "gpt-5.2"
  }'

Allowed Commands: echo, ls, pwd, date, cat, head, tail, wc, grep, find, python, pip, npm, node, git, make

---

Common Workflows

Code Development Workflow

# 1. Create plan
curl -X POST http://localhost:8000/api/v1/claude/plan \
  -H "Content-Type: application/json" \
  -d '{"task": "Implement user authentication", "model": "claude-sonnet-4"}'

# 2. Generate code
curl -X POST http://localhost:8000/api/v1/claude/code \
  -H "Content-Type: application/json" \
  -d '{"description": "JWT authentication middleware", "language": "python"}'

# 3. Review code
curl -X POST http://localhost:8000/api/v1/gemini/review \
  -H "Content-Type: application/json" \
  -d '{"code": "<generated_code>", "language": "python", "model": "gemini-3-pro-preview"}'

# 4. Run tests
curl -X POST http://localhost:8000/api/v1/codex/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "python -m pytest tests/", "timeout": 60}'

Code Analysis Workflow

# 1. Read file content
FILE_CONTENT=$(cat myfile.py | jq -Rs .)

# 2. Analyze with large context model
curl -X POST http://localhost:8000/api/v1/gemini/analyze \
  -H "Content-Type: application/json" \
  -d "{\"content\": $FILE_CONTENT, \"analysis_type\": \"code\", \"model\": \"gemini-2.5-pro\"}"

# 3. Review with detailed model
curl -X POST http://localhost:8000/api/v1/gemini/review \
  -H "Content-Type: application/json" \
  -d "{\"code\": $FILE_CONTENT, \"language\": \"python\", \"model\": \"gemini-3-pro-preview\"}"

---

Error Handling

Service Unavailable (503)

{"detail": "Service not ready"}

Solution: Check if Docker containers are running:

docker ps | grep synaps

Connection Refused

Solution: Start Synapse services:

cd ~/Synapse  # or $SYNAPSE_HOME
docker compose up -d

Command Not Allowed (Codex)

{"success": false, "stderr": "Command not allowed"}

Solution: Use only allowed commands (echo, ls, pwd, python, etc.)

---

Troubleshooting

Check Service Status

# All containers running?
docker ps --format "table {{.Names}}\t{{.Status}}" | grep synaps

# Gateway health
curl -s http://localhost:8000/health

# Individual service health
curl -s http://localhost:8000/api/v1/claude/health
curl -s http://localhost:8000/api/v1/gemini/health
curl -s http://localhost:8000/api/v1/codex/health

Restart Services

cd ~/Synapse  # or $SYNAPSE_HOME
docker compose down
docker compose up -d

View Logs

docker logs synaps-gateway
docker logs synaps-claude
docker logs synaps-gemini
docker logs synaps-codex

---

Service Ports

---

Integration with AI Agents

This skill can be used by any AI coding agent that supports HTTP requests:

• OpenCode/Claude Code: Use bash tool with curl commands
• Cursor: Use terminal or HTTP client extensions
• GitHub Copilot: Use inline curl in terminal
• Windsurf: Use built-in terminal

Example Agent Integration

User: "Create a plan to build a web scraper"

Agent uses Synapse skill:
1. curl POST /api/v1/claude/plan with task and model config
2. Parse response and present steps to user
3. Offer to generate code for each step
4. Execute tests via Codex
5. Review final code via Gemini

Swarm Mode Integration

For complex multi-file tasks, use swarm orchestration:

User: "Review all authentication files for security issues"

Agent orchestrates:
1. Spawn parallel Gemini reviewers for each file
2. Aggregate findings
3. Generate summary report
4. Propose fixes via Claude

---

Current Status (v2.3.0)

Service Health (Verified 2026-01-28)

Connection Pool Metrics

Claude Pool          Gemini Pool          Codex Pool
┌────────────┐       ┌────────────┐       ┌────────────┐
│ Size: 2    │       │ Size: 2    │       │ Size: 2    │
│ Avail: 2   │       │ Avail: 2   │       │ Avail: 2   │
│ Acquired:3 │       │ Acquired:4 │       │ Acquired:3 │
│ Released:3 │       │ Released:4 │       │ Released:3 │
└────────────┘       └────────────┘       └────────────┘

Load Balancer Status: All endpoints healthy (1/1 each)
Avg Response Time (Claude): 21.47ms

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                         SYNAPSE WORKFLOW ARCHITECTURE                        │
└─────────────────────────────────────────────────────────────────────────────┘

                            ┌──────────────┐
                            │   Gateway    │ :8000
                            │   (REST)     │
                            └──────┬───────┘
                                   │
            ┌──────────────────────┼──────────────────────┐
            │                      │                      │
            ▼                      ▼                      ▼
   ┌────────────────┐    ┌────────────────┐    ┌────────────────┐
   │     Claude     │    │     Gemini     │    │     Codex      │
   │     :5011      │    │     :5012      │    │     :5013      │
   │    (gRPC)      │    │    (gRPC)      │    │    (gRPC)      │
   └────────────────┘    └────────────────┘    └────────────────┘
          │                      │                      │
          ▼                      ▼                      ▼
   ┌────────────┐         ┌────────────┐         ┌────────────┐
   │   /plan    │         │  /analyze  │         │  /execute  │
   │   /code    │         │  /review   │         │            │
   └────────────┘         └────────────┘         └────────────┘

---

Improvement Roadmap

1. Unified Workflow Endpoint Enhancement

Current: Individual service calls required

curl /api/v1/claude/plan → curl /api/v1/claude/code → curl /api/v1/gemini/review → curl /api/v1/codex/execute

Planned: Single workflow call with workflow_type parameter

curl /api/v1/workflow -d '{"task": "...", "workflow_type": "pipeline|parallel|swarm"}'

2. MCP Tool Direct Integration

Current: curl-based access via Bash tool

Bash → curl → Gateway → Service

Planned: Native MCP server tools

mcp__synapse__plan → Gateway → Claude
mcp__synapse__analyze → Gateway → Gemini
mcp__synapse__execute → Gateway → Codex

3. Enhanced Error Handling

Current: Simple error response

{"detail": "Service not ready"}

Planned: Rich error with retry guidance

{
  "error": "Service not ready",
  "retry_after": 5,
  "fallback_available": true,
  "fallback_service": "gemini-2.5-flash"
}

4. SSE Streaming Response Support

Current: Full response wait

response = await service.plan(request)  # Waits for completion

Planned: Real-time progress streaming

async for chunk in service.plan_stream(request):
    yield chunk  # Real-time progress updates

5. Redis Caching Layer

Planned Architecture:

              Request
                 │
                 ▼
          ┌─────────────┐     Cache Hit      ┌─────────────┐
          │   Gateway   │ ─────────────────▶ │    Redis    │
          └──────┬──────┘                    └─────────────┘
                 │ Cache Miss
                 ▼
          ┌─────────────┐
          │   Service   │
          └─────────────┘

6. Quick Commands (Planned)

# Shorthand commands for common operations
synapse plan "Build REST API"     # → Claude Plan
synapse review "def foo(): ..."   # → Gemini Review
synapse run "pytest tests/"       # → Codex Execute
synapse flow "Create feature X"   # → Full Pipeline

7. Auto Service Detection

Planned Features:

• Docker container status check on skill activation
• Automatic unhealthy service restart prompt
• Service dependency validation

Synapse Skill

AI Agent skill for multi-agent orchestration with configurable models and role-based workflows.

    

Overview

Synapse is a distributed AI agent orchestration system that coordinates three specialized services with configurable models (Updated January 2026):

Features

• Multi-Model Support: Configure different models for each service (Claude 4.5, Gemini 3, GPT-5.2)
• Role-Based Assignment: Assign specific models to specific tasks
• Agentic Workflows: Support for parallel, pipeline, and swarm patterns
• Claude Swarms Compatible: Similar orchestration patterns to Claude's TeammateTool
• OpenCode Compatible: oh-my-opencode.json agent configuration + skill integration
• Cursor IDE Compatible: .cursor/rules/ integration for Cursor agents
• Claude Code Compatible: CLAUDE.md integration for Claude Code workflows

Installation

Universal Installation (Recommended)

Works with all CLI terminals (Claude Code, Cursor, OpenCode, etc.):

npx skills add https://github.com/akillness/synapse-skill --skill

This automatically installs the skill for your AI agent environment.

Prerequisites

• Docker and Docker Compose
• Synapse services running

Quick Start

# 1. Clone Synapse (the backend services)
git clone https://github.com/akillness/Synapse.git ~/Synapse
cd ~/Synapse
docker compose up -d

# 2. Clone synapse-skill
git clone https://github.com/akillness/synapse-skill.git
cd synapse-skill

# 3. Install for your AI agent

For OpenCode

# 1. Symlink the skill
ln -s $(pwd) ~/.config/opencode/skills/synapse

# 2. (Optional) Add agent configuration to oh-my-opencode.json
cat >> ~/.config/opencode/oh-my-opencode.json << 'EOF'
{
  "agents": {
    "synapse-planner": { "model": "google/antigravity-claude-sonnet-4-5" },
    "synapse-analyst": { "model": "google/antigravity-gemini-3-pro-high" },
    "synapse-reviewer": { "model": "google/antigravity-gemini-3-pro-high" }
  }
}
EOF

OpenCode Trigger Phrases:

• "orchestrate agents" → Synapse workflow
• "multi-agent workflow" → Parallel/pipeline execution
• "run synapse" → Full workflow

For Claude Code

mkdir -p ~/.agents/skills
ln -s $(pwd) ~/.agents/skills/synapse

For Cursor IDE

Create .cursor/rules/synapse.mdc:

---
description: Synapse AI Agent Orchestration
globs: ["**/*"]
alwaysApply: true
---

When orchestrating multi-agent tasks, use Synapse endpoints:
- Plan: POST http://localhost:8000/api/v1/claude/plan
- Code: POST http://localhost:8000/api/v1/claude/code
- Review: POST http://localhost:8000/api/v1/gemini/review

For Other Agents

Copy SKILL.md to your agent's skill directory or reference it directly.

Configuration

Environment Variables

# Custom Synapse location (default: ~/Synapse)
export SYNAPSE_HOME="$HOME/Synapse"

# Gateway URL (default: http://localhost:8000)
export SYNAPSE_GATEWAY_URL="http://localhost:8000"

Model Configuration

Each service supports model selection via the model parameter:

# Claude 4.5 with specific model
curl -X POST http://localhost:8000/api/v1/claude/plan \
  -d '{"task": "Build API", "model": "claude-opus-4.5"}'

# Gemini 3 with specific model
curl -X POST http://localhost:8000/api/v1/gemini/review \
  -d '{"code": "...", "model": "gemini-3-pro-preview"}'

# GPT-5.2 with specific model
curl -X POST http://localhost:8000/api/v1/codex/execute \
  -d '{"command": "pytest", "model": "gpt-5.2-mini"}'

Role-Based Configuration

{
  "model_config": {
    "planner": "claude-sonnet-4.5",
    "analyst": "gemini-3-pro-preview",
    "coder": "claude-sonnet-4.5",
    "reviewer": "gemini-3-pro-preview",
    "executor": "gpt-5.2"
  }
}

Agentic Workflow Patterns

Parallel Specialists

Multiple reviewers work simultaneously:

# Security, performance, and simplicity reviews in parallel
curl -X POST http://localhost:8000/api/v1/gemini/review \
  -d '{"code": "...", "review_type": "security"}' &
curl -X POST http://localhost:8000/api/v1/gemini/review \
  -d '{"code": "...", "review_type": "performance"}' &
curl -X POST http://localhost:8000/api/v1/gemini/review \
  -d '{"code": "...", "review_type": "simplicity"}' &
wait

Pipeline (Sequential)

Research (Gemini) → Plan (Claude) → Implement (Claude) → Test (Codex) → Review (Gemini)

Swarm (Self-Organizing)

Workers claim tasks from a shared pool:

curl -X POST http://localhost:8000/api/v1/workflow \
  -d '{
    "task": "Review all files in src/",
    "mode": "swarm",
    "workers": 3
  }'

API Quick Reference

Available Models (2026)

Claude 4.5

Gemini 3

GPT-5.2 (Codex)

Troubleshooting

Services Not Running

# Check status
docker ps | grep synaps

# Start services
cd ~/Synapse && docker compose up -d

# Check health
curl http://localhost:8000/health

View Logs

docker logs synaps-gateway
docker logs synaps-claude
docker logs synaps-gemini
docker logs synaps-codex

Documentation

See SKILL.md for complete API documentation, workflow patterns, and usage examples.

Related Projects

• Synapse - The backend orchestration system
• Oh My Claude Code - Multi-agent orchestration framework
• Claude Swarm SKILL.md - TeammateTool orchestration patterns
• KERNEL for Cursor - Self-evolving Cursor configuration system
• KERNEL for Claude - Self-evolving Claude Code configuration

License

MIT