Agent Shells

Included in every prebuilt download. Agents can spawn detached terminal sessions, send input, read screen output, and coordinate with each other over agent comms. Sessions can be fully headless or opened in a real terminal tab or window so you watch along.

--features shells or --features full

Tools

shell_spawn

Start a detached headless shell session.

{
  "command": "bash",
  "cwd": "/home/user/project",
  "env": {
    "RUST_LOG": "debug"
  },
  "title": "test-runner"
}

Returns a session_id you use in subsequent calls. The session stays alive until you shell_kill it or it exits naturally.

shell_send

Type input into a session’s stdin.

{
  "session_id": "abc123def456",
  "text": "cargo test --all",
  "no_enter": false
}

Set no_enter: true to send text without a newline, useful for interactive prompts.

shell_capture

Read the visible screen of a session — stdout/stderr buffer, last N lines.

{
  "session_id": "abc123def456",
  "lines": 50
}

Returns the visible output buffer. Useful for polling session status without waiting for it to finish.

shell_list

List all live sessions — returns session_id, command, pid, creation time.

{}

shell_kill

Terminate a session.

{
  "session_id": "abc123def456"
}

shell_broadcast

Send the same input to multiple sessions at once.

{
  "text": "echo 'ready'",
  "session_ids": [
    "abc123def456",
    "def456ghi789"
  ]
}

Coordination

A spawned session and the agent that started it can message each other over agent comms (see Agent comms). This lets orchestrating agents delegate long-running tasks (builds, tests, deploys) to background workers and check in on progress asynchronously.

Examples

Run a test suite in the background:

shell_spawn {
  "command": "bash",
  "cwd": "/repo"
}
→ session_id: "test-runner-001"

shell_send {
  "session_id": "test-runner-001",
  "text": "cargo test --release"
}

shell_capture {
  "session_id": "test-runner-001"
}
→ "running test_outline ... ok"

Coordinate builds across shards:

shell_spawn { "command": "bash", "cwd": "/repo" }
→ "shard-1"
shell_spawn { "command": "bash", "cwd": "/repo" }
→ "shard-2"

shell_broadcast {
  "text": "cargo build --release -p basemind",
  "session_ids": ["shard-1", "shard-2"]
}

// poll each shard's output
shell_capture { "session_id": "shard-1" }
shell_capture { "session_id": "shard-2" }

Discipline

• Use shell_spawn for long-running tasks. Don’t block on test suites or deployments; let them run in the background.
• Poll with shell_capture, don’t assume completion time. Machine speed varies; check output before proceeding.
• Coordinate with comms. A background worker can post updates to a room while an orchestrator polls and decides next steps.
• Clean up with shell_kill or let sessions exit naturally. Don’t accumulate idle sessions.

Note

Headless sessions have no real terminal — they buffer stdout/stderr and you read it with shell_capture. For interactive shells (passing -it flags) or to watch a session’s output in real time, the agent can open a tab or window in your terminal emulator.

See also

Agent comms