| Filename | Latest commit message | Latest commit date |
|---|---|---|
b18348bc9a
`start` takes an optional `goal`. With one set a session stops being a single turn: when a turn ends and nothing has said to stop, the daemon spawns another turn re-prompting the subagent toward that goal, up to `max_turns` (default 5, per-session). Without a goal nothing changes — one turn, one todo, same as before. Four things end a run, each recorded distinctly and reported by `status`: the turn ending with no goal, `goal_reached`, `need_help`, and the turn cap. The last says so out loud rather than stopping quietly — the todo states the harness limit was reached and the goal was never reported reached. Every stop extends the done message rather than replacing it, and lands in the session's report file when it has one. The path is never inferred: it comes from `start`'s `report_file` or from the subagent naming where it wrote. `goal_reached` and `need_help` are the subagent's own, served on a second route (`/signal/mcp`) that carries those two tools and nothing else, so reporting on a run can't become starting one. `goal_reached` is built as a label, never a gate: it is self-reported by a subagent that has just been re-prompted with "you haven't reached the goal", which is exactly the incentive to claim it — the same failure class as a build report asserting the tests pass. Every surface that renders it says so. `need_help` is the blocking signal, and shows in `status` as its own state so a parent polling it sees the block without reading a file. `status` also carries `turn N of M`: with 4330's last-event age, that separates working from wedged from out of turns off one answer. Two bugs the new tests caught: a `tokio::fs::File` was dropped without flushing, so the report line was written to nothing, and the plain idle answer dropped the turn counter. Also documents `await_resume`'s third case — a closed channel with no send, which fails open the same as `Underway` — per argus on #4411. Refs #4403 |
||
| .. | ||
| bash.md | ||
| forge-cli.md | ||
| forge.md | ||
| hivectl-cli.md | ||
| hivectl.md | ||
| lifecycle.md | ||
| matrix.md | ||
| README.md | ||
| scheduling.md | ||
| subagent.md | ||
| swarmctl-cli.md | ||
Tools
hivectl is your tool — the operator's own host CLI. Everything
else here documents the tool surface your agents get inside their
containers (the MCP tools an agent's own claude session can call).
You never call these directly, but they're the reference for what an
agent can actually do — useful when you're trying to understand or
debug agent behavior.
For the operator
- hivectl — the curated guide: provisioning forge and matrix accounts, gateway htpasswd management, container lifecycle shortcuts, interactive agent shell access.
- hivectl-cli — the exhaustive, autogenerated flag-by-flag reference, kept in lockstep with the binary by CI.
For the swarm operator
- swarmctl-cli — the exhaustive, autogenerated
flag-by-flag reference for
swarmctl, kept in lockstep with the binary by CI the same wayhivectl-cli.mdis.swarmctlitself runs as root on the swarm-controller host, not throughhivectl— seeswarmctl/README.mdfor why. Two verb families today:user(authelia's subject store, edited in place) andagent create(queues the swarm-controller's creation job graph). No curated guide yet; add one here if/when that grows.
What your agents can do
- bash — background shell execution (
mcp__bash__*), available on every agent unconditionally. - subagent — spawn nested headless claude sessions
(
mcp__subagent__{start,continue,status,interrupt}), shipped default-on for every agent today alongsidebash(expected to become a real opt-in capability later). - forge — the
hive-forgeForgejo CLI every agent has for issues, PRs, and comments. Not an MCP tool — a binary agents shell out to instead of ad-hoc curl. - forge-cli — the exhaustive, autogenerated
flag-by-flag reference for
hive-forge, kept in lockstep with the binary by CI the same wayhivectl-cli.mdis. - lifecycle — kill/start/restart/update for the agents in a caller's own subtree, plus the approval-gated config-change tools.
- matrix — the matrix MCP tool surface
(
mcp__matrix__*) for agents with a matrix account, multiple accounts per agent, and declaring extra MCP servers generally. - scheduling — scheduled prompts (operator
approval required) and the diagnostics tools (
get_logs,get_host_journal).