Personas define reusable roles that customize how you interact with agents. Instead of selecting an agent directly, you select a persona — a named configuration that bundles a preferred agent, custom instructions, per-agent config options, and MCP servers into a single selectable profile.
Examples of personas include "Frontend Engineer", "Backend Engineer", "CEO", or "Technical Writer" — each with tailored instructions and tool configurations for that role.
| Field | Required | Description |
|---|---|---|
| Name | Yes | A display name for the persona (e.g., "Frontend Engineer") |
| Description | No | A brief summary of the persona's purpose |
| Instructions | No | Custom text prepended to the agent's first prompt in each session |
| Preferred Agent | Yes | The agent to use when this persona is selected |
| Fallback Agents | No | Alternative agents to use if the preferred agent is not running |
| Agent Config Options | No | Per-agent configuration (e.g., bypass permissions, model selection) |
| MCP Servers | No | Tool servers the agent can use during the session |
The Instructions field is a free-text area where you can define the persona's behavior. Instructions are automatically prepended to the first prompt in every session that uses this persona. They are wrapped in <persona-instructions> tags so the agent can distinguish them from user input.
Instructions are only sent once — on the initial prompt of each session. Subsequent prompts in the same session do not include the persona instructions, since agents maintain context across the conversation.
Example instructions for a "Frontend Engineer" persona:
You are a frontend engineer specializing in React, TypeScript, and CSS.
Focus on component architecture, accessibility, and performance.
Prefer functional components with hooks over class components.
Use CSS modules or inline styles — avoid CSS-in-JS libraries.
When you select a preferred or fallback agent, Braide probes the agent to discover its available configuration options. These appear as toggles and dropdowns below the agent selector.
Config options set on a persona are applied automatically when a session is created with that persona. This lets you pre-configure settings like "Bypass Permissions" or model selection per persona, so each role starts with the right configuration.
If the agent is not running when you edit the persona, config options cannot be probed. You can still save the persona and configure options later.
As soon as at least one persona is defined, personas are the sole source of truth for per-agent capability defaults — changing config options in the New Session view does not write back to the project, because the persona is expected to own that configuration. If you want to change defaults, edit the persona here. When no personas are defined the project falls back to remembering per-agent choices at the project level; see Remembered Capability Choices in the Running a Session guide for how that works.
Personas can include MCP (Model Context Protocol) servers — external tool servers that extend the agent's capabilities during a session. MCP servers are passed to the agent when the session is created.
For stdio servers:
| Field | Description | Example |
|---|---|---|
| Command | The executable to run | npx, uvx, node |
| Args | Space-separated arguments | -y @some/mcp-server --port 3000 |
| Env | Environment variables (name=value pairs) | API_KEY=sk-123 |
For http servers:
| Field | Description | Example |
|---|---|---|
| URL | The server endpoint | http://localhost:8080/mcp |
To add a time server MCP that lets the agent check the current time:
Server-Timeuvxmcp-server-timeIf the preferred agent is not running when you try to start a session, Braide shows a warning in the persona selector. If fallback agents are configured and any of them are running, they are offered as alternatives.
Selecting a fallback agent for a session is temporary — it does not modify the persona's preferred agent setting. The next session will attempt to use the preferred agent again.
By default — before you create any personas — new sessions use agent selection mode: the prompt input toolbar shows an agent dropdown and you choose an agent directly for each session.
As soon as a project has one or more personas configured, the toolbar switches to persona selection mode: the persona selector appears in place of the agent dropdown and you choose a persona instead. Deleting all personas returns the project to agent selection mode.
The persona selector shows:
When you select a persona:
The active persona is shown as a pill badge in the session header alongside the session ID.
In the session sidebar, each session's subtitle shows the persona's name in place of the agent name for sessions created with a persona. Sessions created without a persona — either because the project had no personas at the time, or because No persona was selected — continue to show the agent name. If a session references a persona that has since been deleted, the subtitle falls back to showing the agent recorded on the session.
Even when a project has personas configured, you may want a one-off session that doesn't use any of them — for example to try a different agent, skip persona instructions, or test a raw agent interaction. The persona selector's No persona option gives you that escape hatch without deleting any persona definitions.
Selecting No persona:
To return to a persona, open the persona selector again and pick any persona — the agent selector disappears and the chosen persona's preferred agent takes over.
The No persona choice is remembered across page reloads. Each time you open the New Session view, Braide restores the last persona state for that project: if you last picked a persona, it's reselected; if you last picked No persona, the agent selector reappears pre-seeded with the agent you last used in that mode. The persona selector still shows every persona — you can switch back at any time by picking one.
Once the first prompt has been sent the persona and agent selectors lock (same as for any persona-based session), so opting out with No persona is a decision you make at session creation time, not something you can toggle mid-conversation.
Braide persists your persona and agent choices per project, with two distinct defaults:
activePersonaId) — the last persona you chose, or the sentinel value No persona if you explicitly opted out. Set whenever you pick from the persona dropdown (including No persona). Not touched when you're in persona mode and the session is auto-created from the persona's preferred agent — picking a persona never overwrites the no-persona default.selectedAgentId) — the last agent you picked directly, either because the project has no personas configured or because you explicitly chose No persona. Updated only in those flows; selecting a persona leaves this pref untouched so the no-persona default stays stable.On the next New Session view, the two prefs combine as follows:
| Persisted state | What you see |
|---|---|
| Persona X | Persona X auto-selected; session created with persona X's preferred (or fallback) running agent. The persisted default agent is ignored. |
| No persona + agent Y | Agent selector shown with Y pre-selected; session auto-created for Y. |
| No persona, no agent yet | Agent selector shown, glowing for selection. |
| Never chosen (new project) | Persona selector glowing for selection if personas are configured, otherwise the agent selector. |
If the persisted agent (for the No-persona flow) or the persona's preferred agent has been disabled since last use, the toolbar falls back to the Select… invitation instead of auto-creating a session. In persona mode the persona's fallback agents (if any are running) are tried before the invitation is shown.
Persona configurations are stored in the project's settings.json file alongside other project preferences:
~/.braide/projects/<project-id>/settings.json
Personas are project-scoped — each project has its own set of personas.