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

The brain is claudectl's core intelligence layer. A local LLM continuously observes all your sessions — what they're doing, what tools they're calling, how much they're spending — 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
• Delegate tasks to external agents (Codex, Aider, custom tools)

The brain learns from your corrections. Every accept/reject is logged as a few-shot example, so its suggestions improve over time. All data stays on your machine — no cloud API, no telemetry.

# Start with one command (requires ollama)
ollama pull gemma4:e4b && ollama serve
claudectl --brain

# Advisory mode (default): brain suggests, you press b/B to accept/reject
claudectl --brain

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

Supported backends:

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

What the brain sees per session:

• Project name, status, model, pending tool call + command
• Cost, burn rate, context window utilization
• Recent transcript (last 8 messages, earlier ones compacted)
• All other active sessions (for cross-session reasoning)
• Past decisions on similar tool calls (few-shot examples)

Diagnostics and customization:

claudectl --doctor          # Check if backend is reachable
claudectl --brain-eval      # Test decision quality against built-in scenarios
claudectl --brain-prompts   # List prompt templates and their source

# .claudectl.toml
[brain]
enabled = true
endpoint = "http://localhost:11434/api/generate"
model = "gemma4:e4b"
auto = false                # true = auto-execute suggestions
few_shot_count = 5          # Past decisions to include as examples
max_sessions = 10           # Max sessions brain can spawn
orchestrate = false         # Enable cross-session orchestration
orchestrate_interval = 30   # Seconds between orchestration passes

Override any prompt template 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