{"id":50965618,"url":"https://github.com/snakeying/synapse","last_synced_at":"2026-06-18T20:01:39.583Z","repository":{"id":337222664,"uuid":"1151986370","full_name":"snakeying/Synapse","owner":"snakeying","description":"Multi-model AI workflow: Claude \u0026 Gemini draft code, Codex reviews and applies—safe, gated, production-ready. 多模型 AI 工作流：Claude 与 Gemini 起草代码，Codex 审查并应用——安全、门控、生产级","archived":false,"fork":false,"pushed_at":"2026-02-08T12:45:43.000Z","size":190,"stargazers_count":26,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-08T18:11:22.075Z","etag":null,"topics":["claude-code","codex-cli","codex-skills","gemini-cli"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/snakeying.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-07T07:14:45.000Z","updated_at":"2026-02-08T12:45:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/snakeying/Synapse","commit_stats":null,"previous_names":["snakeying/synapse"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/snakeying/Synapse","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snakeying%2FSynapse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snakeying%2FSynapse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snakeying%2FSynapse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snakeying%2FSynapse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/snakeying","download_url":"https://codeload.github.com/snakeying/Synapse/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snakeying%2FSynapse/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34505423,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","codex-cli","codex-skills","gemini-cli"],"created_at":"2026-06-18T20:01:38.462Z","updated_at":"2026-06-18T20:01:39.571Z","avatar_url":"https://github.com/snakeying.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\nSynapse\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eCodex-Based Multi-Model Workflow\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eMulti-model AI meets production standards\u003c/strong\u003e\u003cbr/\u003e\n  \u003cem\u003eDraft by Claude \u0026 Gemini · Review by Codex · Deploy with confidence\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README_CN.md\"\u003e简体中文\u003c/a\u003e | English\n\u003c/p\u003e\n\n---\n\n## 🤔 What is this?\n\nSynapse is a **Codex skill** that orchestrates multiple AI models to help you build software:\n\n```mermaid\nflowchart TB\n    subgraph Orchestrator[\"Codex (Controller)\"]\n        direction TB\n        A1[\"Generates prompts\"]\n        A2[\"Rewrites drafts into production code\"]\n        A3[\"Runs verification \u0026 delivers\"]\n    end\n\n    Orchestrator --\u003e Claude[\"Claude\u003cbr/\u003e(Planning · Backend diffs · Audits)\"]\n    Orchestrator --\u003e Gemini[\"Gemini\u003cbr/\u003e(Frontend diffs · UI/UX audits)\"]\n```\n\n**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.\n\n---\n\n## ✨ Core Features\n\n| Feature | Description |\n|---------|-------------|\n| 📝 Draft-based | External models produce draft diffs; Codex applies final code |\n| 🚪 Gate confirmation | Human approval required after planning, before execution |\n| 🛡️ Write guard | All file writes are restricted to declared safe paths |\n| ✅ Auto-verification | Detects your toolchain and runs lint/typecheck/test automatically |\n| 🔄 Session resume | Pick up where you left off with captured session IDs |\n| 🌐 Web viewer | Browse all artifacts locally via `synapse ui` |\n\n---\n\n## 🚀 Quick Start\n\n### 📋 Prerequisites\n\n| Tool | Required |\n|------|----------|\n| git | Recommended (enables review/audit via `git diff`) |\n| rg (ripgrep) | Recommended (enables context pack search) |\n| uv | Yes (Python runner) |\n| claude CLI | Yes |\n| gemini CLI | Yes |\n\n### 💬 Usage (in Codex chat)\n\n```powershell\n# End-to-end workflow: init through review\nsynapse workflow \"Add user authentication with JWT\"\n\n# Same thing, shorter alias\nsynapse feat \"Add user authentication with JWT\"\n```\n\nCodex automatically orchestrates the full pipeline: `init` → `plan` → Gate → `run` (drafts) → apply code → `verify` → `run` (audits) → deliver.\n\n\u003e **Note**: `workflow` and `feat` are Codex chat commands, not shell commands. You cannot run them directly via `python synapse.py workflow ...`.\n\n### 🔧 Manual commands (advanced)\n\nFor debugging or reproducing individual steps:\n\n```powershell\n$Skill   = \"\u003cpath-to\u003e\\.codex\\skills\\synapse\"\n$Project = \"\u003cyour-project\u003e\"\n\n# Initialize (idempotent)\nuv run --no-project python \"$Skill\\scripts\\synapse.py\" --project-dir \"$Project\" init\n\n# Create a plan\nuv run --no-project python \"$Skill\\scripts\\synapse.py\" --project-dir \"$Project\" plan --task-type fullstack \"Your request\"\n\n# Run an external model (prompt written by Codex)\nuv run --no-project python \"$Skill\\scripts\\synapse.py\" --project-dir \"$Project\" run --model claude --phase plan --slug \"\u003cslug\u003e\" --prompt-file \"\u003cprompt\u003e\"\n\n# Verify (auto-detects toolchain)\nuv run --no-project python \"$Skill\\scripts\\synapse.py\" --project-dir \"$Project\" verify\n\n# Open web viewer\nuv run --no-project python \"$Skill\\scripts\\synapse.py\" --project-dir \"$Project\" ui\n```\n\n---\n\n## 🔄 Workflow Overview\n\n```\ninit → plan → run (gate_prep) → (Gate) → run (drafts) → Codex applies code → verify → run (audits) → deliver\n                         │\n                   Single confirmation\n```\n\n| Stage | What happens | Writes code |\n|-------|-------------|:-----------:|\n| init | Creates `.synapse/` layout, `AGENTS.md`, `.gitignore` | |\n| plan | Generates plan stub + Gate checklist + context pack | |\n| run (gate_prep) | Claude prepares a clarification checklist + acceptance criteria (Gemini optional for frontend) | |\n| **Gate** | **User confirms scope, task type, side effects** | |\n| run (drafts) | Claude/Gemini produce draft diffs | |\n| apply | Codex rewrites drafts into production code | Yes |\n| verify | Auto-detects toolchain, runs lint/typecheck/test | |\n| run (audits) | Claude/Gemini review the final `git diff` | |\n\n---\n\n## 🤖 Model Roles\n\n| Role | Codex (Controller) | Claude | Gemini |\n|------|-------------------|--------|--------|\n| Planning | Merges into final plan | Architecture, risks, tests | UI/UX, accessibility (frontend/fullstack only) |\n| Drafting | Rewrites drafts to production code | Backend diffs (backend/fullstack) | Frontend diffs (frontend/fullstack) |\n| Verification | Runs and interprets results | Not called | Not called |\n| Auditing | Fixes code based on audits | Correctness, security, maintainability | UI/UX, accessibility (frontend/fullstack only) |\n\n**Task type routing** (set at plan time):\n\n- `frontend` — only frontend pipeline\n- `backend` — only backend pipeline\n- `fullstack` — both (default, higher cost)\n\n---\n\n## 🚪 Gate\n\nThe single required user confirmation. After `plan` (+ `gate_prep`), Codex presents:\n\n- Clarification checklist (from Claude `gate_prep`) with recommended defaults (single-round reply)\n- Scope and acceptance criteria\n- `task_type` selection (with recommendation)\n- Stack/toolchain choice\n- Allowed side effects (dependency install, lockfiles, build artifacts)\n- Git/review setup\n- Verification plan\n\nAfter Gate confirmation, the rest proceeds automatically.\n\n---\n\n## 📌 Git Best Practices\n\n- **Use a git repo** — review/audit quality is best with `git diff`. Run `git init` if needed.\n- **Commit after each feat** — keeps the next `git diff` clean and focused.\n- **Before review** — run `git add -N .` so new untracked files appear in `git diff`.\n\n---\n\n## ❓ FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003eQ: Why don't external models write code directly?\u003c/summary\u003e\n\nExternal 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.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eQ: What does `synapse verify` actually run?\u003c/summary\u003e\n\nIt 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.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eQ: Can I use only Claude or only Gemini?\u003c/summary\u003e\n\nYes. Set `--task-type backend` (Claude only) or `--task-type frontend` (Gemini only). With `fullstack`, both are used.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eQ: Where do artifacts go?\u003c/summary\u003e\n\nAll artifacts are written to `.synapse/` in your project root (auto-added to `.gitignore`). Use `synapse ui` to browse them in a local web viewer.\n\n\u003c/details\u003e\n\n---\n\n## 📚 More Information\n\n- [ARCHITECTURE.md](ARCHITECTURE.md) — Technical details, module structure, internal mechanisms\n- `.codex/skills/synapse/SKILL.md` — Codex execution protocol\n- `.codex/skills/synapse/references/*.md` — Per-command specifications\n\n---\n\n## 📄 License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnakeying%2Fsynapse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnakeying%2Fsynapse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnakeying%2Fsynapse/lists"}