claudectl

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 .

Get started

claudectl                     # Live dashboard — see all sessions at a glance
claudectl --init              # Wire up Claude Code hooks (one-time)
claudectl --brain             # Enable local LLM auto-pilot

Why claudectl

• Local LLM auto-pilot — a brain that learns your preferences and auto-approves/denies tool calls. No cloud API.
• Hive mind — knowledge distillation, archiving, and curriculum generation. Connect instances to share learnings across machines.
• Self-improving — detects friction patterns, suggests rules, and gets smarter with every correction.
• Multi-session orchestration — run parallel tasks with dependency ordering and cross-session context routing.
• Health monitoring — catches cognitive decay, cost spikes, error loops, and context saturation before they waste money.
• Works everywhere — Claude Code plugin for inline use, TUI dashboard for oversight, CLI for automation.

Full feature comparison

Local LLM Brain

The brain observes all your sessions 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

ollama pull gemma4:e4b && ollama serve    # One-time setup
claudectl --brain                         # Advisory mode (default)
claudectl --brain --auto-run              # Auto mode: brain executes without asking
claudectl --mode auto                     # Or toggle mid-session (Ctrl+b in TUI)

Works with any OpenAI-compatible endpoint: ollama, llama.cpp, vLLM, LM Studio.

How the brain learns

The brain learns from everything you do — not just brain-involved decisions, but every manual approve, reject, rule execution, and conflict resolution. All data stays on your machine.

| Level | What it learns | Example | |-------|---------------|---------| | Conditional preferences | Context-dependent rules via decision tree splits | approve [Bash] "git push" when cost<$5 (n=8) | | Outcome tracking | Correlates decisions to detect "approved but broke" | Downweights false-positive approvals | | Temporal patterns | Behavioral sequences and time-of-day behavior | After 3+ errors: user usually denies | | Per-project models | Separate preferences per project | [Read] always approve in frontend, usually deny in infra | | Adaptive thresholds | Per-tool confidence requirements based on accuracy | 90%+ accurate on Read = auto-execute at 0.5 confidence |

Self-improving sessions

The brain automatically detects friction patterns and suggests workflow improvements:

claudectl --brain --insights on     # Enable auto-generation (every 10 decisions)
claudectl --brain --insights        # View current insights

Detects: friction patterns, error loops, context blowouts, missing rules, accuracy gaps, cost trends. Only new insights are surfaced — the system tracks what you've already seen. Use /auto-insights in the Claude Code plugin.

Claude Code Plugin

Integrates the brain directly into Claude Code sessions — no TUI required.

| Component | What it does | |-----------|-------------| | Brain gate hook | Queries the brain before every Bash/Write/Edit call | | /brain on\|off\|auto | Toggle brain mode mid-session (or Ctrl+b in TUI) | | /sessions | Show all active sessions with status, cost, health | | /spend | Cost breakdown by project and time window | | /brain-stats | Brain learning metrics and accuracy | | /auto-insights | Auto-generated workflow insights |

Headless Mode

Run the full autonomous stack without a TUI. Attach a dashboard from another terminal.

claudectl --headless --brain --auto-run           # Human-readable events
claudectl --headless --brain --auto-run --json    # Structured JSON events

What runs in headless mode:

• Brain inference (approve/deny/route/spawn with adaptive confidence)
• Coordination layer (leases, interrupts, handoffs, memory)
• Context rot prevention (auto-raises compact/stop interrupts when decay detected)
• Rule evaluation and health monitoring

The TUI dashboard can run alongside -- both share state via the coordination SQLite store, brain decision logs, and session discovery.

# Background daemon
nohup claudectl --headless --brain --auto-run > ~/.claudectl/autopilot.jsonl 2>&1 &

# Attach dashboard in another terminal
claudectl

Coordination Layer

Multi-agent coordination for parallel coding sessions. Prevents duplicate work, manages ownership, and routes context between agents.

Build with cargo build --features coord to enable.

# Ownership leases — prevent two agents from editing the same file
claudectl coord claim --session sess_1 --path src/app.rs --mode exclusive
claudectl coord release lease_123

# Handoffs — structured context transfer between sessions
claudectl coord handoff --from sess_1 --to sess_2 --task task_1 --summary 'Fix path normalization'

# Interrupts — typed cross-agent signals with delivery modes
claudectl coord raise --type pause --target sess_1 --reason 'lease conflict'
claudectl coord ack intr_123

# Memory — validated patterns promoted from brain decisions
claudectl coord promote --project myproject
claudectl coord context --session sess_1           # Preview injected context

# Inspection
claudectl coord leases                             # Active ownership leases
claudectl coord interrupts                         # Pending interrupts
claudectl coord events                             # Event audit log
claudectl coord metrics                            # Coordination health metrics
claudectl coord eval                               # Run 10 eval scenarios
claudectl coord adapters                           # Registered agent adapters

The coordination layer stores state in a local SQLite database (~/.claudectl/coord/coord.db) and injects compact context into the brain's prompt before every decision.

Hive Mind & Relay

The brain distills your decisions into shareable knowledge. Connect instances across machines to build a convergent hive mind.

# Hive knowledge is built-in — view what the brain has learned
claudectl hive status
claudectl hive knowledge
claudectl hive distill                # Condense archive into curriculum

# Add relay for cross-machine networking
cargo install claudectl --features relay
claudectl relay invite                # Generate an invite code
claudectl relay join YEK-AGA-YHK-QAA-BM       # Join from another machine
claudectl relay discover              # Scan LAN for nearby instances

# Start coordinator with HTTP API for multi-machine dashboard
claudectl relay serve --htt