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

All of the following are modes of the shell MCP tool (basemind shell <mode> on the CLI). basemind comms is a separate CLI group for the comms daemon’s own lifecycle (daemon/start/stop/status/doctor) — it is unrelated to shell sessions.

`shell` mode `spawn`

Start a detached headless shell session.

{
  "mode": "spawn",
  "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 kill it (shell mode kill) or it exits naturally.

`shell` mode `send`

Type input into a session’s stdin.

{
  "mode": "send",
  "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` mode `capture`

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

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

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

`shell` mode `list`

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

{
  "mode": "list"
}

`shell` mode `kill`

Terminate a session.

{
  "mode": "kill",
  "session_id": "abc123def456"
}

`shell` mode `broadcast`

Send the same input to multiple sessions at once.

{
  "mode": "broadcast",
  "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 {
  "mode": "spawn",
  "command": "bash",
  "cwd": "/repo"
}
→ session_id: "test-runner-001"

shell {
  "mode": "send",
  "session_id": "test-runner-001",
  "text": "cargo test --release"
}

shell {
  "mode": "capture",
  "session_id": "test-runner-001"
}
→ "running test_outline ... ok"

Coordinate builds across shards:

shell { "mode": "spawn", "command": "bash", "cwd": "/repo" }
→ "shard-1"
shell { "mode": "spawn", "command": "bash", "cwd": "/repo" }
→ "shard-2"

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

// poll each shard's output
shell { "mode": "capture", "session_id": "shard-1" }
shell { "mode": "capture", "session_id": "shard-2" }

Discipline

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

Agent Shells

Tools

shell mode spawn

shell mode send

shell mode capture

shell mode list

shell mode kill

shell mode broadcast