Bolt treats every AI persona as a named agent: a system prompt paired with a precisely scoped set of tool permissions. Rather than running one general-purpose model for every task, you pick the agent whose access and focus matches what you need — whether that is auditing security, writing docs, or wiring up a full framework migration.
Access levels
Every built-in agent is assigned one of three access tiers that determine which tools it can invoke:
Built-in agents
Bolt ships ten specialised agents out of the box. Switch between them in the TUI by pressing Tab.
Subagents
In addition to the ten primary agents, Bolt exposes two built-in subagents that primary agents can delegate work to during a session. You never select a subagent manually — they are dispatched automatically when a primary agent decides to spawn one.
When you need to understand an unfamiliar codebase quickly, start with the ask or plan agent. Behind the scenes they can dispatch the @explore subagent to index your project at high speed before producing an answer — without touching a single file.
Switching agents
In the TUI — press Tab to cycle through the list of available agents at any time during a session. The active agent is shown in the session footer.
Non-interactively — pass --agent <name> to bolt run to pin a specific agent for the duration of that run:
Listing agents
To see all available agents — both built-in and custom — with their modes and permission configuration:
Custom agents
You can create your own agents in two ways.
Generate with bolt agent create
The interactive wizard generates an agent file using an LLM and writes it to disk:
All flags are optional. Provide them to run non-interactively:
Write a markdown file manually
An agent is just a markdown file with YAML frontmatter. Place it in .bolt/agents/ inside your project or in the global agents directory:
The filename (without .md) becomes the agent’s identifier.
Available permissions
Permissions are the fine-grained tool gates you control when creating a custom agent:
