claudectl

Auto-pilot for Claude Code.

Fully local on-device model that learns and decide what to approve - no cloud API, no telemetry. +orchestration, health monitoring, spend control, and highlight-reels.

~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
claudectl --decompose "Add auth and update tests and docs"  # Split into parallel tasks

Why claudectl

Capability	Claude Code alone	With claudectl
Local LLM auto-approve/deny	No	Brain with ollama
Session health monitoring	No	Cache, cost spikes, loops, stalls, context
Record session highlight reels	No	Press R
Orchestrate multi-session workflows	No	Dependency-ordered tasks
Launch/resume sessions	Separate terminal	Press n or --new
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
File conflict detection	No	Auto-detect + brain pre-check + auto-deny
Idle mode / unattended work	No	Run tasks while you sleep
Session auto-restart	No	Checkpoint + restart on context saturation
Task decomposition	No	--decompose splits prompts into parallel DAGs
Auto-rule engine	No	Match by tool/command/project/cost
Approve prompts without switching	No	Press y
Get notified on stalls/blocks	No	Desktop + webhook

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 continuously learns from everything you do — not just brain-involved decisions, but every manual approve, reject, input, rule execution, and conflict resolution. These signals are distilled into compact conditional preferences and injected into the LLM prompt, so the brain's judgment compounds 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:

Backend	Setup	Default endpoint
ollama	ollama pull gemma4:e4b && ollama serve	localhost:11434
llama.cpp	llama-server -m model.gguf	localhost:8080
vLLM	vllm serve gemma4	localhost:8000
LM Studio	Start server in UI	localhost:1234

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

How the brain learns:

The brain captures rich context at every decision point and distills it into compact rules that fit Gemma4's context window (~250 tokens). Four levels of learning work together:

Level	What it does	Example
Context capture	Records 13 session state fields (cost, context%, errors, burn rate, files, conflicts) with every decision	cost_usd: 14.50, context_pct: 82, recent_error_count: 3
Conditional preferences	Learns context-dependent rules via decision tree splits	approve [Bash] "git push" when cost<$5 (n=8)
Outcome tracking	Correlates consecutive decisions to detect "approved but broke"	Downweights false-positive approvals, reinforces correct rejections
Temporal patterns	Detects behavioral sequences across decisions	After 3+ errors: user usually denies (n=12)
Time-of-day	Learns work-hours vs off-hours approval behavior	More permissive during work hours (accept 90% vs 40%)
Per-project models	Distills separate preferences per project	[Read] always approve in frontend, usually deny in infra

The brain learns passively from all user actions, not just brain-involved decisions:

Your action	What the brain learns
Press y (approve)	"This tool+command at this cost/context level is safe"
Press B (reject brain)	"Brain was wrong here — correction signal" (weighted 8x)
Press i (send input)	"Session needed human guidance at this point"
Static rule fires	"This pattern should be internalized"
File conflict deny	"Concurrent edits to this file = deny"

Adaptive confidence thresholds track accuracy per tool — if the brain is 90%+ accurate on Read, it auto-executes with low confidence (0.5). If it's <50% accurate on Bash, it requires 0.95 confidence or defers to you.

What the brain sees per session:

• Project name, status, model, pending tool call + command
• Cost, burn rate, context window utilization
• Git state — branch, uncommitted changes, diff stats, recent commits (cached, 30s TTL)
• Recent transcript (last 8 messages, earlier ones compacted)
• All other active sessions (for cross-session reasoning)
• Per-project preferences — distilled from project-specific decision history (falls back to global with <10 decisions)
• Situational rules (error streaks, cost pressure, context pressure, time-of-day patterns)
• Outcome-weighted few-shot examples (corrections weighted highest)

Measure brain effectiveness:

claudectl --brain-stats learning-curve   # Is correction rate declining? (= learning)
claudectl --brain-stats accuracy         # Per-tool, per-risk, per-project breakdown
claudectl --brain-stats baseline         # Brain vs. dumb rules classifier
claudectl --brain-stats false-approve    # Safety: how often does brain approve risky actions?

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/.

File conflict pre-check — before auto-approving Write/Edit calls, the brain checks if another session has the target file in its edit history. Conflicts are demoted to advisory mode, requiring your confirmation.

Idle Mode

When you step away, claudectl detects inactivity and can run pre-configured low-risk tasks:

# .claudectl.toml
[idle]
enabled = true
after_idle_mins = 15         # Transition to idle after 15 minutes
max_concurrent = 2           # Max parallel idle tasks
max_cost_usd = 5.0           # Budget cap for idle work

The status bar shows idle state and elapsed time. On your first keypress back, a morning report summarizes what happened while you were away.

Session Lifecycle

Long-running sessions degrade as their context window fills. claudectl can auto-restart them:

# .claudectl.toml
[lifecycle]
auto_restart = true          # Enable auto-restart on context saturation
restart_threshold_pct = 90.0 # Restart when context exceeds 90%
restart_only_when_idle = true # Only restart during idle mode

When triggered, the brain summarizes the session state, saves a checkpoint to ~/.claudectl/brain/checkpoints/, and spawns a fresh session with the summary as context.

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

Auto-decompose prompts — let the brain split large prompts into parallel sub-tasks:

# Analyze a prompt and output a task DAG (pipe to --run)
claudectl --decompose "Add JWT auth, write tests for all endpoints, and update the API docs"

# Decompose and run in one pipeline
claudectl --decompose "..." > tasks.json && claudectl --run tasks.json --parallel

The decomposition prompt template is user-overridable via ~/.claudectl/brain/prompts/decomposition.md.

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

Reference	Dashboard features, keybindings, CLI modes, status detection
Configuration	Config files, hooks, rules, model pricing overrides
Terminal Support	Compatibility matrix and setup notes
Troubleshooting	Common issues and FAQ
Contributing	Setup, guidelines, and architecture
Changelog	Release history

Community

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

License

MIT