Synapse_COR (sin-aps C-O-R) is an open-source tool that makes LLM calls cheaper and more accurate by splitting any task into "things a shell command can do" and "things that actually need an AI". Shell steps run free. AI steps go to the cheapest available model automatically.
It pairs with the Folder-Agent Doctrine (see docs/folder-agents.md) — a portable, tool-agnostic contract where every operational lane lives in a folder (AGENTS.md / automation.md / skills.md / intake/ library/ output/ logs/). Any agent (Claude Code, Codex, Gemini, OpenSwarm, your own bash script) reads the same files and runs the same operation. Switching tools or vendors becomes a no-op.
You do not need a paid API. The installer detects free options on your system and uses the best one.
You do not need FUTRON, OpenClaw, or any private infrastructure. This repo is fully self-contained.
Fastest path to working (takes ~5 minutes):
# Step 1: get a free LLM (if you have nothing yet)
npm install -g @google/gemini-cli # requires Node 18+
# Step 2: install
git clone https://github.com/FutronPrime/synapse-cor
cd synapse-cor
bash install.sh
# Step 3: add to PATH (the installer prints the exact command for your shell)
export PATH="$HOME/.synapse-forge/bin:$PATH"
# Step 4: verify
synapse-cor run "hello"No Node.js? No npm? No problem. See BOOTSTRAP_GUIDE.md for step-by-step paths including Ollama (local, no internet), Groq (free API key), or just a Google account.
Terms you'll see in this README:
- Specialist — an AI agent configured for one domain (security, code review, content, etc.)
- Cascade — the automatic fallback chain: local model → free API → paid API
- Deterministic step — a shell command that runs with zero LLM tokens
- Full definitions: docs/glossary.md
When you pass a complex goal to an LLM, you get a single overloaded response that burns enterprise tokens and mixes deterministic work (which needs no LLM at all) with probabilistic work (which does). The quality is generic because the model is not specialized.
Synapse_COR solves this by:
- Decomposing any goal into a
PLAN.jsonthat separates deterministic CLI steps from probabilistic LLM steps - Routing each step to the cheapest capable model (local Ollama first, free APIs second, paid last)
- Spawning bespoke specialist agents with scoped personas, MCC cognitive stacks, and behavioral contracts that force compliance and dramatically reduce hallucination risk
- Running a ValidationAgent after every dispatch to catch failures before they propagate
Goal → Synapse_COR (Context · Objective · Role analysis)
|
v
PLAN.json
/ \
Deterministic Probabilistic LLM steps
CLI steps (cheapest capable model)
(no LLM) |
\ v
\ COMPOSE: build specialist
\ (persona + MCC stack + CoR template)
\ |
\ v
+-----> DISPATCH: fire → ValidationAgent verify
|
v
Verified Output
|
(cascade routing:
local → free API → paid)
Context · Objective · Role — each step gets the right specialist, not a general model:
- Context — understand what the caller is asking, identify scope and constraints
- Objective — determine the exact required outcome (Build / Analyze / Audit / Guide / Validate)
- Role — activate the correct specialist mode (Architect / Translator / Editor / Compressor / Guide)
| Synapse_COR | Raw LLM call | LangGraph | CrewAI | |
|---|---|---|---|---|
| Token efficiency | High — CLI steps bypass LLM | Low — everything goes through LLM | Medium | Medium |
| Deterministic split | Yes — explicit PLAN.json | No | Partial | No |
| Model routing | Local → free → paid cascade | Single endpoint | Manual | Manual |
| Hallucination controls | Behavioral contracts + ValidationAgent | Prompt-level only | Prompt-level only | Prompt-level only |
| Setup overhead | Single script | None | High | High |
| OpenAI-compatible | Yes | Depends | Yes | Yes |
1. Code review specialist on free models
Spawn a code-reviewer specialist on opencode/nemotron-3-super-free, pass your diff. The PLAN separates deterministic lint/grep steps (no LLM) from probabilistic architecture review (LLM). You pay zero tokens for the mechanical part.
2. Financial market data analysis
A financial-analyst specialist with MCC-S4 (PRECISION-EXECUTOR) stack pulls candlestick data via CLI, then feeds the LLM only the cleaned series — not the raw JSON. Reduces prompt size by 60-80% on typical market data payloads.
3. Security audit pipeline
security-auditor specialist runs grep, bandit, semgrep deterministically for known patterns, then hands only ambiguous findings to the LLM for triage. Catches 90%+ of common vulnerabilities before the LLM sees a single token.
4. Phantom file reconstruction (PoC: 8/8 reconstructed)
phantom-file-archaeologist specialist reconstructed 8 deleted/corrupted source files from session logs, git history, and docstring fragments alone. Deterministic steps extracted fragments; LLM steps synthesized coherent code. Zero hallucinated function signatures — all validated against live import tests.
5. Content generation with persona constraints
content-strategist specialist enforces brand voice, tone constraints, and platform limits (Twitter/LinkedIn/Instagram) via behavioral contracts before the first output token. Eliminates post-generation editing loops.
6. Multi-step research workflows
Chain web-search → summarize → synthesize → format where each step routes to the cheapest capable model. The orchestrator tracks state in PLAN.json — restart any step without rerunning the full chain.
git clone https://github.com/FutronPrime/synapse-cor
cd synapse-cor
bash install.sh
# Add to PATH:
export PATH="$HOME/.synapse-forge/bin:$PATH"
# That's it. The installer scans your system and picks the cheapest available LLM.
synapse-cor run "audit my project for security issues"The installer auto-detects what you already have. No config required if any of these are present: Ollama, LM Studio, Gemini CLI, or any *_API_KEY environment variable.
The bundle scans your system in priority order and uses the first working provider:
1. SYNAPSE_FORGE_URL (explicit override — always wins)
|
v
2. Local Ollama at :11434 ← free, private, no internet
|
v
3. Local LM Studio / vLLM at :1234, :8000, :5000 ← free, private
|
v
4. Gemini CLI OAuth (~/.gemini/google_accounts.json) ← free, 1000 req/day
|
v
5. Gemini CLI --free flag ← free, no login (unofficial endpoint*)
|
v
6. GEMINI_API_KEY env / ~/.openclaw/credentials/llm.env ← free tier available
|
v
7. OPENAI_API_KEY ← paid
|
v
8. ANTHROPIC_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY ← paid / free tier
|
v
9. Codex OAuth (~/.codex/auth.json) ← ChatGPT Plus subscription
|
v
[stub mode — goal is planned and structured, LLM call deferred]
*Gemini CLI --free uses an unofficial endpoint per Reddit r/commandline community research. Works without any account. May change without notice.
To see what was detected on your machine:
synapse-cor detectPick any one:
# Option 1: Gemini CLI free mode — no sign-in, works immediately
npm install -g @google/gemini-cli
# Option 2: Gemini with free Google account (1000 req/day)
npm install -g @google/gemini-cli && gemini # sign in once
# Option 3: Ollama — runs models locally, fully private
# https://ollama.com → install → ollama pull llama3
# Option 4: Groq free API key (fast, generous free tier)
# https://console.groq.com → get key → export GROQ_API_KEY=gsk_...Then re-run bash install.sh — it will detect the new provider automatically.
# Full pipeline (most common):
synapse-forge run "audit my codebase for security vulnerabilities"
# Step by step:
synapse-forge plan "your goal" # outputs PLAN.json
synapse-forge compose plan.json # registers/builds specialists
synapse-forge dispatch plan.json # fires tasks, validates outputs
# Utilities:
synapse-forge status # show registered specialists + endpoint health
# Phantom file reconstruction:
synapse-forge run "reconstruct deleted auth.py from git history and session logs"
# Security audit:
synapse-forge run "audit my project for security issues"# Point at FUTRON Forge endpoint and shared registry:
export SYNAPSE_FORGE_URL=http://127.0.0.1:9055
export SYNAPSE_FORGE_REGISTRY=~/.openclaw/state/futron-forge/specialists.json
# Same CLI — now routes through FUTRON's 25-provider LLM cascade:
synapse-forge run "review this PR for architecture issues"
# Specialists auto-register in FUTRON's unified specialist registry,
# shared across all FUTRON agents in the network.from synapse_forge import SynapseCOR
# Standalone
engine = SynapseCOR()
result = engine.run("audit my project for security vulnerabilities")
print(result.summary)
# Custom specialist
from synapse_forge import upsert_specialist
upsert_specialist({
"id": "my-domain-expert",
"synapse_persona": "I am an expert in distributed systems...",
"mcc_stack": "S3-INSIGHT-CATALYST",
"model": "gpt-4o-mini",
"fallback_model": "gpt-3.5-turbo",
"required_agents": ["PromptAgent", "ValidationAgent"],
"required_protocols": ["QualityControlProtocol", "ValidationProtocol"],
"cor_template": {
"goal": "", "progress": 0, "preferences": [], "adjustments": "",
"strategy": ["1. Gather", "2. Analyze", "3. Report"],
"expertise": "Distributed systems architecture", "verbosity": "med"
}
})| Specialist | MCC Stack | Primary Use |
|---|---|---|
security-auditor |
S4-PRECISION-EXECUTOR | Credential scan, threat detection, OWASP audit |
code-reviewer |
S3-INSIGHT-CATALYST | Static analysis, architecture review, PR triage |
content-strategist |
S2-STRUCTURED-BUILDER | Social media, captions, content calendar |
financial-analyst |
S4-PRECISION-EXECUTOR | Market data, portfolio analysis, trading signals |
ui-auditor |
S3-INSIGHT-CATALYST | UI regression, tab/panel audit, accessibility |
phantom-file-archaeologist |
S5-ENLIGHTENMENT | File recovery, session archaeology, code reconstruction |
New specialists are auto-composed when needed. Add your own to specialists.json.
| Variable | Default | Description |
|---|---|---|
SYNAPSE_FORGE_HOME |
~/.synapse-forge |
Base install directory |
SYNAPSE_FORGE_REGISTRY |
$HOME/.synapse-forge/specialists.json |
Specialist registry path |
SYNAPSE_FORGE_URL |
(auto-detect) | OpenAI-compatible LLM endpoint — omit to use auto-detection |
SYNAPSE_FORGE_API_KEY |
(empty) | API key for endpoint |
SYNAPSE_FORGE_MODEL |
opencode/nemotron-3-super-free |
Default model |
SYNAPSE_FORGE_FALLBACK |
gpt-4o-mini |
Fallback model (always 2 backends) |
- Deterministic CLI steps bypass LLM entirely — grep, git, jq, lint run as-is
- Behavioral contracts (prompt software) force compliance before the first output token
- ValidationAgent post-dispatch verification on every step
- 5-block ErrorHandlingProtocol on failures: What / Why / Impact / Fix / Prevent
- MCC cognitive stacks tune reasoning style and error sensitivity per domain
If you have FUTRON installed, install.sh auto-detects it and shows integration instructions. The OpenSwarm adapter (adapters/openswarm/) documents how Synapse_COR plugs into FUTRON's 25-provider LLM cascade and shared specialist registry.
| Adapter | Description |
|---|---|
adapters/claude-code/ |
Claude Code (Anthropic) integration |
adapters/codex/ |
OpenAI Codex / Codex CLI integration |
adapters/gemini/ |
Google Gemini API integration (requires GEMINI_API_KEY) |
adapters/gemini-cli-free/ |
Gemini CLI free-mode adapter — zero config, no API key needed |
adapters/generic-openai/ |
Any OpenAI-compatible endpoint (Ollama, vLLM, LM Studio) |
adapters/openswarm/ |
OpenSwarm + FUTRON Forge integration |
from synapse_forge import upsert_specialist
upsert_specialist({
"id": "my-specialist",
"synapse_persona": "I am an expert in...",
"mcc_stack": "S3-INSIGHT-CATALYST",
"model": "gpt-4o-mini",
"fallback_model": "gpt-3.5-turbo",
"required_agents": ["PromptAgent", "ValidationAgent"],
"required_protocols": ["QualityControlProtocol", "ValidationProtocol"],
"cor_template": {
"goal": "", "progress": 0, "preferences": [], "adjustments": "",
"strategy": ["1. Gather", "2. Analyze", "3. Report"],
"expertise": "Expertise in my domain", "verbosity": "med"
}
})See docs/extending.md for the full specialist schema.
- Fork the repo
- Add specialists in
templates/specialist-spec.schema.json - Add examples in
examples/ - Add adapters in
adapters/for new LLM runtimes - PR with title:
feat: add <domain> specialistorfix: <issue>
| Document | What it covers |
|---|---|
| BOOTSTRAP_GUIDE.md | Start from zero — install Python, Node.js, and a free LLM |
| docs/quickstart.md | First pipeline walkthrough once prerequisites are met |
| docs/glossary.md | Plain-language definitions: Synapse_COR, Forge, MCC, CoR, cascade, specialist |
| docs/architecture.md | Full pipeline diagram and component descriptions |
| docs/extending.md | Add your own specialists and adapters |
| docs/use-cases.md | Worked examples with commands and sample output |
| docs/folder-agents.md | Folder-agent doctrine — portable, tool-agnostic lanes that pair with specialists |
| docs/troubleshooting.md | Error messages, root causes, and exact fixes |
| CONTRIBUTING.md | How to contribute specialists, adapters, and fixes |
MIT — see LICENSE. Free for any use including commercial.
- DJ Generation — founding concepts, coined "Prompt Software", Synapse_COR architecture
- Synaptic Labs & WarlockAI — Professor Synapse prompt integration
- Claude R&D — initial Professor Synapse integration and error handling design