Roles
The eight built-in worker roles, their tool restrictions, and how to define custom roles.
A role is a named bundle of {systemPrompt, allowedTools, disallowedTools, model, mcpServers, permissionMode, browserAccess, writePathPrefixes, backend} that the master applies when it spawns a worker. Roles let an orchestrator pick the right shape of worker for the job — a QA worker that cannot edit files, a security auditor that only reports findings, a browser_qa worker scoped to writing recordings.
Built-in roles
Agent Grid ships with eight built-in roles. Every Claude pane is master-capable by default and can spawn workers in any of these roles via MCP spawn_role.
| Role | Scope | Tool restrictions | Default backend |
|---|---|---|---|
builder | Implement features following project patterns. Full read/write. | None | SDK |
qa | Review staged or uncommitted changes and give a verdict. No code changes. | Write, Edit disallowed | SDK |
validator | Compare staged changes against the original spec; flag misses and deviations. No code changes. | Write, Edit disallowed | SDK |
backend | Server-side code only. Full read/write. | None | SDK |
frontend | UI components, client-side code, styling. Full read/write. | None | SDK |
devops | CI/CD, deploy configs, infra, Docker, build tooling. Full read/write. | None | SDK |
security | OWASP-style audit. Reports findings only — no changes. | Write, Edit disallowed | SDK |
browser_qa | Visual end-to-end QA driving a real browser pane (Playwright MCP + the agent-grid browser MCP). | Edit disallowed; browserAccess: true; writePathPrefixes: ['.agent-grid/qa-specs/'] | SDK (pinned) |
There is no built-in pr role. If a project defines a pr role in .agent-grid/roles.json it exists for that project only. Don't rely on a pr role being present out of the box.
Backend selection: SDK vs PTY
Each role declares a default backend:
sdk— the standard programmatic path through@anthropic-ai/claude-agent-sdk. Required for any role that wires MCP servers, because the PTY backend can't pipe MCP servers into the interactive CLI.pty— drives theclaudeCLI under a headless PTY. Routes usage to the Max subscription quota.
browser_qa is pinned to SDK because it depends on the Playwright MCP and the agent-grid browser MCP. Other roles can override the backend via project configuration.
writePathPrefixes is advisory
writePathPrefixes declares the only paths a role should write to (for example browser_qa is contracted to write only under .agent-grid/qa-specs/). The setting is advisory, not enforced by the SDK. The orchestrator can audit a worker's writes after the fact, but nothing in the runtime blocks an out-of-bounds write.
Treat writePathPrefixes as a documented role contract, and pair it with a reviewing role (qa, validator, security) if you need a stronger boundary.
Custom roles via .agent-grid/roles.json
A project can extend or override the built-in roles by adding .agent-grid/roles.json to its repository root. Definitions in that file are merged over the built-ins; you can add brand-new roles or tweak the prompt and tool list of an existing one. See The .agent-grid/ folder for the convention.
Here's a worked example of a custom pr role — remember pr is not built in, so this only exists in projects that define it themselves:
{
"pr": {
"systemPrompt": "Open a pull request from the current branch...",
"allowedTools": ["Read", "Bash"],
"disallowedTools": ["Write", "Edit"],
"backend": "sdk"
}
}The example above is illustrative — confirm the exact schema against electron/workers/roles.ts in the repo before shipping a custom role.
Related
- Spawn menu — how Claude / Codex panes get on the canvas in the first place.
- Keyboard shortcuts — driving panes and the canvas from the keyboard.