https://github.com/snakeying/synapse
Multi-model AI workflow: Claude & Gemini draft code, Codex reviews and applies—safe, gated, production-ready. 多模型 AI 工作流：Claude 与 Gemini 起草代码，Codex 审查并应用——安全、门控、生产级
https://github.com/snakeying/synapse
claude-code codex-cli codex-skills gemini-cli
Last synced: 1 day ago
JSON representation
Multi-model AI workflow: Claude & Gemini draft code, Codex reviews and applies—safe, gated, production-ready. 多模型 AI 工作流：Claude 与 Gemini 起草代码，Codex 审查并应用——安全、门控、生产级
- Host: GitHub
- URL: https://github.com/snakeying/synapse
- Owner: snakeying
- License: mit
- Created: 2026-02-07T07:14:45.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-08T12:45:43.000Z (4 months ago)
- Last Synced: 2026-02-08T18:11:22.075Z (4 months ago)
- Topics: claude-code, codex-cli, codex-skills, gemini-cli
- Language: Python
- Homepage:
- Size: 186 KB
- Stars: 26
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Synapse
Codex-Based Multi-Model Workflow
Multi-model AI meets production standards
Draft by Claude & Gemini · Review by Codex · Deploy with confidence
简体中文 | English
---
## 🤔 What is this?
Synapse is a **Codex skill** that orchestrates multiple AI models to help you build software:
```mermaid
flowchart TB
subgraph Orchestrator["Codex (Controller)"]
direction TB
A1["Generates prompts"]
A2["Rewrites drafts into production code"]
A3["Runs verification & delivers"]
end
Orchestrator --> Claude["Claude
(Planning · Backend diffs · Audits)"]
Orchestrator --> Gemini["Gemini
(Frontend diffs · UI/UX audits)"]
```
**Key principle**: External models (Claude/Gemini) only produce **drafts** — they never touch your files directly. Codex reviews every draft and rewrites it into production-quality code before applying.
---
## ✨ Core Features
| Feature | Description |
|---------|-------------|
| 📝 Draft-based | External models produce draft diffs; Codex applies final code |
| 🚪 Gate confirmation | Human approval required after planning, before execution |
| 🛡️ Write guard | All file writes are restricted to declared safe paths |
| ✅ Auto-verification | Detects your toolchain and runs lint/typecheck/test automatically |
| 🔄 Session resume | Pick up where you left off with captured session IDs |
| 🌐 Web viewer | Browse all artifacts locally via `synapse ui` |
---
## 🚀 Quick Start
### 📋 Prerequisites
| Tool | Required |
|------|----------|
| git | Recommended (enables review/audit via `git diff`) |
| rg (ripgrep) | Recommended (enables context pack search) |
| uv | Yes (Python runner) |
| claude CLI | Yes |
| gemini CLI | Yes |
### 💬 Usage (in Codex chat)
```powershell
# End-to-end workflow: init through review
synapse workflow "Add user authentication with JWT"
# Same thing, shorter alias
synapse feat "Add user authentication with JWT"
```
Codex automatically orchestrates the full pipeline: `init` → `plan` → Gate → `run` (drafts) → apply code → `verify` → `run` (audits) → deliver.
> **Note**: `workflow` and `feat` are Codex chat commands, not shell commands. You cannot run them directly via `python synapse.py workflow ...`.
### 🔧 Manual commands (advanced)
For debugging or reproducing individual steps:
```powershell
$Skill = "\.codex\skills\synapse"
$Project = ""
# Initialize (idempotent)
uv run --no-project python "$Skill\scripts\synapse.py" --project-dir "$Project" init
# Create a plan
uv run --no-project python "$Skill\scripts\synapse.py" --project-dir "$Project" plan --task-type fullstack "Your request"
# Run an external model (prompt written by Codex)
uv run --no-project python "$Skill\scripts\synapse.py" --project-dir "$Project" run --model claude --phase plan --slug "" --prompt-file ""
# Verify (auto-detects toolchain)
uv run --no-project python "$Skill\scripts\synapse.py" --project-dir "$Project" verify
# Open web viewer
uv run --no-project python "$Skill\scripts\synapse.py" --project-dir "$Project" ui
```
---
## 🔄 Workflow Overview
```
init → plan → run (gate_prep) → (Gate) → run (drafts) → Codex applies code → verify → run (audits) → deliver
│
Single confirmation
```
| Stage | What happens | Writes code |
|-------|-------------|:-----------:|
| init | Creates `.synapse/` layout, `AGENTS.md`, `.gitignore` | |
| plan | Generates plan stub + Gate checklist + context pack | |
| run (gate_prep) | Claude prepares a clarification checklist + acceptance criteria (Gemini optional for frontend) | |
| **Gate** | **User confirms scope, task type, side effects** | |
| run (drafts) | Claude/Gemini produce draft diffs | |
| apply | Codex rewrites drafts into production code | Yes |
| verify | Auto-detects toolchain, runs lint/typecheck/test | |
| run (audits) | Claude/Gemini review the final `git diff` | |
---
## 🤖 Model Roles
| Role | Codex (Controller) | Claude | Gemini |
|------|-------------------|--------|--------|
| Planning | Merges into final plan | Architecture, risks, tests | UI/UX, accessibility (frontend/fullstack only) |
| Drafting | Rewrites drafts to production code | Backend diffs (backend/fullstack) | Frontend diffs (frontend/fullstack) |
| Verification | Runs and interprets results | Not called | Not called |
| Auditing | Fixes code based on audits | Correctness, security, maintainability | UI/UX, accessibility (frontend/fullstack only) |
**Task type routing** (set at plan time):
- `frontend` — only frontend pipeline
- `backend` — only backend pipeline
- `fullstack` — both (default, higher cost)
---
## 🚪 Gate
The single required user confirmation. After `plan` (+ `gate_prep`), Codex presents:
- Clarification checklist (from Claude `gate_prep`) with recommended defaults (single-round reply)
- Scope and acceptance criteria
- `task_type` selection (with recommendation)
- Stack/toolchain choice
- Allowed side effects (dependency install, lockfiles, build artifacts)
- Git/review setup
- Verification plan
After Gate confirmation, the rest proceeds automatically.
---
## 📌 Git Best Practices
- **Use a git repo** — review/audit quality is best with `git diff`. Run `git init` if needed.
- **Commit after each feat** — keeps the next `git diff` clean and focused.
- **Before review** — run `git add -N .` so new untracked files appear in `git diff`.
---
## ❓ FAQ
Q: Why don't external models write code directly?
External models run headlessly with no auto-approve. Their output is treated as a draft. Codex rewrites it to match project conventions, adds tests, and ensures quality before applying.
Q: What does `synapse verify` actually run?
It auto-detects your toolchain (Node, Python, Rust, Go, .NET) and runs the appropriate install/lint/typecheck/test commands. Use `--dry-run` to preview without executing.
Q: Can I use only Claude or only Gemini?
Yes. Set `--task-type backend` (Claude only) or `--task-type frontend` (Gemini only). With `fullstack`, both are used.
Q: Where do artifacts go?
All artifacts are written to `.synapse/` in your project root (auto-added to `.gitignore`). Use `synapse ui` to browse them in a local web viewer.
---
## 📚 More Information
- [ARCHITECTURE.md](ARCHITECTURE.md) — Technical details, module structure, internal mechanisms
- `.codex/skills/synapse/SKILL.md` — Codex execution protocol
- `.codex/skills/synapse/references/*.md` — Per-command specifications
---
## 📄 License
MIT