claudectl

~6 MB binary (full features, Homebrew bottle). Sub-50ms startup. Zero config required.

Website | Demo | Blog: Why a local brain? | Releases

What it does for you

Run claudectl --brain-stats impact to see your numbers:

  ╔════════════════════════════════════════════════╗
  ║              IMPACT SCORECARD                  ║
  ║             1200 decisions tracked             ║
  ╠════════════════════════════════════════════════╣
  ║  Auto-handled                             71%  ║
  ║  ████████████████████░░░░░░░░  847/1200        ║
  ║                                                ║
  ║  Brain accuracy                          96.2%  ║
  ║  ███████████████████████████░  1154/1200       ║
  ║                                                ║
  ║  Coverage vs static rules               2.9x  ║
  ║  brain ████████████████████████████  100%      ║
  ║  rules █████████░░░░░░░░░░░░░░░░░░░  34%      ║
  ║                                                ║
  ║  Dangerous ops blocked      12  Time saved 42m  ║
  ║  2 critical | 10 high-risk | 847 auto x 3s    ║
  ║                                                ║
  ║  Learning: correction rate 8.4% ↓ 2.1% (-6pp) ║
  ╚════════════════════════════════════════════════╝

Install

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

Both produce the same ~6 MB binary with bus/coord/relay/hive enabled — claudectl bus, coord, relay, and hive work out of the box. For the minimal ~3.5 MB sync-only build, opt out with cargo install claudectl --no-default-features --features hive.

Building from source (Cargo) requires rustc 1.88+. Older toolchains fail with an opaque transitive-dependency error before the build starts — run rustup update stable first. The Homebrew bottle ships prebuilt and has no toolchain requirement.

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 demo                # Guided first-value tour — no live sessions needed
claudectl init                # Onboarding wizard (budget, brain, hooks, bus, skills)
claudectl doctor              # Verify install + runtime health (✓ checklist)
claudectl                     # Live dashboard — see all sessions at a glance
claudectl --brain             # Enable local LLM auto-pilot

After brew upgrade claudectl, run claudectl init --upgrade to re-sync hook entries, plugin files, and DB migrations to the new binary. claudectl doctor's plugin version row will tell you when this is needed.

The init wizard walks five phases — weekly budget, local-LLM brain detection, Claude Code hook install, agent-bus role, and curated skill suggestions. Plugin files (slash commands, supervisor agent, bus MCP server registration) are embedded in the binary and written to ~/.claude/plugins/claudectl/ automatically — no repo clone. Run claudectl doctor to verify every piece is wired up, or claudectl init --check for the drift report against the onboarding marker.

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.

Explain & audit every decision

To leave the brain unattended you need to trust and audit it. Every decision now carries a "why" — the source (rule, few-shot, or LLM), the confidence, and the past examples that informed it — surfaced inline in --brain-query output and the Brain Review panel.

claudectl --brain-review           # Triage decisions; press [c] to correct-and-learn in one keystroke
claudectl --brain-export           # Export the decision timeline as Markdown (paste into a PR)
claudectl --brain-export json --project acme   # …or JSON, filtered to one project (or --pid <n>)

A one-key correct-and-learn in the review view records the right answer as canonical training material, so the next similar decision improves.

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.

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.

Enabled by default. For the minimal sync-only build, use cargo build --no-default-features --features hive.

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

Agent Bus (preview)

A durable directory + mailbox that exposes the running swarm as an MCP server. Agents discover each other (list_agents), look up their own role (whoami), publish directed messages, and drain their inbox at turn boundaries. Phases 1–4 of the design spec are shipped.