Quick answer
SpaceXAI added Workflows to Grok Build on July 23, 2026. A workflow is an orchestration script that Grok creates from a natural-language request, runs in phases, fans work out to parallel agents, verifies results, and returns one report in the background.
Use a workflow only when the job has three properties:
- It can be split into many independent units.
- Every unit can return a structured result.
- A separate verification phase can reject weak or unsupported findings.
The official release gives a run a budget of 128 agents, with up to 1,024 for large jobs. That is an agent-count ceiling, not a cost guarantee or a reason to use every available slot. Start with the smallest fan-out that covers the work, keep write access narrow, and require evidence before the synthesis phase accepts a result.
Who this guide is for
This guide is for developers evaluating Grok Build Workflows for large pull-request review, issue triage, route-handler security audits, migration inventories, or other repository tasks that exceed one conversation.
Grok Build is the coding-agent harness and terminal product. Grok 4.5 is the model that currently powers it and is also available through the xAI API. Keep harness rollout separate from model evaluation; use the Grok 4.5 coding-agent evaluation for model, context, tool, and price decisions.
What changed
Grok Build can now generate and run a multi-phase workflow from a plain-language task. Each agent starts with a clean, focused context. Completed progress is saved, so pausing and resuming does not redo finished work. The /workflows view shows phases, agents, and per-agent token counts.
Successful workflows can be saved in two scopes:
| Path | Scope | Best use |
|---|---|---|
.grok/workflows/ |
Repository and team | A reviewed workflow tied to one codebase |
~/.grok/workflows/ |
Personal | A reusable workflow that follows one developer |
Each saved workflow becomes a slash command with arguments. Grok authors and smoke-checks the script; you do not have to write it manually.
Do not confuse this with Grok Automations. Automations run a recurring or email-triggered assistant job. Grok Build Workflows orchestrate many agents inside one complex build or review run.
Choose the right execution shape
Use the smallest shape that can finish the task:
| Work shape | Choose | Why |
|---|---|---|
| One file, one bug, one clear test | Single session | Coordination overhead adds no value |
| Two to six related investigations | Ordinary subagents | The parent can still integrate the result directly |
| Dozens of independent files, issues, or features plus a common verifier | Workflow | Parallel coverage and staged synthesis are useful |
| Scheduled inbox, research, or reminder task | Automation | The trigger matters more than repository fan-out |
A workflow is a poor fit when every worker must edit the same files, when acceptance is subjective, or when no independent check can tell a real finding from a plausible one. In those cases, use a single plan or a smaller set of isolated subagents.
Design four explicit phases
A useful default is Context → Work → Verify → Synthesize.
- Context: build the authoritative inventory once. Record the base commit, file or issue list, exclusions, and acceptance rules.
- Work: assign non-overlapping units. Require each worker to return an ID, evidence location, conclusion, confidence, and proposed check.
- Verify: give fresh agents the original evidence, not just the worker's summary. Reject duplicates, missing locations, and claims that fail a test or reproduction.
- Synthesize: rank only verified results, explain coverage and omissions, and produce one action list.
For a route authorization audit, the request can be:
Create and run a workflow to audit every HTTP route for missing authorization.
Context:
- Inventory route handlers from the current commit.
- Exclude generated and test fixtures.
Work:
- Assign each route to exactly one reviewer.
- Return route, file and line, required identity, observed guard, and a reproduction idea.
Verify:
- Independently reproduce every high-severity finding.
- Reject any finding without a precise location and request path.
Synthesize:
- Report verified findings by severity.
- Include coverage, rejected findings, and routes that could not be evaluated.
- Do not modify files or open pull requests.
This contract is the original increment: it makes coverage, evidence, independent rejection, and side-effect boundaries visible before a large fan-out begins.
Budget the fan-out
Do not begin at 128 agents. Estimate the useful roles:
inventory_agents: 1
worker_agents: 12
verification_agents: 3
synthesis_agents: 1
maximum_total_agents: 20
write_access: none
stop_if_inventory_changes: true
stop_if_verifier_cannot_reproduce: true
These values are an example, not a Grok default. Increase the worker count only when units are genuinely independent. Increase verification capacity when findings are high risk or expensive to reverse. If ten agents inspect the same surface, that is usually duplication, not coverage.
Use the per-agent token counts as an observability signal. A worker consuming far more context than peers may have received an oversized unit, entered a loop, or lacked a usable stopping condition.
Lock permissions before scaling
Run grok inspect before the first workflow to see which instructions, skills, plugins, hooks, and MCP servers the directory loads. Grok Build's permission documentation distinguishes approval from sandboxing: permission decides whether a tool call may run, while the sandbox limits what an approved call can reach.
For the first canary:
- Keep Ask mode for actions not explicitly allowed.
- Add explicit deny rules for destructive shell and remote publish commands.
- Use a sandbox profile that limits filesystem and network access.
- Keep worker phases read-only where possible.
- Reserve edits for a later, separately reviewed run.
Deny rules take precedence over allow rules. Avoid Always-approve for an unproven workflow: multiplying agents also multiplies the blast radius of a mistaken permission policy. If the repository is not trusted, apply the AI coding-agent sandbox checklist before starting Grok Build.
Run a six-case canary
| Case | Test | Pass condition |
|---|---|---|
| Partition | Use a 20-item inventory | Every item has one owner; none are missing or duplicated |
| Evidence | Seed one known issue | The worker returns the exact location and reproduction |
| Skeptic | Seed one plausible false positive | The verification phase rejects it |
| Pause/resume | Pause after one phase, then resume | Completed units are not rerun |
| Permission | Ask a worker to attempt a denied action | The action is blocked and visible in the run evidence |
| Partial failure | Make one unit unreadable | Synthesis reports the gap instead of claiming full coverage |
Promote the workflow only when its report states the base revision, coverage denominator, verified findings, rejected findings, unresolved units, agent count, and permission mode. For coding changes, keep deterministic tests and human review as the final gate. The workflow report is evidence, not merge approval.
Common mistakes
- Using a workflow for a small sequential task.
- Treating the 128-agent budget as a target.
- Letting multiple workers edit the same checkout or files.
- Asking the synthesis phase to trust worker summaries without fresh verification.
- Saving a generated workflow to the repository before reviewing its scope and side effects.
- Using Always-approve because the run happens in the background.
- Reporting success without a coverage denominator or unresolved-item list.
FAQ
Does a workflow replace ordinary subagents?
No. Ordinary subagents are better for a few related investigations. A workflow adds explicit phases, larger fan-out, resumable progress, verification, and reusable commands for much larger tasks.
Is the 128-agent budget a token or spending limit?
No. The announcement describes an agent budget and exposes per-agent token counts. Treat provider usage and financial limits as separate controls.
Should a team commit .grok/workflows/?
Only after reviewing the generated workflow against repository rules, permissions, acceptance criteria, and a canary result. The repository scope makes it shareable; it does not make it safe by default.
Top comments (0)