Skip to content

Reference

Dashboard Features

  • Live table: PID, project, status, context %, cost, $/hr burn rate, elapsed, CPU%, memory, tokens, sparkline
  • Parent sessions expand into subagent rows (completed totals + active subagents)
  • 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)
  • Live triage filters: status cycle (f), focus cycle (v), text search (/), clear (z)
  • 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:

Status Color Meaning
Needs Input Magenta Waiting for user to approve/confirm a tool use
Processing Green Actively generating or executing tools
Waiting Yellow Done responding, waiting for user's next prompt
Unknown Blue Session is alive, but transcript telemetry is missing or unsupported
Idle Gray No recent activity (>10 min since last message)
Finished Red Process exited

Interactive Controls

Key Action
j/k or Up/Down Navigate sessions
Tab Switch to session's terminal tab
Enter Toggle detail panel
y Approve (send Enter to NeedsInput session)
i Input mode (type text to session)
d/x Kill session (double-tap to confirm)
a Toggle auto-approve (double-tap to confirm)
n Launch wizard for cwd, prompt, and resume
g Toggle grouped view by project
s Cycle sort column
f Cycle status filter
v Cycle focus filter (attention, budget, context, telemetry, conflicts)
/ Search project/model/session text
z Clear all active filters
c Send /compact to session (when idle)
R Record session highlight reel (toggle)
b Accept brain suggestion for selected session
B Reject brain suggestion
K Open Skills & Hive mode (see below)
S Send this conversation to a paired machine (relay feature)
Ctrl+r Bind an agent-bus role to the selected session
p Toggle the peers panel (relay feature)
r Force refresh
? Toggle help overlay
q/Esc Quit

Skills & Hive mode (K)

A full-screen mode for discovering Claude Code skills and managing the local hive. Two tabs, toggle with Tab.

Skills & Hive mode

Skills tab scans ~/.claude/skills, ~/.claude/plugins/*/skills, and <cwd>/.claude/skills. A ✓ marks skills already in the local hive store. Hotkeys:

Key Action
j/k Navigate the skill list
s Share selected skill with the local hive (must be ≤32 KiB)
r Re-scan disk
Tab Switch to Hive tab
Esc/K/q Return to session table

Hive tab shows your peer identity, listener status, known peers (read from ~/.claudectl/relay/peers/), and what is nearby. Opening the tab starts listening for LAN announcements on UDP 9848, and the Nearby section fills in as relays are heard: each named hive with its join policy, peer and unit counts, and the machines announcing it, then machines relaying without a hive name. Leaving the tab stops listening. When a relay, or another claudectl TUI, is already listening on this machine the tab reads the view that process publishes instead of binding beside it; when the tab is the one listening it publishes in turn, so relay discover and hive discover answer from it. The header says which source is active, and says so when the port is held by some other program.

An announcement is unauthenticated and carries no key, so the listing is informational: pairing still takes an invite minted on the other machine (i there, J here).

Hotkeys:

Key Action
h Start hive listener (spawns claudectl relay serve detached)
i Generate invite — relay code, word phrase, and invite link shown inline
J Join via a pasted relay code, invite link, or word phrase
r Refresh peer list and the nearby listing
Tab Switch to Skills tab
Esc/K/q Return to session table

Long-running relay subprocesses run detached so the TUI event loop stays responsive. Requires the relay feature to be built in.

Send a conversation to another machine (S)

S on the highlighted session lists your paired machines, numbered. A digit sends, Esc cancels:

 send> claudectl → 1) mac-mini-9f2a1b  2) laptop-a3f2  (Esc to cancel)

The target is captured when the picker opens, so a refresh tick reordering the table while you read the list cannot send the wrong session. It refuses a remote row (send it from the machine it is on), a session with no transcript, and an empty peer list — in each case saying which.

Three things are checked before anything is spawned: the transcript exists, the machine is paired, and there is an address to dial. The transfer itself is detached, because a median transcript is 5.45 MB, so the status line says sending; claudectl relay sessions reaches received with the far-side path and the resume command.

What travels is the message history, tool calls and results included. What does not: the working tree and git state, subagent transcripts, running processes, local hooks and environment, and the session id — the receiver forks. Check out the same commit over there first. See relay.md for the CLI equivalent and --remote-cwd.

CLI Reference

Dashboard

Flag Description
(no flags) Interactive TUI dashboard
-i, --interval <ms> Refresh interval in milliseconds (default: 2000)
--theme <dark\|light\|none> Color theme. Respects NO_COLOR env var
--debug Show timing metrics in the footer
--demo Run with fake sessions for screenshots and demos

Output Modes

Flag Description
-l, --list Print session table to stdout and exit
--json Print JSON array of sessions and exit
-w, --watch Stream status changes to stdout (no TUI)
--headless Run headless with brain, coordination, and context rot prevention active (no TUI). Attach a dashboard with claudectl in another terminal
--format <template> Custom format for --watch. Placeholders: {pid}, {project}, {status}, {cost}, {context}
--summary Show activity summary and exit
--since <duration> Time window for --summary, --history, --stats (e.g., "8h", "24h", "7d"). Default: 24h

Filtering

Flag Description
--filter-status <status> Filter by status: NeedsInput, Processing, Waiting, Finished, etc.
--focus <filter> High-signal subset: attention, over-budget, high-context, unknown-telemetry, conflict
--search <text> Search project/model/session text

Session Management

Flag Description
--new Launch a new Claude Code session
--cwd <path> Working directory for the new session (default: .)
--prompt <text> Prompt to send to the new session
--resume <session-id> Resume a previous session by ID

Budget & Notifications

Flag Description
--budget <usd> Per-session budget in USD. Alert at 80%, optionally kill at 100%
--kill-on-budget Auto-kill sessions that exceed budget (requires --budget)
--notify Desktop notifications on NeedsInput transitions
--webhook <url> Webhook URL to POST JSON on status changes
--webhook-on <statuses> Only fire webhook on these transitions (comma-separated, e.g. "NeedsInput,Finished")

Brain (Local LLM)

Flag Description
--brain Enable local LLM brain for session advisory
--auto-run Auto-execute brain suggestions without confirmation
--url <endpoint> LLM endpoint URL (maps to config [brain] endpoint)
--brain-model <name> Override brain model name (maps to config [brain] model)
--brain-eval Run brain eval scenarios against the LLM and report results
--brain-prompts List brain prompt templates and their source (built-in vs user override)
--brain-stats <metric> Brain statistics: impact, learning-curve, accuracy, baseline, false-approve
--brain-query Query brain for a single tool-call decision (JSON output)
--tool <name> Tool name for --brain-query (e.g., "Bash", "Write")
--tool-input <input> Command or file path for --brain-query
--project <name> Project name for --brain-query (default: current directory name)
--mode <on\|off\|auto\|status> Set brain gate mode (see Brain Gate Mode below)
--insights [on\|off\|status] Show auto-generated insights, or set insights mode. Requires --brain.

Orchestration

Flag Description
--decompose <prompt> Analyze a prompt and suggest parallel sub-tasks (outputs JSON)
--run <file> Run tasks from a JSON file
--parallel Run independent tasks in parallel (used with --run)

Recording

Flag Description
--record <path> Record the TUI as an asciicast v2 file (e.g., --record demo.cast)
--duration <secs> Auto-quit after N seconds (useful with --demo --record)

Press R on any session to record a per-session highlight reel (edits, commands, errors — idle time stripped). In --demo mode, a scripted coding session is drip-fed so recording works without live sessions.

Coordination

Inspect multi-session coordination state. Enabled by default since the supervisor RFC (#342).

Command Description
coord events [N] [type] Show last N coordination events (default 50), optionally filtered by type
coord leases Show active ownership leases, with expiry
coord claim --session S (--path P \| --resource KIND:VALUE) [--mode exclusive\|advisory] [--ttl SECS] [--wait [--timeout SECS]] Take a lease. Paths overlap by prefix; any other kind matches exactly. --wait queues FIFO instead of failing. A lease lives --ttl seconds (default 300) and is renewed automatically while its session is running
coord release LEASE Release a lease
coord claim --fleet … Claim from the lease authority ([relay] lease_authority), so no session on any machine in the fleet holds it at once. Same flags as coord claim. The lease is renewed while its session appears in that machine's heartbeat
coord release LEASE --fleet --session S Release a fleet lease. Only the session and machine holding it can
coord leases --fleet List the fleet's leases, as the authority holds them
coord renew LEASE [--ttl SECS] Extend a lease whose owner isn't a running session
coord blockers Show open blockers
coord handoffs Show handoffs
coord interrupts Show pending interrupts
coord memory List recent coordination memory records
coord memory search <q> Full-text search coordination memory
coord promote --project <name> Promote brain patterns to coordination memory
coord prune [--days N] Delete old events, resolved blockers, expired leases (default: 30 days)

Supervisor

Durable task lifecycles on top of the bus. See the README's Supervisor section for the design overview and tasks.toml shape.

Command Description
supervisor init [--force] Scaffold a documented starter tasks.toml in the cwd (won't clobber without --force)
supervisor validate <tasks.toml> Parse + validate without submitting — reports the first problem (missing field, dangling or cyclic depends_on, duplicate name)
supervisor run <tasks.toml> [--dry-run] Batch-submit one or more tasks from a TOML file (RFC §4 shape); validated before insert
supervisor submit --name --cwd --prompt [--role ...] [--git-ref REF [--branch B]] [--permission-mode M] [--requires a,b] [--peer ID] One-shot inline submission. With --git-ref, the task runs in its own worktree of cwd's repo on its own branch
supervisor work [--interval SECS] [--until-idle] [--timeout SECS] Run the queue: spawn each task's claude session (detached; output under ~/.claudectl/supervisor/runs/), watch it, run its verifiers in its workdir, remove a clean worktree after DONE. Touches no session it didn't start
supervisor status [--state STATE] Compact task table; optional state filter (PENDING / RUNNING / DONE / NEEDS_HUMAN / …)
supervisor status --graph Every task as its depends_on tree, each under the task it waits for, with the cause of any NEEDS_HUMAN
supervisor logs <task_id> Task detail + full transition log
supervisor cancel <task_id> Idempotent move to CANCELLED
supervisor pr <task_id> Post a task summary comment on its branch's PR and set a claudectl/verifier commit status from the latest verdict, via gh (#369). Best-effort — no open PR / no gh / not a repo prints a skip and exits 0
supervisor drain Set sentinel file at ~/.claudectl/coord/drain; the reconciler starts no new task on this machine (queued tasks wait, with the reason)
supervisor undrain Clear the drain marker

Set CLAUDECTL_PR_AUTO_POST=1 in the supervisor daemon's environment to run the supervisor pr flow automatically whenever a task reaches DONE (#369). Off by default; the post runs on a detached thread so it never blocks the reconciler tick.

Coord schema is gated on PRAGMA user_version. A binary that meets a newer schema (e.g. after brew upgrade without a follow-up init --upgrade) refuses to start with the exact remediation in the error.

Ingest

Command Description
ingest --hook <PreToolUse\|PostToolUse\|Stop\|SessionStart\|Notification\|UserPromptSubmit> Append the hook's stdin payload to coord hook_events. Best-effort by construction — meant to be called from a bash hook with 2>/dev/null \|\| true. JSONL tail + ps stay authoritative; this is a latency optimization for the supervisor's reconciler.

Relay

Connect machines, delegate tasks. See the full relay guide.

Command Description
relay serve [--port N] Start the relay listener for peer connections
relay invite [--qr] [--words] Generate invite code, link, and word phrase
relay join <code> Connect using any invite format (code, words, or link)
relay discover Scan LAN for nearby claudectl instances
relay peers List paired peers, live first: status (live: a heartbeat within stale_after_secs, 90 s by default; stale; never: no heartbeat on record), when each was last heard, advertised capabilities, headroom (free memory, load per core, free disk, running tasks) and tags
relay prune [--older-than 7d] [--yes] List paired peers quiet for longer than --older-than (one with no heartbeat counts from its pairing); --yes forgets them. Kept, with the reason: the peer you joined a hive through, members of your hive, and peers with a pending join request. Needs this machine's relay running (it is what records heartbeats), and refuses an --older-than shorter than stale_after_secs
relay delegate <peer> <prompt> Delegate a task to a remote peer
relay identity Show this instance's relay identity
relay install-agent Install a service so the relay survives logout (launchd on macOS, systemd --user on Linux)
relay install-agent --headless Also install the headless service: the supervisor reconciler, and the brain with --brain
relay uninstall-agent Remove both services
relay agent-status Whether the agent is installed, loaded, and running

Both ends of a connection gossip: the dialler and the listener each offer the other whatever it has not been sent, every 12 seconds, incrementally. A peer that joins long after a distillation catches up on the next tick.

Hive Mind

Share knowledge, distill learnings. Local knowledge needs nothing; sharing it across machines goes over the relay.

Command Description
hive status Knowledge store overview (units, categories, conflicts)
hive knowledge [--from X] List knowledge units, filter by peer or scope
hive trust [<peer> [<level>]] Show or set peer trust levels
hive export Export all knowledge as JSON
hive import <file> Import knowledge from JSON file
hive archive [--prune Nd] Show cold storage archive stats
hive distill Run distillation pipeline (dedup, condense, curriculum)
hive curriculum Show distilled curriculum

Naming a hive makes it something that can be advertised, found and joined as such. A hive with no name advertises nothing, which is how every install starts.

Command Description
hive identity Show this hive's name, description and join policy
hive identity set --name X [--join-policy P] Name it. P is invite (default), ask or open
hive identity clear --yes Back to unnamed
hive discover Find named hives on the LAN, with peer and unit counts
hive invite [--qr] [--words] Mint an invite to this hive (link, code, phrase)
hive join <invite> [--grant T] Join a hive. --grant joins read-only
hive requests Peers waiting to join, and who is already a member
hive requests approve <peer> Admit a waiting peer
hive requests deny <peer> Refuse one. They stay paired; the hive stays closed to them

join_policy is enforced by the host, not by the invite: ask queues each request for the owner rather than admitting on possession of a link. A hive.read:<hive-name> capability grant admits a reader — it receives the hive's knowledge and can never contribute any, and its attempted contributions are refused on the wire. A reader needs both an invite (transport) and the grant (role). See the full relay guide.

Cleanup

Flag Description
--clean Clean up old session data (JSONL transcripts, session JSON files)
--older-than <duration> Only clean sessions older than this (e.g., "7d", "24h")
--finished Only clean sessions that have finished
--dry-run Show what would be removed without deleting

History & Diagnostics

Flag Description
--autopsy Run post-mortem analysis on a completed session transcript
--session <id> Session ID or JSONL path for --autopsy (defaults to most recent session)
--history Show completed session history and exit
--stats Show aggregated session statistics and exit
--config Show resolved configuration and exit
--config-template Print annotated default config template to stdout
--hooks List configured event hooks and exit
--doctor Deprecated. Use claudectl doctor instead. Legacy report (terminal compat only) follows after the deprecation note
--log <path> Write diagnostic logs to a file

Doctor — install + runtime health check

claudectl doctor runs eight checks top-down and reports Pass / Advisory / Fail / Skipped with a one-line message and a fix hint for anything broken.

Check What it verifies
binary on PATH which claudectl matches the running binary
Claude Code hooks ~/.claude/settings.json contains claudectl entries
plugin files ~/.claude/plugins/claudectl/ is populated
brain endpoint localhost:11434 (ollama) is reachable
bus feature compiled into the binary
bus DB ~/.claudectl/bus/bus.db opens and is writable
session discovery at least one Claude session detected
terminal integration tab switching / input automation supported
claudectl doctor               # human-readable checklist
claudectl doctor --json        # machine-readable for scripting

Exit code 0 when every check is Pass / Advisory / Skipped; non-zero on any Fail. Failure messages include the exact command to run (e.g. claudectl init --plugin-only when plugin files are missing).

Setup

Two layers. The init subcommand is the canonical onboarding wizard (five phases — budget, brain, hooks, bus, skills). The legacy --init/--uninstall flags install/remove only the Claude Code hook entries and remain supported as the hook-only escape hatch.

claudectl init — onboarding wizard (preferred)

Form Description
claudectl init Interactive five-phase wizard
claudectl init --non-interactive [--budget N] [--brain-url URL] [--bus-role NAME] [--skip-*] Same flow, no prompts. For CI / dotfiles
claudectl init --check Drift report — compares the recorded marker against current state, exits non-zero on drift
claudectl init --reset Clear the onboarding marker so the next run prompts fresh. Does not touch installed artifacts
claudectl init --remove Soft uninstall. Strips Claude Code hooks + clears the marker. Preserves user data (bus DB roles, brain decision logs, hive knowledge, relay identity, config file)
claudectl init --purge [--yes] Hard uninstall. --remove PLUS wipe ~/.claudectl/ (bus DB, brain decisions, hive, relay, coord) and ~/.config/claudectl/config.toml. Confirms by default; --yes skips the prompt. Idempotent

The wizard records what ran where at ~/.claudectl/onboarding.json so --check can detect drift in later runs.

--init / --uninstall — hook-only (legacy)

Flag Description
--init Wire up Claude Code hooks in settings and exit
--uninstall Remove claudectl hooks from settings and exit
-s, --scope <user\|project> Configuration scope (default: user). Matches Claude Code's --scope convention

--init writes three hooks into Claude Code's settings:

Hook Matcher Purpose
PreToolUse Bash Lets claudectl observe commands before execution
PostToolUse * Notifies claudectl after every tool completion
Stop (all) Notifies claudectl when a session ends

The hooks call claudectl --json on each event. They are safe to run alongside any existing hooks — --init merges without overwriting.

--uninstall removes only claudectl hook entries, preserving all other settings and hooks. If the file becomes empty after removal, it is deleted.

Scope Flag File Committed to git?
user (default) --init ~/.claude/settings.json No (user home)
project --init -s project .claude/settings.local.json No (gitignored)

Cost Tracking

  • 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 in title bar
  • Unknown models marked as fallback estimates until overridden in config

Themes

Dark, light, and none (--theme). Respects NO_COLOR environment variable.

How It Works

claudectl reads Claude Code's local data — no API keys, no modifications to Claude Code, and no network traffic until you pair a relay peer or wire up a webhook:

One exception, opt-in and off by default: the read-only query surface can send a third party's question and one paragraph of CLAUDE.md to a hosted classifier. It needs TYPESAFE_API_KEY to be set, and [query] jev_enabled = false is the hard off. Nothing else in claudectl requires an API key, and no index content, file body or session data is ever sent. See Capability Grants.

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

Brain Query

Query the brain for a single tool-call decision without the TUI. Used by the Claude Code plugin hook, but also useful for scripting and testing:

claudectl --brain --brain-query --tool Bash --tool-input "rm -rf /tmp"
claudectl --brain --brain-query --tool Write --tool-input "src/main.rs" --project myapp

Output is JSON:

{"action":"deny","reasoning":"Destructive command","confidence":0.95,"source":"brain","below_threshold":false,"threshold":0.6}

The decision flow is: deny rules (instant) -> approve rules (instant) -> LLM query -> adaptive threshold check.

If the brain is unreachable, returns {"action":"abstain","source":"error"} so callers are never blocked.

Brain Gate Mode

Control whether the brain hook evaluates tool calls:

claudectl --mode on                    # Brain evaluates tool calls (default)
claudectl --mode off                   # Disable brain — all calls pass through
claudectl --mode auto                  # Brain auto-approves above threshold
claudectl --mode status                # Show current mode
Mode Approves safe calls Denies dangerous calls Low-confidence calls
on Yes Yes Fall through to user
auto Yes Yes Auto-approve
off No No Fall through to user

Mode is stored in ~/.claudectl/brain/gate-mode. File absent = on (default).

Claude Code Plugin

claudectl includes a Claude Code plugin in claude-plugin/ that integrates the brain directly into sessions.

Plugin Components

Component Type What it does
brain-gate.sh PreToolUse hook Queries the brain before Bash/Write/Edit/NotebookEdit calls
budget-check.sh PreToolUse hook Denies tool calls when session exceeds budget
/brain Command Toggle brain mode: /brain on, /brain off, /brain auto
/sessions Command Show all active sessions with status, cost, and health
/spend Command Cost breakdown by project and time window
/brain-stats Command Brain learning metrics and accuracy
/auto-insights Command Show or configure auto-generated workflow insights
Supervisor Agent Proactive session health triage
Session Monitoring Skill Auto-activated awareness of claudectl capabilities

How the brain gate hook works

  1. Claude Code fires a PreToolUse event with the tool name and input
  2. The hook checks ~/.claudectl/brain/gate-mode — if off, exits immediately
  3. Calls claudectl --brain --brain-query --tool <name> --tool-input <input>
  4. claudectl checks static deny/approve rules first (instant, no LLM)
  5. If no rule matches, queries the local LLM brain
  6. Returns {"decision":"approve"} or {"decision":"deny","reason":"..."} to Claude Code

In on mode, low-confidence brain approvals fall through to normal permission prompts. In auto mode, all brain approvals execute.

Security

claudectl reads Claude Code's session files from disk and process data from ps. It does not: - Modify Claude Code's files or behavior - Require API keys or authentication - Run with elevated privileges - Send anything anywhere you have not wired up yourself

Four things can leave the machine, all of them something you turn on: webhooks (session metadata — project, cost, status), the relay (session snapshots and delegated tasks, to peers you paired with over an HMAC-authenticated link), the hive (knowledge units, to members of a hive you named and admitted them to), and the Jev classifier on the query surface (a third party's question plus one paragraph of CLAUDE.md, never index contents or session data — it needs TYPESAFE_API_KEY, and [query] jev_enabled = false is the hard off). Pair with nobody and set no key, and nothing is sent.

The brain sends session context to a local LLM endpoint (default localhost:11434); nothing leaves the machine unless you point --url at a remote one. Review your webhook URL and event filters before enabling webhooks. See relay security for the peer transport's threat model.

Comparison

claudectl was the first tool to combine local LLM supervision with multi-session orchestration for Claude Code (shipped April 2026).

Capability Claude Code alone With claudectl
Local LLM auto-approve/deny No Brain with ollama
Self-improving insights No Friction detection, rule suggestions
Session health monitoring No 10 checks: cognitive decay, cost spikes, loops, stalls, context, cache, compaction, token efficiency, error acceleration, repetition
Orchestrate multi-session workflows No Dependency-ordered tasks
See status of all sessions at once No Live dashboard
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
Headless daemon mode No --headless with brain, coordination, and context rot prevention
Session autopsy / post-mortem No --autopsy on completed session transcripts
Idle mode / unattended work No Run tasks while you sleep
Session auto-restart No Checkpoint + restart on context saturation
Task decomposition No Splits prompts into parallel DAGs
Auto-rule engine No Match by tool/command/project/cost
Approve prompts without switching No Press y
Record session highlight reels No Press R
Claude Code plugin No /brain, /sessions, /spend, /auto-insights

| Cross-machine knowledge sharing | No | Peer-to-peer hive mind | | Remote task delegation | No | Delegate to connected peers |

Feature claudectl Static auto-approve tools Cloud-based supervisors
Local LLM brain that learns your preferences Yes No No
Cross-session orchestration + context routing Yes No Varies
10-check health monitoring + context rot detection Yes No No
File conflict detection across sessions Yes No No
Per-tool adaptive confidence thresholds Yes No No
Task decomposition into parallel DAGs Yes No No
Binary size ~3.5 MB default / ~6 MB with all features Varies N/A
Startup time <50 ms Varies N/A
Data stays on your machine 100% Usually No