Synapse

Multi-model orchestration skill for Codex CLI. Synapse coordinates Claude, Gemini, and Codex to deliver higher-quality code changes through structured workflows.

What It Does

Synapse turns a single feature request into a multi-stage, multi-model workflow:

init → analyze → plan → execute → optimize → review

Each stage leverages the strengths of different models:

• Codex: Orchestrator and sole code writer
• Claude: Strict correctness, security, and maintainability analysis
• Gemini: UI/UX authority, accessibility, visual consistency

Quick Start

Prerequisites

• Codex CLI installed
• At least one of: Claude CLI, Gemini CLI (optional but recommended)
• uv (Python package manager)

Installation

1. Copy the Synapse/.codex/skills/synapse directory to your Codex skills folder:

   # Windows
   Copy-Item -Recurse "Synapse\.codex\skills\synapse" "$HOME\.codex\skills\synapse"
   
   # macOS/Linux
   cp -r Synapse/.codex/skills/synapse ~/.codex/skills/synapse

2. Initialize in your project:

   synapse init
   

Usage

From within Codex CLI, use any of these commands:

Command	Description
synapse init	Initialize Synapse state and generate AGENTS.md
synapse workflow <task>	Full end-to-end workflow
synapse feat <task>	Feature development (flexible modes)
synapse frontend <task>	UI-focused workflow (Gemini as authority)
synapse backend <task>	API/logic-focused workflow
synapse analyze <task>	Research and ideation only
synapse plan <task>	Generate implementation plan
synapse execute <plan>	Execute an existing plan
synapse optimize <plan>	Optimization analysis
synapse review <plan>	Code review (hard gate)
synapse debug <issue>	Diagnose and fix issues
synapse test <target>	Add or improve tests

How It Works

Multi-Model Collaboration

Synapse doesn't just call multiple models—it assigns them specific roles:

1. Analysis Phase: Claude and Gemini analyze the task in parallel
2. Planning Phase: Both models contribute planning drafts; Codex synthesizes
3. Execution Phase: Codex writes code; Gemini provides UI prototypes
4. Review Phase: All models review; findings are merged and prioritized

Quality Gates

• Requirements Completeness Score (0-10): Blocks planning if < 7/10
• Hard-Gate Review: No code changes without explicit user approval
• Cross-Check: Flags unrelated changes against expected file list

Graceful Degradation

If a backend is unavailable or times out, Synapse continues with available models. You can run Synapse with just Codex—external models enhance but don't block the workflow.

Project Structure

.synapse/
├── plan/           # Plans, prompts, and analysis artifacts
├── sessions/       # Session logs and index.json
└── .venv/          # Isolated Python environment

Configuration

Synapse uses environment variables for customization:

Variable	Default	Description
CODEAGENT_POST_MESSAGE_DELAY	5	Seconds to wait after Codex message before terminating
CODEX_REQUIRE_APPROVAL	(unset)	If set, disables --dangerously-bypass-approvals-and-sandbox
CODEX_DISABLE_SKIP_GIT_CHECK	(unset)	If set, disables --skip-git-repo-check

Requirements

• Python 3.11+ (managed via uv)
• Codex CLI
• Optional: Claude CLI, Gemini CLI

License

MIT

Contributing

See ARCHITECTURE.md for technical details.