| Filename | Latest commit message | Latest commit date |
|---|---|---|
657875b2fa
A `start` may now name a role: `role: "reviewer"` loads the spawning agent's own `subagent_roles/reviewer.md` and renders it, alone, into one per-session file that `--append-system-prompt-file` points at. The role is the system prompt; the task is the turn, never the other way round — a task baked into the system prompt would re-assert itself as an instruction on every later turn of a continued session, not just the one it was written for. The task instructions (`prompt_file`) are read and folded ahead of the turn's own prompt instead, the same channel that carries them to the subagent without a role. The argument is optional, so every existing call is unchanged — pinned by a test that a pre-role payload still deserializes with `role` absent from the schema's required set, and another that the no-role path reaches claude with the caller's own file, unrendered, and the trigger untouched. With a role, one test pins the system-prompt file to the role's text and nothing of the task, and another pins the task still reaching the subagent as the turn's prompt. A role name with no file fails the call, before the session name is even reserved, and the error lists the roles the directory does hold. No agent ships roles yet, so named-but-missing is the ordinary first-run state; a fallback there would spawn a subagent under a prompt missing every clause the role existed to carry. An empty file and a name that is not a plain identifier refuse the same way. |
||
| .. | ||
| bash.md | ||
| forge-cli.md | ||
| forge.md | ||
| hivectl-cli.md | ||
| hivectl.md | ||
| matrix.md | ||
| README.md | ||
| scheduling.md | ||
| subagent.md | ||
| swarm-logs-cli.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. - 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
get_host_journaldiagnostics tool.