Claude Code Hive Manager
Coordinate Claude Code sessions across machines and build reusable project knowledge locally.
- Source repo
- mercurialsolo/claudectl
- Stars
- ★ 205
- Last updated
- 5d ago
- License
- MIT
- Primary language
- Rust
- FA score
- 58/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesClaude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A solo developer running several Claude Code sessions can use the dashboard to track spend, error loops, and context health.
- Not a fit if
- Teams seeking native ChatGPT or Codex integration
- Users who do not want to run a local CLI
- Source review
- 58/100 · Major gaps
What does this agent do, and when should you use it?
claudectl is a Rust CLI with a terminal dashboard and a Claude Code plugin for observing and coordinating coding sessions. Its relay connects machines so users can delegate work, move sessions, and sync knowledge among approved hive members. An optional local LLM brain can approve or deny tool calls using rules and learned preferences, detect session problems, and route summaries between sessions. The coordination layer, agent bus, and supervisor handle leases, messaging, and verified task lifecycles, with state stored in local SQLite databases. It is used through the CLI, plugin, MCP stdio interface, or headless daemon; the README documents macOS and Linux support and Cargo installation.
claudectl reads Claude Code session state and tool-decision activity, then records brain decisions, coordination events, and task state locally. The dashboard shows session health, cost, and errors; with the brain configured, rules or a local LLM can advise on or automatically handle calls such as Bash, Write, and Edit, while detecting loops, stalls, and context decay. After machines are paired and claudectl relay serve is running, users can discover peers, delegate tasks, send sessions, and sync approved knowledge units. claudectl coord provides resource leases, handoffs, and interrupts; claudectl bus provides a role directory, mailboxes, and an MCP server; claudectl supervisor records tasks in a SQLite ledger, assigns sessions, and runs declared verifiers. Outputs include the terminal dashboard, JSON events, audit records, task states, and optional Prometheus metrics.
- A solo developer running several Claude Code sessions can use the dashboard to track spend, error loops, and context health.
- A developer with a laptop and workstation can delegate tests or parallel coding work to the idle machine, or move a session with relay.
- A small engineering team can use coordination leases and handoffs to prevent sessions from editing the same resource and to transfer context.
- A Claude Code user who wants fewer repetitive approvals can configure the local brain to learn project preferences and handle low-risk tool calls.
- A developer who needs unattended work with result checks can submit supervisor tasks with command, brain, or agent verifiers.
How do you install or deploy this agent?
Install on macOS or Linux with Homebrew, or install through Cargo. Building from source requires Rust 1.88 or later. Run init to configure the budget, brain detection, Claude Code hooks, bus role, and skill suggestions, then run doctor to check the setup. To use the Claude Code features, install the plugin from the repository marketplace separately.
How do you use this agent?
After installation and initialization, launch the dashboard; demo provides a guided tour without live sessions. The brain runs in advisory mode by default. For local model inference, use Ollama or another OpenAI-compatible endpoint. To connect machines, run a relay on each and pair them with invite/join; the bus MCP server can be started over stdio.
What are this agent's strengths and limitations?
- One CLI combines a TUI, Claude Code hooks, and automation interfaces for observing multiple sessions.
- Relay supports cross-machine discovery, delegation, and session transfer; hive membership can propagate selected knowledge categories.
- Coordination and supervisor provide leases, task dependencies, retries, and verifier workflows, with coordination state persisted in SQLite.
- The brain can use a local LLM or built-in rules; the README says decision data stays on the machine.
- Claude Code is the primary documented integration; the README does not describe native ChatGPT, Codex, or other coding-agent plugins.
- Automatic approvals need careful configuration: the brain gate can act on Bash, Write, and Edit calls, and auto-run lets the brain execute without asking each time.
- Full local LLM inference requires Ollama or another OpenAI-compatible endpoint; the README gives no model cost or hardware baseline.
- Cross-machine relay requires network connectivity, a running service on each machine, pairing, and access-policy setup.
- Source builds require Rust 1.88+; some remote supervisor tasks also require compatible build features on both machines and matching repository paths.
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Claude Code Hive Manager This agent | 58 · Major gaps | CLIFree + model costs | ★ 205 | 5d ago | Rust | Claude Code |
| AGF Local Coding Session Finder | 77 · Good | CLIFree | ★ 162 | 1mo ago | Rust | Codex · Claude Code |
| Grounded Docs MCP Server | 78 · Good | CLIFree + model costs | ★ 1.9k | 7d ago | TypeScript | ChatGPT · Claude Code |
| Vigil Multi-Agent Terminal Orchestrator | 68 · Some gaps | Desktop appFree + model costs | ★ 28 | 1mo ago | Swift | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
The files describe hive join approval, scoped/expiring/revocable grants, read-only queries, sensitive-file exclusions from indexing, and uninstall options, so confirmation, data flow, and recovery receive meaningful credit. However, key security guarantees are mostly documented claims; the sample does not show the boundary implementations. The product reads session transcripts, runs hooks and terminal input, and can auto-execute actions, terminate sessions, relay over networks, or run user-configured shell hooks, giving it a broad permission surface. Dependency review and publisher identity are also limited by the packet, so these criteria do not score highly.
The CI file specifies cross-platform tests, feature-combination checks, standalone crate builds, and documentation-link checks, while README and Cargo metadata describe default features and MSRV. However, AGENTS.md and CLAUDE.md disagree on default features and binary size, and some sampled skills/docs use legacy CLI flags; the packet does not establish that CI ran successfully. This lowers consistency and dependency-availability scores. Doctor, logging, concrete fix hints, and troubleshooting guidance are comparatively well documented.
The documentation covers single-machine and multi-session use, the Claude Code plugin, unattended operation, cross-machine collaboration, and read-only third-party queries. Feature flags, configuration layers, read-only membership, grants, and local/remote boundaries are described, though some capability limits rely on documentation claims and the sampled skills do not cover the full product. macOS/Linux, WSL, terminal backends, and Rust requirements are addressed; native Windows support is limited.
README, quickstart, configuration, troubleshooting, reference material, and skill files provide a clear information structure. Installation, upgrades, examples, FAQ, platform limitations, and the MIT license are explicit. Deductions reflect drift among sampled descriptions of defaults, binary size, and command flags; version information appears in Cargo metadata and skill metadata, but a changelog and ongoing maintenance responsibility are not clear in the supplied material. Unverified publisher identity is not itself a deduction.
Outputs include session tables, cost and health indicators, decision audits, cited read-only query results, structured task state, and JSON modes that can support downstream use. Multi-session coordination and local learning may provide useful value. The packet offers no independent support for the README's accuracy or time-savings figures, and does not provide enough evidence to assess the tradeoff between runtime resources, setup burden, and benefits.
CLI behavior, configuration, hooks, state locations, and some safety behaviors are traceable to files or concrete examples, and documentation often distinguishes configuration facts from recommendations. The CI workflow describes intended checks but does not prove they passed. Many performance, safety, and effectiveness claims lack corroborating implementation or results in the packet, and the documentation contains some inconsistencies.
- This is a low-confidence static review; the CI workflow shows configured checks, not that they were run or passed for this revision.
- Before enabling brain auto mode, relay, shell hooks, or hard purge, review the configuration and target: these features can affect tool calls, network connections, or local data.
- Documentation differs on default features, binary size, and some CLI flags; verify the installed version with its current --help and doctor output.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/claudectl)<a href="https://followagents.com/en/agents/claudectl"><img src="https://followagents.com/badge/claudectl.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
What's Changed * fix(relay): preserve explicit port precedence by @mikemikimike in https://github.com/mercurialsolo/claudectl/pull/615 * Normalize line endings to LF with .gitattributes by @mercurialsolo in https://github.com/mercurialsolo/claudectl/pull/616 * Release 0.92.4 by @mercurialsolo in https://github.com/mercurialsolo/claudectl/pull/617 New Contributors * @mikemikimike made their first contribution in https://github.com/mercurialsolo/claudectl/pull/615 Full Changelog: https://github.com/mercurialsolo/claudectl/compare/v0.92.3...v0.92.4View on GitHub ↗ -
Release notes excerpt
What's Changed * Show which paired peers are live, and prune the ones that are gone by @mercurialsolo in https://github.com/mercurialsolo/claudectl/pull/612 * Release 0.92.3 by @mercurialsolo in https://github.com/mercurialsolo/claudectl/pull/613 Full Changelog: https://github.com/mercurialsolo/claudectl/compare/v0.92.2...v0.92.3View on GitHub ↗ -
Release notes excerpt
What's Changed * Packaging: point homebrew-core and AUR at 0.91.1 by @mercurialsolo in https://github.com/mercurialsolo/claudectl/pull/601 * Route a roleless supervisor task to the role that owns its work (#596 follow-up) by @mercurialsolo in https://github.com/mercurialsolo/claudectl/pull/604 * Release 0.92.1 by @mercurialsolo in https://github.com/mercurialsolo/claudectl/pull/607 * Add a hive skill and make the plugin installable from Claude Code by @mercurialsolo in https://github.com/mercurialsolo/claudectl/pull/609 …View on GitHub ↗
FAQ
Does it require a cloud LLM?
TYPESAFE_API_KEY is configured.Does a hive share my knowledge automatically?
Can it execute tool calls without asking me?
--mode off is available. The plugin brain gate evaluates tool calls; configure a local LLM and understand the rule coverage before enabling automatic execution.How does the supervisor decide a task is done?
run, brain, or agent verifiers. Failed output is added to the retry prompt; after the retry limit, the task moves to NEEDS_HUMAN.Thanks — we use this to improve the page.