hive

Overview Schema Source Related Servers Discussions Admin

agent_spawn

Launch a project-locked worker agent (Claude or Codex) in a shared tmux pane, automatically briefed and ready for assignments.

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. 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).
`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).
`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
`brief_path`	No
`codex_home`	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.

First observedv1.0.0Sep 22, 2026

TDQS

A4.4/5.0

Behavior5/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It extensively covers side effects: automatic briefing, refusal of unauthorized harnesses, project locking, inability to type into unclassifiable command panes, and human monitoring via tmux. This is well beyond a minimal statement of the action.

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

Conciseness4/5

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

The description is dense but every clause carries meaningful information, and the core action is front-loaded. The long, semicolon-heavy sentences make it slightly harder to parse, but there is no filler or repetition.

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 9-parameter tool with no annotations, the description covers defaults, refusal conditions, edge cases, project scoping, and monitoring. An output schema exists, so return-value explanation is not required. Nothing essential for calling this tool correctly is missing.

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

Parameters3/5

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

All 9 parameters are documented in the input schema, so the baseline is 3. The description adds valuable policy context around command/harness resolution and defaults, but it does not add per-parameter semantics beyond the schema's own descriptions. It neither harms nor significantly elevates parameter understanding.

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?

The description states a specific verb and resource ('Spawn a worker agent') and distinguishes this tool from downstream interaction tools by explaining what spawn does and what it refuses. It also clarifies the default command/harness behavior, leaving no ambiguity about the tool's purpose.

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?

The description gives clear usage context: how to brief a claude worker, when commands/harnesses are refused, and which panes cannot be typed into later. It references agent_send's refusal behavior, but it does not explicitly contrast agent_spawn against other lifecycle siblings like agent_resume or agent_close, which would have made the guidance complete.

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