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 --new --cwd ./myproject         # Launch a new session
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 --url http://localhost:8080/v1/chat/completions

# vLLM
claudectl --brain --url 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. Run claudectl --brain-eval to test decision quality against built-in scenarios. Run claudectl --brain-prompts to see which prompt templates are active and whether they're built-in or user overrides.

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

Override prompt templates by placing files in ~/.claudectl/brain/prompts/.

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

Session Health Monitoring

claudectl continuously checks each session for problems and surfaces them with severity-ranked icons in the dashboard:

• Cache health — detects low cache hit ratios that can silently multiply costs
• 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 file edits
• Context saturation — warns when a session approaches its context window limit

Health issues appear as icons in the session table and as a summary in the status bar. No configuration needed.

File Conflict Detection

When multiple sessions edit the same file, claudectl detects the conflict and flags it:

• !F prefix in the session table for sessions with file-level conflicts
• File Conflicts section in the detail panel showing which files conflict and with which sessions
• Predictive detection — flags pending Edit/Write calls targeting files another session has already modified
• Auto-deny — optionally deny writes to conflicting files with an actionable message

# .claudectl.toml
[orchestrate]
file_conflicts = true              # Detect file-level conflicts (default: on)
auto_deny_file_conflicts = true    # Auto-deny conflicting writes (default: off)

File conflicts can also be matched in auto-rules:

[rules.deny_conflicts]
match_file_conflict = true
action = "deny"
message = "Another session is editing this file"

Launch and Resume Sessions

Start new Claude Code sessions without leaving the dashboard:

claudectl --new --cwd ./backend                       # Launch in a directory
claudectl --new --cwd ./api --prompt "Add rate limiting"  # Launch with a prompt
claudectl --new --resume abc123                       # Resume a previous session

From the dashboard, press n to open the launch wizard (directory, prompt, resume fields).

Auto-Rules

Define rules in .claudectl.toml to automatically approve, deny, terminate, or route sessions based on conditions:

[[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 status, tool name, command substring, project name, cost threshold, and error state. Deny rules always take precedence. Rules can also route output between sessions, spawn new sessions, or delegate to agents.

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
claudectl --stats --since 24h             # Aggregated session statistics
claudectl --summary --since 8h            # Activity summary

From the dashboard: y approve, i input, Tab switch terminal, d kill, n new session, R record, ? all keys.

Filter and Search

claudectl --filter-status NeedsInput       # Only show sessions needing input
claudectl --focus attention                # High-signal triage view
claudectl --focus over-budget              # Sessions exceeding budget
claudectl --search "my-project"            # Filter by project name
claudectl --watch                          # Stream status changes (no TUI)
claudectl --watch --json                   # Stream as JSON

In the dashboard: f cycle status filters, v cycle focus filters, / search, z clear all filters, g group by project, s cycle sort order.

Clean Up

claudectl --clean                          # Remove old session data
claudectl --clean --older-than 7d          # Only sessions older than 7 days
claudectl --clean --finished --dry-run     # Preview what would be removed

Docs

Community

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

License

MIT