hive

Overview Schema Source Related Servers Discussions Admin

agent_spawn

Spawn a worker agent in a tmux pane, auto-briefed and locked to the project, so you can delegate tasks and coordinate a visible crew; optionally run read-only.

Instructions

Spawn a worker agent (default: claude, or the project's hive.yml agents: default). A claude worker is briefed automatically: the full brief is appended to its system prompt, so send it its assignment directly. A command or harness that resolves to a known harness (claude, codex) not listed in the project's hive.yml agents: is refused; absent agents: means claude only. A command hive cannot classify the screen of (claude and codex both do; a harness with no entry does not) can be spawned but NOT typed into: the receipt carries brief_path and says so, and agent_send's text path and wakes both refuse that pane. Set read_only: true to block local file writes and mutating shell while keeping Hive MCP available; agent_resume preserves this mode and agent_status reports it. Only bare claude/codex executables are supported in this mode, with only effort-setting extra_args. The worker is locked to this project. Humans can watch with: tmux attach -t hive-main.

Input Schema

TableJSON Schema

Name	Required	Description
`cwd`	No	Working directory, e.g. a git worktree path. Defaults to the project root.
`name`	No	Display name; defaults to worker-N. This is how you address the worker later.
`model`	No	Passed as --model to the agent command.
`layout`	No	How to arrange the lead's window when placement is split. main-vertical gives the lead the left half with workers stacked on the right; tiled (default) splits evenly. Projects can set a default in hive.yml.
`command`	No	Raw agent command to run. Overrides harness when both are given. Defaults to the project's hive.yml agents: default, or claude. Refused if it resolves to a known harness the project's agents: list does not allow.
`harness`	No	Spawn a known harness by name (e.g. "codex") instead of a raw command. Ignored when command is also given. Must be in the project's hive.yml agents: list (default: claude only).
`todo_id`	No	The todo this worker is on, recorded as a link (a non-archived todo in the same project). Changes no todo status.
`placement`	No	split (default): the worker appears as a pane in the lead's window, auto-tiled, so the whole crew shares one screen. window: its own tmux window (an iTerm tab under control mode).
`read_only`	No	Prevent local file writes and mutating shell commands while allowing Hive MCP tools. Only bare claude/codex executables. Extra args allow codex -c model_reasoning_effort=low\|medium\|high\|xhigh, or claude --effort low\|medium\|high\|xhigh\|max; all other arguments are refused.
`extra_args`	No	Extra CLI arguments.
`project_id`	No	Different project override. Use ONLY when the user explicitly asks for another project by name; otherwise stay in the current scope, even when results are empty.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`name`	Yes
`note`	No
`tail`	No
`ready`	No
`exited`	No
`layout`	No
`actor_id`	Yes
`agent_id`	Yes
`read_only`	No
`brief_path`	No
`codex_home`	No
`hive_notice`	No
`tmux_target`	Yes
`instructions`	No
`config_warnings`	No
`worktree_install`	No
`landed_in_project`	No
`codex_instructions`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.11.5Oct 15, 2026

addedInput schema / properties / todo_id

Added value: +{
+  "description": "The todo this worker is on, recorded as a link (a non-archived todo in the same project). Changes no todo status.",
+  "exclusiveMinimum": 0,
+  "maximum": 9007199254740991,
+  "type": "integer"
+}

Changed2 schema fields changedv1.4.0Sep 30, 2026

addedInput schema / properties / read_only

Added value: +{
+  "description": "Prevent local file writes and mutating shell commands while allowing Hive MCP tools. Only bare claude/codex executables. Extra args allow codex -c model_reasoning_effort=low|medium|high|xhigh, or claude --effort low|medium|high|xhigh|max; all other arguments are refused.",
+  "type": "boolean"
+}

addedOutput schema / properties / read_only
```
Added value: +{
+  "type": "boolean"
+}
```

Changed1 schema field changedv1.2.2Sep 26, 2026
- addedOutput schema / properties / hive_notice
```
Added value: +{
+  "type": "string"
+}
```
First observedv1.0.0Sep 22, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Far exceeds the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), which only say this is a non-read, non-idempotent, non-destructive write. The description adds the auto-briefing behavior, the harness allow-list refusal rule, the classify/type-into restriction with brief_path in the receipt, read_only semantics, project locking, and the tmux attach watch command.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Information-dense and front-loaded with the main action, but it is a single sprawling paragraph with heavily nested parentheticals ("A command hive cannot classify the screen of (claude and codex both do; a harness with no entry does not)..."), which hurts parseability. Every sentence carries content, but the structure is tangled.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 11-parameter spawn tool with an output schema present, the description covers the briefing model, refusal conditions, read_only mode, and project scoping without needing to explain return values. An agent has everything required to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the command-vs-harness precedence and refusal rule, the exact extra_args allow-list under read_only, and the project_id scope restriction. It clarifies the interplay among these parameters rather than merely restating them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource ("Spawn a worker agent") and immediately names the default (claude, or the project's hive.yml agents: default). It is clearly distinguishable from siblings like agent_resume, agent_send, and agent_status, which it references by their distinct roles.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives strong conditional guidance: claude workers are briefed automatically so "send it its assignment directly" (routing to agent_send), and it spells out when spawning is refused (unlisted known harness, unclassifiable harness). It cross-references agent_resume and agent_status but never explicitly frames when to choose spawn vs those alternatives, keeping it short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.