claudectl

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)

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.

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.

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

claudectl 0.31.0