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.1 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?)

Submit a shell command for background execution (sh -c <cmd>). Returns a task ID immediately; the command runs asynchronously in a harness-managed tokio task. Stdout and stderr stream to harness/bash-tasks/<id>.{out,err}. When the task completes (or times out, or the process errors), the harness wakes the agent with a summary body — handle on a future turn. Optional timeout_secs: pass a value for a deadline, or omit for no timeout (runs until natural exit).

Exposed as mcp__bash__run.

status(id)

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)

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.