Grok Build Subagents: What They Are and How to Use Them

Q: Can a subagent edit my files?

A general-purpose subagent can. explore and plan can't. Use worktree isolation when several helpers change files.

Q: How many levels of subagents can I have?

One. Subagents can't start their own subagents. Swarm School is an independent site. We're not affiliated with xAI.

Short answer

Subagents are helper sessions that Grok Build, xAI’s coding agent, starts to handle one part of a task in their own separate context. When a subagent finishes, it hands a summary back to the main session. They’re on by default. You can ask for them in plain words, or use the built-in explore and plan types or your own custom agents.

What Grok Build is

Grok Build is xAI’s coding agent for your terminal. You install it, run grok inside a project folder, and chat with it about your code. It’s separate from Grok Bot, which is for everyday tasks on a cloud computer.

curl -fsSL https://x.ai/cli/install.sh | bash
cd your-project
grok

Why subagents help

Each subagent gets its own context window, so research, tests or reviews don’t fill up the main session’s memory. xAI’s guide suggests them for:

Researching the codebase while the main session keeps working
Running tests in parallel with changes
Reviewing changes before you commit
Independent tasks that don’t depend on each other

Skip them for simple tasks, work that needs back-and-forth with you, or jobs where explaining the task costs more than it saves.

The built-in types

Type	What it does
`general-purpose`	The default. Can do anything the main session can
`explore`	Reads and searches the codebase. Never edits files
`plan`	Explores and writes an implementation plan. Never edits files

How to use them

Just ask. For example: “Use subagents: one to find every caller of parseConfig, one to run the test suite, then summarize both.” The main agent decides when to delegate and starts each child with its spawn_subagent tool.
Watch them work. Press Ctrl+G to open the tasks pane, which lists running and finished subagents. Press Enter on a subagent’s line in the conversation to read its full transcript.
Keep edits apart. For tasks that change files, a subagent can run in an isolated git worktree, so its edits don’t clash with the main session until you merge them.

Make your own subagent

Add a Markdown file to .grok/agents/ in your project (or ~/.grok/agents/ for all projects). It needs a name and a description in the front matter. The body is its instructions.

---
name: migration-reviewer
description: Use when reviewing database migrations
tools: Read, search_tool, use_tool
---

Review migrations for correctness and rollback safety. Report problems with file paths.

Manage agents with /config-agents (or /agents). Run grok inspect to check what Grok found.

Personas are lighter: a tone, focus or output format layered on a subagent without changing its tools. Define them in .grok/personas/*.toml and manage them with /personas.

Limits and switches (as of Oct 2026)

One level deep: only the main session can start subagents. A subagent can’t start its own.
They work on their own: they aren’t built for chatting with you mid-task.
Turn them off for one session with grok --no-subagents, or with GROK_SUBAGENTS=0, or [subagents] enabled = false in ~/.grok/config.toml.
Per-type control: you can switch off a type or send it to a different model in config.
Access: x.ai/pricing lists Grok Build as limited on Free and included from Plus ($8/month) up. In environments without a browser, Grok Build can sign in with an xAI API key. Plans: Grok and Grok Bot pricing.

FAQ

Are Grok Build subagents the same as Grok Bot’s Bots?

No. Subagents are short-lived helpers inside one coding session. Bots are lasting teammates with names, memory and a cloud computer. See Grok agents explained.

Are they the same as the Grok API multi-agent model?

No. That’s a single API model where several agents research one question. See Grok API multi-agent.

Can a subagent edit my files?

A general-purpose subagent can. explore and plan can’t. Use worktree isolation when several helpers change files.

How many levels of subagents can I have?

One. Subagents can’t start their own subagents.

Swarm School is an independent site. We’re not affiliated with xAI.

Sources

Swarm School is independent and not affiliated with Grok Bot’s makers. Features change; check the official docs for current details.

Related guides

Browse bots → All guides →

Grok Build subagents: what they are and how to use them