Use Grok Build subagents for parallel child sessions

A subagent is an independent child session with its own context. When it finishes, it returns a summary to the parent. Official Build docs enable subagents by default when the setting is unset.

Built-in types

Type	Role
general-purpose	Default full-capability child
explore	Read, list, and search only — no shell, no edits
plan	Drafts an implementation plan — no shell, no edits

Use explore when you want a map of the tree without writes. Use plan when you want a draft plan from a child while the parent stays focused. Use general-purpose for a full-capability handoff that can edit and run shell.

Turn the feature on or off

Environment and config switches live in the settings reference:

• Env: GROK_SUBAGENTS=1 enables the task tool; 0 disables it.
• User config: [subagents] enabled = true (or false).
• Per-type: [subagents.toggle] maps type name → bool.
• Per-type models: [subagents.models] maps type name → model id.

[subagents]
enabled = true

[subagents.toggle]
explore = true
plan = true

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

Leave the setting unset to keep the default-on behavior described in the Subagents feature page. After you change config, run grok inspect from the project root to confirm what Grok discovered for agents and skills.

Add custom agents and personas

Drop agent definitions under .grok/agents/ (project) or ~/.grok/agents/ (user) to add or override types. Manage agents and personas in the TUI with /config-agents (alias /agents) or /personas.

Personas are behavioral overlays only — tone, focus, and contracts. Define them under [subagents.personas] in config, or as files in .grok/personas/*.toml / ~/.grok/personas/*.toml. A persona changes how the child writes and prioritizes; it does not add shell or edit tools to an explore or plan child.

How they fit the rest of Build

Child sessions inherit the parent’s ask / auto / always-approve permission mode; see Configure Grok Build permissions. Pair planning children with Plan Mode when you want the parent review UI. Repo rules still come from AGENTS.md. Plugins can ship extra agent types — see Use skills and plugins in Grok Build.

Pitfalls

• explore and plan children cannot run shell or edit tools — pick general-purpose when the child must change files.
• Personas do not add tools; they only change behavior overlays.
• Install the CLI first: Install the Grok Build CLI.