claudectl

Mission control for Claude Code.

A local LLM watches your Claude Code sessions and decides what to approve. You press one key to record a highlight reel GIF. You orchestrate 5 sessions with dependencies. And you never tab-hunt again.

~1 MB binary. Sub-50ms startup. Zero config required.

Website | Demo | Releases

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 .

Try it now

claudectl --demo                          # Fake sessions, no Claude needed
claudectl                                 # Live dashboard
claudectl --brain                         # Local LLM auto-pilot
claudectl --run tasks.json --parallel     # Orchestrate multiple sessions

Why claudectl

Local LLM Brain

A local LLM observes your sessions and suggests what to approve, deny, or terminate. It learns from your corrections. Works with any local inference server — no cloud API needed.

Supported backends:

Any endpoint that accepts a JSON POST and returns generated text will work.

# ollama (default — zero config)
claudectl --brain

# llama.cpp
claudectl --brain --brain-endpoint http://localhost:8080/v1/chat/completions

# vLLM
claudectl --brain --brain-endpoint http://localhost:8000/v1/chat/completions --brain-model gemma4

# Advisory mode: brain suggests, you press b to accept or B to reject
claudectl --brain

# Auto mode: brain executes without asking
claudectl --brain --auto-run

Every decision is logged locally. Past decisions are retrieved as few-shot examples so the brain adapts to your preferences over time. Deny rules always override brain suggestions. All data stays on your machine.

Run claudectl --doctor to check if your backend is reachable.

# .claudectl.toml
[brain]
enabled = true
endpoint = "http://localhost:11434/api/generate"  # change for other backends
model = "gemma4:e4b"
auto = false
few_shot_count = 5

Record and Share

Highlight reels — Press R on any session. claudectl extracts file edits, bash commands, errors, and successes. Idle time and noise are stripped. Output is a shareable GIF.

Dashboard recording — Capture the full TUI as a GIF or asciicast:

claudectl --record session.gif             # GIF (requires agg)
claudectl --demo --record demo.gif         # One-command demo GIF for your README

Orchestrate Sessions

Run coordinated tasks with dependency ordering, retries, cross-session data routing, and resumable sessions:

{
  "tasks": [
    { "name": "auth", "cwd": "./backend", "prompt": "Add JWT auth middleware" },
    { "name": "tests", "cwd": "./backend", "prompt": "Update API tests for auth. Previous output: {{auth.stdout}}", "depends_on": ["auth"] },
    { "name": "docs", "cwd": "./docs", "prompt": "Document the new auth flow", "depends_on": ["auth"] }
  ]
}

claudectl --run tasks.json --parallel

Supervise and Control Spend

claudectl --budget 5 --kill-on-budget      # Auto-kill at $5
claudectl --notify                         # Desktop notifications on blocks/stalls
claudectl --webhook https://hooks.slack.com/... --webhook-on NeedsInput,Finished
claudectl --history --since 24h            # Review past session costs

From the dashboard: y approve, i input, Tab switch terminal, d kill, ? all keys.

Docs

Community

Questions or ideas? Start a Discussion. Found a bug? Open an issue.

License

MIT