Skip to content

claudectl

Mission control for Claude Code - supervise, budget, orchestrate, and auto-pilot sessions with a local LLM brain.

Know which agent is blocked, burning budget, waiting for approval, or stalled - and intervene without tab hunting.

~1 MB binary Sub-50ms startup Zero config macOS & Linux

claudectl dashboard demo

Install

brew install mercurialsolo/tap/claudectl

cargo install claudectl

Then wire up Claude Code hooks and start the dashboard:

claudectl --init    # one-time setup
claudectl           # launch dashboard

Or try it without Claude Code running:

claudectl --demo

See the Quick Start for the full walkthrough.

Features

Live Dashboard

See every session's status, burn rate, context usage, activity sparkline, CPU, memory, and subagent rows in one place.

Intervene Fast

Approve prompts, send input, jump to the right terminal tab, or kill a runaway session - without leaving the dashboard.

Budget Enforcement

Set per-session or daily spending limits. Alert at 80%, auto-kill at 100%. Track live $/hr burn rate.

Local LLM Brain

A local model (ollama/gemma) watches sessions, auto-approves safe commands, denies dangerous ones. Learns from your corrections. All on-device.

Auto-Rules Engine

TOML rules to approve, deny, send, terminate, route, or spawn based on tool name, command pattern, project, or cost threshold.

Health Monitoring

Detects stalled sessions, context saturation, cache issues, cost spikes, retry loops, and cognitive decay - no config needed.

Multi-Session Orchestration

Run dependency-ordered task graphs across sessions. Decompose prompts into parallel DAGs.

Event Hooks

Trigger desktop notifications, shell commands, and webhooks when sessions need attention.

Session Recording

Press R to record a session highlight reel as a GIF. Extracts edits, commands, errors - strips idle time.

Screenshots

Dashboard health monitoring:

claudectl health monitoring

Status Detection

Multi-signal inference from CPU usage, JSONL events, and timestamps:

Status Meaning
Needs Input Waiting for user to approve/confirm a tool use
Processing Actively generating or executing tools
Waiting Done responding, waiting for user's next prompt
Idle No recent activity (>10 min)
Finished Process exited

Terminal Support

Terminal Launch Switch Input Approve
Ghostty - Yes Yes Yes
tmux Yes Yes Yes Yes
Kitty Yes Yes Yes Yes
Warp - Yes Yes Yes
iTerm2 - Yes Yes Yes
Terminal.app - Yes Yes Yes
WezTerm Yes Yes - -
GNOME Terminal Yes - - -

Run claudectl --doctor to verify support in your terminal. See Terminal Support for setup notes.

How It Works

claudectl reads Claude Code's local data - no API keys, no network access, no modifications to Claude Code:

  • ~/.claude/sessions/*.json - session metadata
  • ~/.claude/projects/{slug}/*.jsonl - conversation logs with token usage
  • ps - CPU%, memory, TTY for each process

Status inference combines multiple signals: waiting_for_task events, CPU usage thresholds, stop_reason fields, and message recency.

Security

claudectl runs entirely locally. It does not:

  • Send data to any server (unless you configure webhooks)
  • Modify Claude Code's files or behavior
  • Require API keys or authentication
  • Run with elevated privileges

Built With

License

MIT