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

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)

Other methods

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.
• 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.

Full feature comparison

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

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
/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

Orchestrate Sessions

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 tasks

Session Health Monitoring

Continuously checks each session and surfaces problems in the dashboard:

• Cognitive decay — composite 0-100 score tracking degradation over time
• Proactive compaction — suggests /compact at 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

Spend Control

claudectl --budget 5 --kill-on-budget     # Auto-kill at $5
claudectl --notify                        # Desktop notifications on blocks
claudectl --stats --since 24h            # Aggregated cost statistics

Auto-Rules

[[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

Idle Mode

When you step away, claudectl can run pre-configured low-risk tasks. A morning report summarizes what happened.

Session Lifecycle

Auto-restart sessions on context saturation with checkpoint + summary handoff.

Record and Share

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.

Launch and Resume

claudectl --new --cwd ./backend --prompt "Add auth" or press n in the dashboard.

Filter and Search

--filter-status NeedsInput, --focus attention, --search "project", --watch for streaming.

Sandboxed claude orphan cleanup

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:

1. Type /exit before closing the iTerm2 tab — clean shutdown, no orphan.
2. Run claudectl --reap-orphans manually any time — diffs the host's open SANDBOX_HOST_TTY set against in-sandbox sidecars under /var/lib/sandbox-sessions/*.terminal.json, SIGHUPs any sandbox claude whose host TTY is no longer attached, and sweeps dead-PID sidecars off disk. Add --dry-run to preview without acting.
3. Run claudectl --install-reaper to wire a periodic background job that runs --reap-orphans every 60 seconds. macOS uses launchd; Linux uses a systemd user timer. Tune with --reaper-interval N (range 10..=3600 seconds). Reverse with claudectl --uninstall-reaper.

The reaper is a no-op on hosts without sbx in PATH, so it's 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.

Where things live

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

Docs

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

Community

• Questions or ideas? Start a Discussion
• Found a bug? Open an issue
• Share your setup in Show & Tell

License

MIT