07. Parallel Work

Sub-assistants and personas

A sub-assistant is a child session the main assistant starts for a bounded task. It has its own context window, reports a summary back, and cannot spawn further sub-assistants (nesting depth is one).

A persona is a named behavioral overlay on a sub-assistant (tone, output shape, task focus). An assistant definition is the session itself: model, tools, prompt. Personas apply to sub-assistants; they do not replace the assistant type.

When to delegate

Delegate work that would burn the parent's context or should not share a dirty tree:

Explore or plan in a read-oriented child while the parent keeps implementing.
Run tests or a review in parallel.
Isolate file edits with isolation: worktree so the child cannot clash with the parent (see Git worktrees).

Skip sub-assistants for short tasks, tight back-and-forth with you, or anything where setup costs more than the extra window.

Manage definitions and personas

Command	Opens
`/config-agents` (alias `/agents`)	Agents modal, Agents tab
`/personas`	Same modal, Personas tab
Palette Manage Agents (`Ctrl+P`)	Same modal

This is not the assistant dashboard (/dashboard / Ctrl+\), which lists live top-level sessions.

Assistant definition files live in .matcha/agents/ or ~/.matcha/agents/. Personas live in config.toml ([subagents.personas]) or .toml files:

.matcha/personas/*.toml (project)
~/.matcha/personas/*.toml (user)
Bundled personas (lowest priority; read-only)

Inline config.toml personas win over files. The file stem is the persona name. The main assistant does not pass a persona name into spawn_subagent; Matcha applies personas through sub-assistant resolution and roles.

Built-in assistant types

The child is always an assistant type (subagent_type on spawn_subagent):

Type	Role
`general-purpose`	Default. Full toolset.
`explore`	Search, read, grep, shell; no file edits.
`plan`	Explore and write a plan; no file edits.

Project or user assistants can add types or shadow these names.

Disable locally

Sub-assistants are on by default.

export MATCHA_SUBAGENTS=0

# ~/.matcha/config.toml
[subagents]
enabled = false

--no-subagents on the CLI also turns spawning off. GROK_SUBAGENTS is the compatibility alias.

Per-type toggles and model overrides:

[subagents.toggle]
plan = false

[subagents.models]
explore = "grok-build"

Without a per-type model, the child inherits the parent's model.

How the parent spawns a child

The main assistant calls spawn_subagent. Typical fields:

Parameter	Meaning
`prompt` / `description`	Task text and a short label
`subagent_type`	Defaults to `general-purpose`
`background`	Return a sub-assistant id immediately
`capability_mode`	`read-only`, `read-write`, `execute`, or `all`
`isolation`	`none` (shared workspace, default) or `worktree`
`resume_from`	Continue a completed child of this session, same type
`cwd`	Working directory; not with `isolation: worktree`

Background children: collect output with get_command_or_subagent_output. Capability mode, if omitted, is the type's own toolset (explore / plan already cannot edit).

Isolation worktree gives the child its own checkout; the result includes the worktree path. Apply or remove through Matcha's git worktree operations (same family as matcha worktree).

Personas may set instructions, instructions_file, description, inputs / outputs, optional model and reasoning_effort, and default_isolation (none or worktree). A missing or unreadable persona fails the spawn.

Watch children in the TUI

Scrollback: a lifecycle block (Subagent running / started / completed). Enter or Ctrl-F opens the child's transcript in a framed, mostly observational view (q / Esc to return).
**Tasks pane** (Ctrl+G): group **Subagents**, with inspect/kill.
/tasks commits the same snapshot as a system block (works in minimal, which has no pane). See Background tasks, queue, and loops.

A child cannot call spawn_subagent. Depth is one.

Not in this build

Do not expect a downloaded remote sub-assistant pack or a cloud chat-modes catalog. Define assistants and personas on this machine. Cloud Agent (cloud_agent) is also disabled — a sub-assistant is a local child, not a remote VM.