vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hyperhive/docs/tools/bash.md

2.7 KiB
Raw Blame History

Bash execution tools

Background shell execution via hive-bash-mcp. Tools land as mcp__bash__<tool> (the MCP server name is bash, not hyperhive). Available on every agent unconditionally — harness-base.nix always injects bash into hyperhive.extraMcpServers (with allowedTools = ["*"]), so mcp__bash__* is in --allowedTools for every claude invocation regardless of tool groups.

Tools

run(cmd, timeout_secs?, wait_seconds?)

Submit a shell command for background execution (sh -c <cmd>). Stdout and stderr stream to harness/bash-tasks/<id>.{out,err}. When the task completes (or times out, or the process errors), the harness fires a wake with from: "bash-task-<id>" and the exit code

  • last stdout lines in the body; handle it on a future turn.
  • timeout_secs — kill the task after N seconds and mark it timed_out. Omit for no timeout (runs until natural exit).
  • wait_seconds — inline poll before returning (capped at 30). When the task finishes within the window the full status is returned immediately and no wake is fired; when the window expires the task keeps running and the normal task started: id=<id> response is returned. Defaults to 3 — pass wait_seconds: 0 to disable inline waiting and always get the immediate response.

Exposed as mcp__bash__run.

status(id, wait_seconds?)

Poll the status of a task submitted with run. Returns:

  • status — pending / running / done / timed_out / interrupted
  • exit_code — set when done
  • run duration
  • last 4 KiB of stdout and stderr (full output in the .out / .err files)

wait_seconds — optional inline poll (capped at 30): when the task finishes within the window the full status is returned immediately. Useful to avoid a separate round-trip when the task is expected to finish soon.

Tasks marked interrupted had their process killed by a harness restart; a best-effort wake was still sent so the agent is not silently blocked.

Exposed as mcp__bash__status.

Namespace note

run and status live in the bash MCP server, not hyperhive. So the tool names in claude are mcp__bash__run and mcp__bash__status. The Bash built-in tool is blocked — all shell execution goes through this structured path so tasks get task-id tracking and structured output.

Relationship to the execution tool group

ToolGroup::Execution exists and appears in AGENT_DEFAULT, but its tools() returns ["run", "status"] which the harness expands to mcp__hyperhive__run / mcp__hyperhive__status — tools that don't exist in the hyperhive MCP server (dead entries). Removing execution from an agent's groups has no effect on bash availability. Bash is registered separately via the extraMcpServers path described above.