claudectl

Mission control for Claude Code.

Monitor multiple Claude Code sessions in one terminal dashboard. Catch blocked agents, control token burn, approve actions, and orchestrate work across tmux, iTerm2, Ghostty, Warp, and more.

_{~1 MB binary. Sub-50ms startup. Zero config required.}

Install

brew install mercurialsolo/tap/claudectl     # Homebrew (macOS)
cargo install claudectl                       # Cargo (any platform)

Quick install (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/mercurialsolo/claudectl/main/install.sh | sh

Nix

nix run github:mercurialsolo/claudectl

From source

git clone https://github.com/mercurialsolo/claudectl.git
cd claudectl && cargo install --path .

Quickstart

# Make sure you have at least one Claude Code session running, then:
claudectl

That's it. claudectl auto-discovers all running Claude Code sessions and shows a live dashboard. No configuration needed.

From the dashboard you can:

• Press y to approve a blocked permission prompt
• Press i to type input to a session
• Press Tab to jump to a session's terminal tab
• Press d to kill a runaway session
• Press ? for all keybindings

Why This Exists

Claude Code is excellent at execution. It is not built to supervise many concurrent sessions.

When you run 3, 5, or 8 sessions across terminals, real problems appear:

• Which session is blocked? One is waiting for approval and you don't know which tab.
• Which session is burning money? You can't see token spend without switching to each one.
• Which session needs input? A permission prompt has been sitting for 10 minutes.
• Which session is stalled? It looks busy but CPU is zero.

claudectl is the operator layer that answers these questions from one pane.

Claude Code vs claudectl

Core Workflows

Supervise multiple sessions

Launch claudectl and see every running session: status, cost, burn rate, CPU, context window usage, token counts, and activity sparkline — all updating live.

claudectl                   # Interactive TUI dashboard
claudectl --watch           # Stream status changes (no TUI)
claudectl --list            # Print session table and exit
claudectl --json            # Machine-readable output for scripting

Control spend

Set per-session budgets. Get warned at 80%. Optionally auto-kill at 100%.

claudectl --budget 5 --kill-on-budget

Weekly and daily cost aggregation shows in the title bar. Use --history and --stats to review past spend:

claudectl --history --since 24h
claudectl --stats --since 7d

Catch blockers instantly

Sessions needing approval show as Needs Input in magenta. Desktop notifications and webhooks alert you even when claudectl isn't focused:

claudectl --notify
claudectl --webhook https://hooks.slack.com/... --webhook-on NeedsInput,Finished

Orchestrate multi-session work

Run coordinated tasks with dependency ordering:

{
  "tasks": [
    {
      "name": "Add auth middleware",
      "cwd": "./backend",
      "prompt": "Add JWT auth middleware to all API routes"
    },
    {
      "name": "Update tests",
      "cwd": "./backend",
      "prompt": "Update API tests for the new auth middleware",
      "depends_on": ["Add auth middleware"]
    },
    {
      "name": "Update docs",
      "cwd": "./docs",
      "prompt": "Document the new auth flow"
    }
  ]
}

claudectl --run tasks.json --parallel

Record and share

Highlight reels — Press R on any session to record a supercut: file edits, bash commands, errors, and successes. Idle time and noise are stripped. Output is a shareable GIF.

Dashboard recording — Capture the full TUI:

claudectl --record session.gif      # Direct GIF (requires agg)
claudectl --record session.cast     # Raw asciicast v2

Demo mode — Deterministic fake sessions for screenshots and content:

claudectl --demo                    # Animated TUI with 8 fake sessions
claudectl --demo --record demo.gif  # One-command GIF for your README

Features

Dashboard

• Live table: PID, project, status, context %, cost, $/hr burn rate, elapsed, CPU%, memory, tokens, sparkline
• Detail panel (Enter) with full session metadata
• Grouped view (g) by project with aggregate stats
• Sort by status, context, cost, burn rate, or elapsed (s)
• Conflict detection when 2+ sessions share the same git worktree (!!)
• Permission wait time — shows how long sessions have been waiting, longest first

Status Detection

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

Cost Tracking & Budgets

• Per-session USD estimates (Opus, Sonnet, Haiku model pricing)
• Live $/hr burn rate
• Per-session budget alerts at 80%, auto-kill at 100%
• Daily/weekly aggregate cost tracking
• Session history with cost analytics

Interactive Controls

Terminal Support

Notes: Ghostty has the best support — no config needed. Kitty requires allow_remote_control yes in config. Warp requires Accessibility permission. tmux is auto-detected.

Themes

• Dark, light, and monochrome (--theme)
• Respects NO_COLOR environment variable

Event Hooks

Run shell commands automatically when session events occur. Add to your config file:

# ~/.config/claudectl/config.toml

[hooks.on_needs_input]
run = "say 'Claude needs your attention'"

[hooks.on_finished]
run = "terminal-notifier -title 'claudectl' -message '{project} finished (${cost})'"

[hooks.on_budget_warning]
run = "curl -X POST $SLACK_WEBHOOK -d '{\"text\": \"{project} hit 80% budget (${cost})\"}'"

[hooks.on_status_change]
run = "echo '[{project}] {old_status} -> {new_status}' >> ~/claude-activity.log"

Events

Template Variables

{pid}, {project}, {status}, {cost}, {model}, {cwd}, {tokens_in}, {tokens_out}, {elapsed}, {session_id}, {old_status}, {new_status}, {context_pct}

Use claudectl --hooks to verify your configured hooks.

Verified Hooks

We maintain a curated set of verified hooks at mercurialsolo/claudectl-hooks. Submitted hooks are reviewed for security, reliability, and usefulness before being added.

To submit a hook, open an issue with the config snippet, what it solves, and any dependencies.

Configuration

claudectl loads settings from ~/.config/claudectl/config.toml (global) and .claudectl.toml (per-project). CLI flags override both.

[defaults]
interval = 1000
notify = true
grouped = true
sort = "cost"
budget = 5.00
kill_on_budget = false

[webhook]
url = "https://hooks.slack.com/..."
events = ["NeedsInput", "Finished"]

[context]
warn_threshold = 75

Show resolved config: claudectl --config

Maintenance

claudectl --clean --older-than 7d --dry-run   # Preview cleanup
claudectl --clean --finished                    # Remove finished session data

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 (PID, session ID, working directory, start time)
• ~/.claude/projects/{slug}/*.jsonl — conversation logs with token usage and events
• ps — CPU%, memory, TTY for each process
• /tmp/claude-{uid}/{slug}/{sessionId}/tasks/ — subagent task files

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

Troubleshooting

No sessions found

• Ensure Claude Code is running (claude in another terminal)
• Check that ~/.claude/sessions/ contains .json files
• Run claudectl --log /tmp/claudectl.log and check the log

Tab switching doesn't work

• Ghostty: should work out of the box
• Kitty: add allow_remote_control yes to ~/.config/kitty/kitty.conf
• Warp: grant Accessibility permission in System Settings > Privacy & Security
• tmux: must be running inside a tmux session

Cost shows $0.00

• claudectl reads token usage from JSONL logs. If the session just started, wait for the first response to complete
• Check that ~/.claude/projects/ contains .jsonl files

High CPU usage from claudectl itself

• Increase the poll interval: claudectl --interval 3000 (default is 1000ms)

For other issues, run with --log and open an issue with the log attached.

FAQ

Does claudectl modify Claude Code or its files?
No. It is read-only. The only writes are to its own history file and log file.

Does it need an API key?
No. It reads local files on disk. No network access required (unless you configure webhooks).

Does it work with Claude Code in VS Code / JetBrains?
It monitors any Claude Code process, regardless of how it was launched. Terminal-specific features (tab switching, input) require a supported terminal.

Can I use it with a single session?
Yes, but the value increases with concurrency. If you run one session, you already know where it is.

What about Windows?
Not yet. macOS and Linux only. WSL support is planned.

Security

claudectl runs entirely locally. It reads Claude Code's session files from disk and process data from ps. 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

Webhook payloads contain session metadata (project name, cost, status). Review your webhook URL and event filters before enabling.

Contributing

Contributions are welcome.

Setup

git clone https://github.com/mercurialsolo/claudectl.git
cd claudectl
cargo build
cargo test --all-targets

Before submitting

cargo test --all-targets
cargo clippy --all-targets -- -D warnings
cargo fmt --all -- --check

Guidelines

• No new dependencies without strong justification — the project stays lightweight
• Test behavior, not implementation — focus on what the code does
• Match existing patterns — look at similar code before writing new code
• Keep commits atomic — one logical change per commit

Not all contributions are code. Hooks, docs, config presets, terminal compatibility fixes, and packaging help are all valuable.

Architecture

Community

Questions, ideas, or workflows to share? Start a Discussion.

Found a bug? Open an issue with claudectl --version, your terminal (echo $TERM_PROGRAM), and steps to reproduce.

License

MIT