# 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) |
| `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](assets/claudectl-demo-skills.gif){ .terminal-screenshot }


**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, and known peers (read from `~/.claudectl/relay/peers/`). 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 |
| `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.

## 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 (--features coord)

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 |
| `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](../README.md#supervisor) for the design overview and `tasks.toml` shape.

| Command | Description |
|---------|-------------|
| `supervisor run <tasks.toml> [--dry-run]` | Batch-submit one or more tasks from a TOML file (RFC §4 shape) |
| `supervisor submit --name --cwd --prompt [--role ...]` | One-shot inline submission |
| `supervisor status [--state STATE]` | Compact task table; optional state filter (`PENDING` / `RUNNING` / `DONE` / `NEEDS_HUMAN` / …) |
| `supervisor logs <task_id>` | Task detail + full transition log |
| `supervisor cancel <task_id>` | Idempotent move to CANCELLED |
| `supervisor drain` | Set sentinel file at `~/.claudectl/coord/drain`; reconciler stops issuing new assignments |
| `supervisor undrain` | Clear the drain marker |

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 (--features relay)

Connect machines, delegate tasks. See the [full relay guide](relay.md).

| 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 known and connected peers |
| `relay delegate <peer> <prompt>` | Delegate a task to a remote peer |
| `relay identity` | Show this instance's relay identity |

### Hive Mind (--features hive)

Share knowledge, distill learnings. Requires relay for transport.

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

### 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 |

```bash
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 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.

### 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:

```bash
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:

```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:

```bash
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 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 or the brain feature)
- 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.

The brain feature sends session context to a **local** LLM endpoint (default `localhost:11434`). No data leaves your machine unless you point `--url` at a remote server.

## 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 |
