# 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.
[](https://github.com/mercurialsolo/claudectl/actions/workflows/ci.yml)
[](https://crates.io/crates/claudectl)
[](https://github.com/mercurialsolo/homebrew-tap)
[](LICENSE)
[]()
<sub>~1 MB binary. Sub-50ms startup. Zero config required.</sub>
<a href="https://asciinema.org/a/bovJrUq2vEmC08NU?autoplay=1"><img src="https://asciinema.org/a/bovJrUq2vEmC08NU.svg" alt="claudectl demo" width="100%" /></a>
## Install
```bash
brew install mercurialsolo/tap/claudectl # Homebrew (macOS / Linux)
cargo install claudectl # Cargo (any platform)
```
<details>
<summary>Other methods</summary>
```bash
git clone https://github.com/mercurialsolo/claudectl.git && cd claudectl && cargo install --path .
```
</details>
## Try it now
```bash
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 auto-approve/deny | No | **Brain with ollama** |
| Record session highlight reels | No | **Press `R`** |
| Orchestrate multi-session workflows | No | **Dependency-ordered tasks** |
| See status of all sessions at once | No | **Yes** |
| Know which session is blocked | Tab-hunt | **At a glance** |
| Track cost per session | Manually | **Live $/hr burn rate** |
| Enforce spend budgets | No | **Auto-kill at limit** |
| Approve prompts without switching | No | **Press `y`** |
| Get notified on stalls/blocks | No | **Desktop + webhook** |
## 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:**
| [ollama](https://ollama.com) | `ollama pull gemma4:e4b && ollama serve` | `localhost:11434` |
| [llama.cpp](https://github.com/ggerganov/llama.cpp) | `llama-server -m model.gguf` | `localhost:8080` |
| [vLLM](https://github.com/vllm-project/vllm) | `vllm serve gemma4` | `localhost:8000` |
| [LM Studio](https://lmstudio.ai) | Start server in UI | `localhost:1234` |
Any endpoint that accepts a JSON POST and returns generated text will work.
```bash
# 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.
```toml
# .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:
```bash
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:
```json
{
"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"] }
]
}
```
```bash
claudectl --run tasks.json --parallel
```
## Supervise and Control Spend
```bash
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
| [Reference](docs/reference.md) | Dashboard features, keybindings, CLI modes, status detection |
| [Configuration](docs/configuration.md) | Config files, hooks, rules, model pricing overrides |
| [Terminal Support](docs/terminal-support.md) | Compatibility matrix and setup notes |
| [Troubleshooting](docs/troubleshooting.md) | Common issues and FAQ |
| [Contributing](docs/contributing.md) | Setup, guidelines, and architecture |
| [Changelog](CHANGELOG.md) | Release history |
## Community
Questions or ideas? [Start a Discussion](https://github.com/mercurialsolo/claudectl/discussions). Found a bug? [Open an issue](https://github.com/mercurialsolo/claudectl/issues/new).
## License
MIT