Purpose
The Brain is a Python CLI orchestration system that offloads AI tasks from Claude to free provider APIs. Claude acts as orchestrator — deciding what to do and which worker to use — while the actual AI work (summarization, code generation, classification, etc.) is handled by free-tier providers. All calls are logged for cost tracking.
Core promise: Claude only does what only Claude can do. Everything else is delegated.
Tech Stack
| Component | Technology |
|---|---|
| Runtime | Python 3 |
| Entry point | delegate.py CLI |
| Provider adapters | brain/adapters/ — one file per provider |
| Routing logic | brain/router.py |
| Stats tracking | brain/stats.py → stats/usage.json |
| Orchestrator | brain/orchestrator.py |
| Integration | Global CLAUDE.md routing table |
CLI Interface
python delegate.py --provider <name> --type <type> --prompt "<prompt>"Claude reads the routing table in CLAUDE.md and calls delegate.py directly. The result is returned on stdout and relayed to the user.
Task Types
| Type | Best Provider | Use case |
|---|---|---|
classification | cerebras | Yes/no, scoring, labelling |
factual_qa | cerebras / groq | Quick factual questions, general explanation |
summarization | gemini | Long text compression, 1M token context |
translation | gemini | Any language pair |
coding | mistral | Code generation, debugging |
extraction | mistral | Structured data extraction from text |
creative | mistral | Writing, drafting, brainstorming |
reasoning | sambanova | Deep analysis, trade-off evaluation |
general | cerebras | Anything that doesn't fit above |
Provider Registry
| Key | Default Model | Speed | Notes |
|---|---|---|---|
cerebras | llama3.1-8b | ~284ms | Ultra-fast; best for classification and quick Q&A |
groq | llama-3.1-8b-instant | ~366ms | Fast LPU inference; general fallback |
gemini | gemini-2.5-flash-lite | ~541ms | 1M token context; best for long docs, translation |
mistral | mistral-small-latest | ~1172ms | Best free quality for coding and creative tasks |
sambanova | Meta-Llama-3.3-70B | ~1.4s | 70B model; highest free-tier quality for reasoning |
fireworks | llama-v3p3-70b-instruct | fast | Strong coding; DeepSeek V3 available |
openai | gpt-4o-mini | standard | Reliable all-rounder |
cohere | command-r-08-2024 | standard | Retrieval and extraction specialist |
cloudflare | llama-3.1-8b-instruct | fast | Edge-hosted; no credit card required |
huggingface | Qwen2.5-72B-Instruct | slow | Last-resort fallback; broad model selection |
openrouter | gemma-4-26b-a4b-it:free | standard | 50+ models via one key |
ollama | qwen2.5-coder:7b | local | Local inference; fully private, no API key |
pollinations | openai / flux | varies | Keyless; text and image generation fallback |
Repository Structure
the-brain/
├── delegate.py # CLI entry point — call this to offload
├── session_start.py # Session startup: prints provider health + stats
├── report.py # Usage stats report
├── push_stats.py # Update GitHub README with usage stats
├── health_check.py # Provider health polling
├── brain/
│ ├── orchestrator.py # Core dispatcher
│ ├── router.py # Routing table and fallback chains
│ ├── stats.py # Persistent usage tracking
│ └── adapters/ # One file per provider
├── config/
│ ├── keys.json # API keys (not committed)
│ └── keys.example.json # Template
├── stats/
│ └── usage.json # Running usage log (auto-created)
├── assets/
│ └── brain.png # Project image
└── docs/
└── index.html # Public project page (GitHub Pages)Persistence
| File | Contents |
|---|---|
.env | API keys per provider (gitignored) |
stats/usage.json | Aggregate lifetime totals per provider; last 100 calls for display (bounded) |
stats/call_log.jsonl | Permanent per-call history — one JSON line per delegate call, never truncated |
stats/health_log.json | Append-only health probe results — one entry per provider/model per check cycle |
stats/model_state.json | Per-model state: active / paused / disabled with reason and timestamp |
Integration with Claude Code
The Brain is activated by adding a routing table to the global CLAUDE.md (at C:\Users\<user>\.claude\CLAUDE.md). Claude reads this at session start and automatically delegates matching tasks rather than answering them directly.
Session startup runs session_start.py which prints live provider health and usage stats so routing advisories can be relayed before any work begins.