Auto-pilot for Claude Code.
A local on-device model that learns what to approve, deny, and improve — no cloud API, no telemetry.
~1 MB binary. Sub-50ms startup. Zero config required.
Website | Demo | Blog: Why a local brain? | Releases
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) ║
╚════════════════════════════════════════════════╝
brew install mercurialsolo/tap/claudectl # Homebrew (macOS / Linux)
cargo install claudectl # Cargo (any platform)Other methods
curl -fsSL https://raw.githubusercontent.com/mercurialsolo/claudectl/main/install.sh | sh
nix run github:mercurialsolo/claudectl
git clone https://github.com/linera-io/claudectl.git && cd claudectl && cargo install --path .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- Local LLM auto-pilot — a brain that learns your preferences and auto-approves/denies tool calls. No cloud API.
- 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.
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-sessionWorks with any OpenAI-compatible endpoint: ollama, llama.cpp, vLLM, LM Studio.
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 |
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 insightsDetects: 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.
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 |
/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 |
Run coordinated tasks with dependency ordering, retries, and cross-session data routing:
{
"tasks": [
{ "name": "auth", "cwd": "./backend", "prompt": "Add JWT auth middleware" },
{ "name": "tests", "cwd": "./backend", "prompt": "Update API tests. Previous: {{auth.stdout}}", "depends_on": ["auth"] },
{ "name": "docs", "cwd": "./docs", "prompt": "Document the new auth flow", "depends_on": ["auth"] }
]
}claudectl --run tasks.json --parallel
claudectl --decompose "Add auth, write tests, update docs" # Auto-split into parallel tasksContinuously checks each session and surfaces problems in the dashboard:
- Cognitive decay — composite 0-100 score tracking degradation over time
- Proactive compaction — suggests
/compactat 50% context, before the 80/90% thresholds - Cost spikes — flags when burn rate exceeds the session average
- Loop detection — catches tools failing repeatedly in retry loops
- Stall detection — sessions spending money but producing no edits
- File conflicts — detects when multiple sessions edit the same file
claudectl --budget 5 --kill-on-budget # Auto-kill at $5
claudectl --notify # Desktop notifications on blocks
claudectl --stats --since 24h # Aggregated cost statistics[[rules]]
name = "approve-cargo"
match_tool = ["Bash"]
match_command = ["cargo"]
action = "approve"
[[rules]]
name = "deny-rm-rf"
match_command = ["rm -rf"]
action = "deny"
[[rules]]
name = "kill-runaway"
match_cost_above = 20.0
action = "terminate"Rules support matching by tool, command, project, cost, and error state. Deny rules always take precedence.
More features
When you step away, claudectl can run pre-configured low-risk tasks. A morning report summarizes what happened.
Auto-restart sessions on context saturation with checkpoint + summary handoff.
Press R on any session for a highlight reel GIF (edits, commands, errors — idle time stripped). Or claudectl --record demo.gif for the full dashboard.
claudectl --new --cwd ./backend --prompt "Add auth" or press n in the dashboard.
--filter-status NeedsInput, --focus attention, --search "project", --watch for streaming.
Running claude inside a Docker-based agent sandbox (e.g. hazmat claude --docker=sandbox) leaves orphaned claude processes on the host whenever
an iTerm2 tab is closed without /exit. The in-sandbox claude survives
on a dead pty — claudectl shows the row stuck Idle forever. After a few
days of normal use these accumulate into 40+ ghost rows.
Root cause: hazmat/sbx exec doesn't propagate the host disconnect to
the in-sandbox process. The kernel pty SIGHUP doesn't fire because the
master fd stays open in the sbx daemon (see
docs/known-bugs/hazmat-orphan-disconnect.md
for the full diagnosis).
Mitigations, in order of preference:
- Type
/exitbefore closing the iTerm2 tab — clean shutdown, no orphan. - Run
claudectl --reap-orphansmanually any time — diffs the host's openSANDBOX_HOST_TTYset against in-sandbox sidecars under/var/lib/sandbox-sessions/*.terminal.json, SIGHUPs any sandboxclaudewhose host TTY is no longer attached, and sweeps dead-PID sidecars off disk. Add--dry-runto preview without acting. - Run
claudectl --install-reaperto wire a periodic background job that runs--reap-orphansevery 60 seconds. macOS uses launchd; Linux uses a systemd user timer. Tune with--reaper-interval N(range 10..=3600 seconds). Reverse withclaudectl --uninstall-reaper.
The periodic job does one more thing, and it is not sandbox-specific: it
keeps the session-restore registry honest. Sessions you close by hand are
pruned from it, so --restore-sessions after a terminal restart brings back
the sessions that died with the terminal and not ones you closed days ago.
That verdict is only observable while the terminal is still running, so
nothing at restore time can reconstruct it — if you use
--restore-sessions, install the reaper. Without it, closed sessions
accumulate in the registry and come back on the next restore.
The orphan-hunting half is a no-op on hosts without sbx in PATH, and the
registry half is host-only, so the job is safe to install unconditionally.
Sandbox layout differs across teams. Override the defaults via env vars:
| Env var | Default | Purpose |
|---|---|---|
CLAUDECTL_SANDBOX_NAME |
auto-detected, falls back to linera-agent |
sbx sandbox name to scan |
CLAUDECTL_SANDBOX_SESSIONS_DIR |
/var/lib/sandbox-sessions |
in-sandbox dir holding {pid}.terminal.json sidecars |
If CLAUDECTL_SANDBOX_NAME is unset, claudectl runs sbx ls once per
invocation and uses the single running sandbox if there is exactly one;
otherwise it falls back to linera-agent. An empty value is treated as
unset.
| Platform | Unit / plist | Error log |
|---|---|---|
| macOS | ~/Library/LaunchAgents/linera.claudectl-reaper.plist |
~/Library/Logs/claudectl-reaper.err.log |
| Linux | ~/.config/systemd/user/claudectl-reaper.{service,timer} |
~/.local/state/claudectl-reaper.err.log |
| Quick Start | Install, init, first dashboard |
| Reference | All flags, keybindings, modes |
| Configuration | Config files, hooks, rules |
| Terminal Support | Compatibility matrix |
| Troubleshooting | Common issues and FAQ |
| Contributing | Setup and guidelines |
| Changelog | Release history |
- Questions or ideas? Start a Discussion
- Found a bug? Open an issue
- Share your setup in Show & Tell
MIT