{"id":48220151,"url":"https://github.com/mercurialsolo/claudectl","last_synced_at":"2026-04-25T07:02:59.289Z","repository":{"id":349189556,"uuid":"1200807788","full_name":"mercurialsolo/claudectl","owner":"mercurialsolo","description":"Auto-pilot your Claude Code. Add a local LLM brain that learns from your actions and auto-approves/denies","archived":false,"fork":false,"pushed_at":"2026-04-20T15:57:40.000Z","size":2340,"stargazers_count":55,"open_issues_count":24,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-20T16:08:52.691Z","etag":null,"topics":["agent-orchestration","auto-approve","claude","claude-code","cli","llm","local-llm","ollama","ratatui","rust","session-monitor","terminal","tui"],"latest_commit_sha":null,"homepage":"https://mercurialsolo.github.io/claudectl/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mercurialsolo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-03T21:12:01.000Z","updated_at":"2026-04-20T14:30:35.000Z","dependencies_parsed_at":"2026-04-13T10:00:53.835Z","dependency_job_id":null,"html_url":"https://github.com/mercurialsolo/claudectl","commit_stats":null,"previous_names":["mercurialsolo/claudectl"],"tags_count":60,"template":false,"template_full_name":null,"purl":"pkg:github/mercurialsolo/claudectl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mercurialsolo%2Fclaudectl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mercurialsolo%2Fclaudectl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mercurialsolo%2Fclaudectl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mercurialsolo%2Fclaudectl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mercurialsolo","download_url":"https://codeload.github.com/mercurialsolo/claudectl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mercurialsolo%2Fclaudectl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32253252,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T04:23:17.126Z","status":"ssl_error","status_checked_at":"2026-04-25T04:21:53.360Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-orchestration","auto-approve","claude","claude-code","cli","llm","local-llm","ollama","ratatui","rust","session-monitor","terminal","tui"],"created_at":"2026-04-04T19:08:51.116Z","updated_at":"2026-04-25T07:02:59.278Z","avatar_url":"https://github.com/mercurialsolo.png","language":"Rust","funding_links":[],"categories":["Development tools","Rust","💻 Apps"],"sub_categories":["Workflow Automation","⌨️ Development Tools"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"claudectl\" width=\"372\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\u003cstrong\u003eMission control for Claude Code.\u003c/strong\u003e\u003c/p\u003e\n\u003cp align=\"center\"\u003eSupervise, orchestrate, and connect coding agents with a local LLM brain and hive mind.\u003c/p\u003e\n\n[![CI](https://github.com/mercurialsolo/claudectl/actions/workflows/ci.yml/badge.svg)](https://github.com/mercurialsolo/claudectl/actions/workflows/ci.yml)\n[![Crates.io](https://img.shields.io/crates/v/claudectl)](https://crates.io/crates/claudectl)\n[![Homebrew](https://img.shields.io/badge/homebrew-mercurialsolo%2Ftap-orange)](https://github.com/mercurialsolo/homebrew-tap)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Downloads](https://img.shields.io/crates/d/claudectl)](https://crates.io/crates/claudectl)\n[![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)]()\n\n\u003csub\u003e~1 MB binary. Sub-50ms startup. Zero config required.\u003c/sub\u003e\n\n[Website](https://mercurialsolo.github.io/claudectl/) | [Demo](https://asciinema.org/a/AJP33vbmHGFVW6zL) | [Blog: Why a local brain?](blog/local-brain-architecture.md) | [Releases](https://github.com/mercurialsolo/claudectl/releases)\n\n\u003ca href=\"https://asciinema.org/a/AJP33vbmHGFVW6zL?autoplay=1\"\u003e\u003cimg src=\"https://asciinema.org/a/AJP33vbmHGFVW6zL.svg\" alt=\"claudectl demo\" width=\"100%\" /\u003e\u003c/a\u003e\n\n## What it does for you\n\nRun `claudectl --brain-stats impact` to see your numbers:\n\n```\n  ╔════════════════════════════════════════════════╗\n  ║              IMPACT SCORECARD                  ║\n  ║             1200 decisions tracked             ║\n  ╠════════════════════════════════════════════════╣\n  ║  Auto-handled                             71%  ║\n  ║  ████████████████████░░░░░░░░  847/1200        ║\n  ║                                                ║\n  ║  Brain accuracy                          96.2%  ║\n  ║  ███████████████████████████░  1154/1200       ║\n  ║                                                ║\n  ║  Coverage vs static rules               2.9x  ║\n  ║  brain ████████████████████████████  100%      ║\n  ║  rules █████████░░░░░░░░░░░░░░░░░░░  34%      ║\n  ║                                                ║\n  ║  Dangerous ops blocked      12  Time saved 42m  ║\n  ║  2 critical | 10 high-risk | 847 auto x 3s    ║\n  ║                                                ║\n  ║  Learning: correction rate 8.4% ↓ 2.1% (-6pp) ║\n  ╚════════════════════════════════════════════════╝\n```\n\n## Install\n\n```bash\nbrew install mercurialsolo/tap/claudectl     # Homebrew (macOS / Linux)\ncargo install claudectl                       # Cargo (any platform)\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eOther methods\u003c/summary\u003e\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/mercurialsolo/claudectl/main/install.sh | sh\nnix run github:mercurialsolo/claudectl\ngit clone https://github.com/mercurialsolo/claudectl.git \u0026\u0026 cd claudectl \u0026\u0026 cargo install --path .\n```\n\n\u003c/details\u003e\n\n## Get started\n\n```bash\nclaudectl                     # Live dashboard — see all sessions at a glance\nclaudectl --init              # Wire up Claude Code hooks (one-time)\nclaudectl --brain             # Enable local LLM auto-pilot\n```\n\n## Why claudectl\n\n- **Local LLM auto-pilot** — a brain that learns your preferences and auto-approves/denies tool calls. No cloud API.\n- **Hive mind** — knowledge distillation, archiving, and curriculum generation. Connect instances to share learnings across machines.\n- **Self-improving** — detects friction patterns, suggests rules, and gets smarter with every correction.\n- **Multi-session orchestration** — run parallel tasks with dependency ordering and cross-session context routing.\n- **Health monitoring** — catches cognitive decay, cost spikes, error loops, and context saturation before they waste money.\n- **Works everywhere** — Claude Code plugin for inline use, TUI dashboard for oversight, CLI for automation.\n\n[Full feature comparison](docs/reference.md#comparison)\n\n## Local LLM Brain\n\nThe brain observes all your sessions and makes real-time decisions:\n\n- **Approve** safe tool calls automatically (reads, greps, test runs)\n- **Deny** dangerous operations before they execute (force pushes, destructive commands)\n- **Terminate** sessions that are looping, stalled, or burning money\n- **Route** summarized output between sessions so they share context\n- **Spawn** new sessions when the brain detects parallelizable work\n\n```bash\nollama pull gemma4:e4b \u0026\u0026 ollama serve    # One-time setup\nclaudectl --brain                         # Advisory mode (default)\nclaudectl --brain --auto-run              # Auto mode: brain executes without asking\nclaudectl --mode auto                     # Or toggle mid-session (Ctrl+b in TUI)\n```\n\nWorks with any OpenAI-compatible endpoint: [ollama](https://ollama.com), [llama.cpp](https://github.com/ggerganov/llama.cpp), [vLLM](https://github.com/vllm-project/vllm), [LM Studio](https://lmstudio.ai).\n\n### How the brain learns\n\nThe 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.\n\n| Level | What it learns | Example |\n|-------|---------------|---------|\n| **Conditional preferences** | Context-dependent rules via decision tree splits | `approve [Bash] \"git push\" when cost\u003c$5 (n=8)` |\n| **Outcome tracking** | Correlates decisions to detect \"approved but broke\" | Downweights false-positive approvals |\n| **Temporal patterns** | Behavioral sequences and time-of-day behavior | `After 3+ errors: user usually denies` |\n| **Per-project models** | Separate preferences per project | `[Read] always approve in frontend, usually deny in infra` |\n| **Adaptive thresholds** | Per-tool confidence requirements based on accuracy | 90%+ accurate on Read = auto-execute at 0.5 confidence |\n\n### Self-improving sessions\n\nThe brain automatically detects friction patterns and suggests workflow improvements:\n\n```bash\nclaudectl --brain --insights on     # Enable auto-generation (every 10 decisions)\nclaudectl --brain --insights        # View current insights\n```\n\nDetects: 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.\n\n## Claude Code Plugin\n\nIntegrates the brain directly into Claude Code sessions — no TUI required.\n\n| Component | What it does |\n|-----------|-------------|\n| **Brain gate hook** | Queries the brain before every Bash/Write/Edit call |\n| `/brain on\\|off\\|auto` | Toggle brain mode mid-session (or `Ctrl+b` in TUI) |\n| `/sessions` | Show all active sessions with status, cost, health |\n| `/spend` | Cost breakdown by project and time window |\n| `/brain-stats` | Brain learning metrics and accuracy |\n| `/auto-insights` | Auto-generated workflow insights |\n\n## Headless Mode\n\nRun the full autonomous stack without a TUI. Attach a dashboard from another terminal.\n\n```bash\nclaudectl --headless --brain --auto-run           # Human-readable events\nclaudectl --headless --brain --auto-run --json    # Structured JSON events\n```\n\nWhat runs in headless mode:\n- Brain inference (approve/deny/route/spawn with adaptive confidence)\n- Coordination layer (leases, interrupts, handoffs, memory)\n- Context rot prevention (auto-raises compact/stop interrupts when decay detected)\n- Rule evaluation and health monitoring\n\nThe TUI dashboard can run alongside -- both share state via the coordination SQLite store, brain decision logs, and session discovery.\n\n```bash\n# Background daemon\nnohup claudectl --headless --brain --auto-run \u003e ~/.claudectl/autopilot.jsonl 2\u003e\u00261 \u0026\n\n# Attach dashboard in another terminal\nclaudectl\n```\n\n## Coordination Layer\n\nMulti-agent coordination for parallel coding sessions. Prevents duplicate work, manages ownership, and routes context between agents.\n\nBuild with `cargo build --features coord` to enable.\n\n```bash\n# Ownership leases — prevent two agents from editing the same file\nclaudectl --coord \"claim --session sess_1 --path src/app.rs --mode exclusive\"\nclaudectl --coord \"release lease_123\"\n\n# Handoffs — structured context transfer between sessions\nclaudectl --coord \"handoff --from sess_1 --to sess_2 --task task_1 --summary 'Fix path normalization'\"\n\n# Interrupts — typed cross-agent signals with delivery modes\nclaudectl --coord \"raise --type pause --target sess_1 --reason 'lease conflict'\"\nclaudectl --coord \"ack intr_123\"\n\n# Memory — validated patterns promoted from brain decisions\nclaudectl --coord \"promote --project myproject\"\nclaudectl --coord \"context --session sess_1\"      # Preview injected context\n\n# Inspection\nclaudectl --coord leases                           # Active ownership leases\nclaudectl --coord interrupts                       # Pending interrupts\nclaudectl --coord events                           # Event audit log\nclaudectl --coord metrics                          # Coordination health metrics\nclaudectl --coord eval                             # Run 10 eval scenarios\nclaudectl --coord adapters                         # Registered agent adapters\n```\n\nThe 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.\n\n## Hive Mind \u0026 Relay\n\nThe brain distills your decisions into shareable knowledge. Connect instances across machines to build a convergent hive mind.\n\n```bash\n# Hive knowledge is built-in — view what the brain has learned\nclaudectl --hive status\nclaudectl --hive knowledge\nclaudectl --hive distill              # Condense archive into curriculum\n\n# Add relay for cross-machine networking\ncargo install claudectl --features relay\nclaudectl --relay invite              # Generate an invite code\nclaudectl --relay \"join YEK-AGA-YHK-QAA-BM\"   # Join from another machine\nclaudectl --relay discover            # Scan LAN for nearby instances\n```\n\nKnowledge categories (best practices, techniques, workflow patterns) propagate automatically. Personal patterns (time-of-day habits, cost tolerance) stay local. You control what's shared:\n\n```toml\n[hive]\nshare_categories = [\"best_practice\", \"technique\"]\nexclude_tools = [\"Write\"]\nmax_units = 500\nmax_prompt_units = 20\n```\n\nSee the [full Relay \u0026 Hive Mind guide](docs/relay.md).\n\n## Orchestrate Sessions\n\nRun coordinated tasks with dependency ordering, retries, and cross-session data routing:\n\n```json\n{\n  \"tasks\": [\n    { \"name\": \"auth\", \"cwd\": \"./backend\", \"prompt\": \"Add JWT auth middleware\" },\n    { \"name\": \"tests\", \"cwd\": \"./backend\", \"prompt\": \"Update API tests. Previous: {{auth.stdout}}\", \"depends_on\": [\"auth\"] },\n    { \"name\": \"docs\", \"cwd\": \"./docs\", \"prompt\": \"Document the new auth flow\", \"depends_on\": [\"auth\"] }\n  ]\n}\n```\n\n```bash\nclaudectl --run tasks.json --parallel\nclaudectl --decompose \"Add auth, write tests, update docs\"   # Auto-split into parallel tasks\n```\n\n## Session Health Monitoring\n\nContinuously checks each session and surfaces problems in the dashboard:\n\n- **Cognitive decay** — composite 0-100 score tracking degradation over time\n- **Proactive compaction** — suggests `/compact` at 50% context, before the 80/90% thresholds\n- **Cost spikes** — flags when burn rate exceeds the session average\n- **Loop detection** — catches tools failing repeatedly in retry loops\n- **Stall detection** — sessions spending money but producing no edits\n- **File conflicts** — detects when multiple sessions edit the same file\n\n## Spend Control\n\n```bash\nclaudectl --budget 5 --kill-on-budget     # Auto-kill at $5\nclaudectl --notify                        # Desktop notifications on blocks\nclaudectl --stats --since 24h            # Aggregated cost statistics\n```\n\n## Auto-Rules\n\n```toml\n[[rules]]\nname = \"approve-cargo\"\nmatch_tool = [\"Bash\"]\nmatch_command = [\"cargo\"]\naction = \"approve\"\n\n[[rules]]\nname = \"deny-rm-rf\"\nmatch_command = [\"rm -rf\"]\naction = \"deny\"\n\n[[rules]]\nname = \"kill-runaway\"\nmatch_cost_above = 20.0\naction = \"terminate\"\n```\n\nRules support matching by tool, command, project, cost, and error state. Deny rules always take precedence.\n\n\u003cdetails\u003e\n\u003csummary\u003eMore features\u003c/summary\u003e\n\n### Idle Mode\n\nWhen you step away, claudectl can run pre-configured low-risk tasks. A morning report summarizes what happened.\n\n### Session Lifecycle\n\nAuto-restart sessions on context saturation with checkpoint + summary handoff.\n\n### Record and Share\n\nPress `R` on any session for a highlight reel GIF (edits, commands, errors — idle time stripped). Or `claudectl --record demo.gif` for the full dashboard.\n\n### Launch and Resume\n\n`claudectl --new --cwd ./backend --prompt \"Add auth\"` or press `n` in the dashboard.\n\n### Filter and Search\n\n`--filter-status NeedsInput`, `--focus attention`, `--search \"project\"`, `--watch` for streaming.\n\n\u003c/details\u003e\n\n## Docs\n\n| | |\n|---|---|\n| [Quick Start](docs/quickstart.md) | Install, init, first dashboard |\n| [Reference](docs/reference.md) | All flags, keybindings, modes |\n| [Configuration](docs/configuration.md) | Config files, hooks, rules |\n| [Relay \u0026 Hive Mind](docs/relay.md) | Connect instances, share knowledge |\n| [Terminal Support](docs/terminal-support.md) | Compatibility matrix |\n| [Troubleshooting](docs/troubleshooting.md) | Common issues and FAQ |\n| [Contributing](docs/contributing.md) | Setup and guidelines |\n| [Changelog](CHANGELOG.md) | Release history |\n\n## Community\n\n- Questions or ideas? [Start a Discussion](https://github.com/mercurialsolo/claudectl/discussions)\n- Found a bug? [Open an issue](https://github.com/mercurialsolo/claudectl/issues/new)\n- Share your setup in [Show \u0026 Tell](https://github.com/mercurialsolo/claudectl/discussions/categories/show-and-tell)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmercurialsolo%2Fclaudectl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmercurialsolo%2Fclaudectl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmercurialsolo%2Fclaudectl/lists"}