~1 MB binary. Sub-50ms startup. Zero config required.
Website | Demo | Blog: Why a local brain? | Releases
What it does for you
Run claudectl --brain-stats impact to see your numbers:
╔════════════════════════════════════════════════╗
║ IMPACT SCORECARD ║
║ 1200 decisions tracked ║
╠════════════════════════════════════════════════╣
║ Auto-handled 71% ║
║ ████████████████████░░░░░░░░ 847/1200 ║
║ ║
║ Brain accuracy 96.2% ║
║ ███████████████████████████░ 1154/1200 ║
║ ║
║ Coverage vs static rules 2.9x ║
║ brain ████████████████████████████ 100% ║
║ rules █████████░░░░░░░░░░░░░░░░░░░ 34% ║
║ ║
║ Dangerous ops blocked 12 Time saved 42m ║
║ 2 critical | 10 high-risk | 847 auto x 3s ║
║ ║
║ Learning: correction rate 8.4% ↓ 2.1% (-6pp) ║
╚════════════════════════════════════════════════╝
Install
brew install mercurialsolo/tap/claudectl # Homebrew (macOS / Linux)
cargo install claudectl # Cargo (any platform)
curl -fsSL https://raw.githubusercontent.com/mercurialsolo/claudectl/main/install.sh | sh
nix run github:mercurialsolo/claudectl
git clone https://github.com/mercurialsolo/claudectl.git && cd claudectl && cargo install --path .
Get started
claudectl # Live dashboard — see all sessions at a glance
claudectl --init # Wire up Claude Code hooks (one-time)
claudectl --brain # Enable local LLM auto-pilot
Why claudectl
- Local LLM auto-pilot — a brain that learns your preferences and auto-approves/denies tool calls. No cloud API.
- Hive mind — knowledge distillation, archiving, and curriculum generation. Connect instances to share learnings across machines.
- Self-improving — detects friction patterns, suggests rules, and gets smarter with every correction.
- Multi-session orchestration — run parallel tasks with dependency ordering and cross-session context routing.
- Health monitoring — catches cognitive decay, cost spikes, error loops, and context saturation before they waste money.
- Works everywhere — Claude Code plugin for inline use, TUI dashboard for oversight, CLI for automation.
Local LLM Brain
The brain observes all your sessions and makes real-time decisions:
- Approve safe tool calls automatically (reads, greps, test runs)
- Deny dangerous operations before they execute (force pushes, destructive commands)
- Terminate sessions that are looping, stalled, or burning money
- Route summarized output between sessions so they share context
- Spawn new sessions when the brain detects parallelizable work
ollama pull gemma4:e4b && ollama serve # One-time setup
claudectl --brain # Advisory mode (default)
claudectl --brain --auto-run # Auto mode: brain executes without asking
claudectl --mode auto # Or toggle mid-session (Ctrl+b in TUI)
Works with any OpenAI-compatible endpoint: ollama, llama.cpp, vLLM, LM Studio.
How the brain learns
The brain learns from everything you do — not just brain-involved decisions, but every manual approve, reject, rule execution, and conflict resolution. All data stays on your machine.
| Level | What it learns | Example |
|---|---|---|
| Conditional preferences | Context-dependent rules via decision tree splits | approve [Bash] "git push" when cost<$5 (n=8) |
| Outcome tracking | Correlates decisions to detect "approved but broke" | Downweights false-positive approvals |
| Temporal patterns | Behavioral sequences and time-of-day behavior | After 3+ errors: user usually denies |
| Per-project models | Separate preferences per project | [Read] always approve in frontend, usually deny in infra |
| Adaptive thresholds | Per-tool confidence requirements based on accuracy | 90%+ accurate on Read = auto-execute at 0.5 confidence |
Self-improving sessions
The brain automatically detects friction patterns and suggests workflow improvements:
claudectl --brain --insights on # Enable auto-generation (every 10 decisions)
claudectl --brain --insights # View current insights
Detects: friction patterns, error loops, context blowouts, missing rules, accuracy gaps, cost trends. Only new insights are surfaced — the system tracks what you've already seen. Use /auto-insights in the Claude Code plugin.
Claude Code Plugin
Integrates the brain directly into Claude Code sessions — no TUI required.
| Component | What it does |
|---|---|
| Brain gate hook | Queries the brain before every Bash/Write/Edit call |
/brain on|off|auto |
Toggle brain mode mid-session (or Ctrl+b in TUI) |
/sessions |
Show all active sessions with status, cost, health |
/spend |
Cost breakdown by project and time window |
/brain-stats |
Brain learning metrics and accuracy |
/auto-insights |
Auto-generated workflow insights |
Headless Mode
Run the full autonomous stack without a TUI. Attach a dashboard from another terminal.
claudectl --headless --brain --auto-run # Human-readable events
claudectl --headless --brain --auto-run --json # Structured JSON events
What runs in headless mode:
- Brain inference (approve/deny/route/spawn with adaptive confidence)
- Coordination layer (leases, interrupts, handoffs, memory)
- Context rot prevention (auto-raises compact/stop interrupts when decay detected)
- Rule evaluation and health monitoring
The TUI dashboard can run alongside -- both share state via the coordination SQLite store, brain decision logs, and session discovery.
# Background daemon
nohup claudectl --headless --brain --auto-run > ~/.claudectl/autopilot.jsonl 2>&1 &
# Attach dashboard in another terminal
claudectl
Coordination Layer
Multi-agent coordination for parallel coding sessions. Prevents duplicate work, manages ownership, and routes context between agents.
Build with cargo build --features coord to enable.
# Ownership leases — prevent two agents from editing the same file
claudectl coord claim --session sess_1 --path src/app.rs --mode exclusive
claudectl coord release lease_123
# Handoffs — structured context transfer between sessions
claudectl coord handoff --from sess_1 --to sess_2 --task task_1 --summary 'Fix path normalization'
# Interrupts — typed cross-agent signals with delivery modes
claudectl coord raise --type pause --target sess_1 --reason 'lease conflict'
claudectl coord ack intr_123
# Memory — validated patterns promoted from brain decisions
claudectl coord promote --project myproject
claudectl coord context --session sess_1 # Preview injected context
# Inspection
claudectl coord leases # Active ownership leases
claudectl coord interrupts # Pending interrupts
claudectl coord events # Event audit log
claudectl coord metrics # Coordination health metrics
claudectl coord eval # Run 10 eval scenarios
claudectl coord adapters # Registered agent adapters
The coordination layer stores state in a local SQLite database (~/.claudectl/coord/coord.db) and injects compact context into the brain's prompt before every decision.
Hive Mind & Relay
The brain distills your decisions into shareable knowledge. Connect instances across machines to build a convergent hive mind.
# Hive knowledge is built-in — view what the brain has learned
claudectl hive status
claudectl hive knowledge
claudectl hive distill # Condense archive into curriculum
# Add relay for cross-machine networking
cargo install claudectl --features relay
claudectl relay invite # Generate an invite code
claudectl relay join YEK-AGA-YHK-QAA-BM # Join from another machine
claudectl relay discover # Scan LAN for nearby instances
# Start coordinator with HTTP API for multi-machine dashboard
claudectl relay serve --http-port 9876 --auth-token secret
# Remote sessions appear