Concepts
Roles
On this page
A role is a saved agent configuration that you can reuse in chats and crews. It describes how an agent should work; starting it creates a separate session.
What a role stores
| Setting | Purpose |
|---|---|
| Name and handle | A readable name and a unique identifier such as coder |
| Agent runtime | The CLI to run, such as Codex or Claude Code |
| Model and effort | Optional choices supported by that runtime; otherwise its defaults apply |
| Speed | Codex's inherited, standard or fast service tier |
| System prompt | The role's responsibilities and working style |
| Working directory | A default folder when the launch does not supply one |
| Command, arguments and environment | How the agent process is launched |
Create and edit roles from Roles. A role's system prompt should describe its job, such as “review the diff and report defects without editing files.” Put a particular task in a chat prompt or mission goal so the role remains reusable.
Roles in chats and crews
In Start a chat → Role, choosing a role copies its settings into the launch. Changes in that dialog apply to that chat; they do not rewrite the saved role. Direct starts an agent without needing a role.
A crew slot references a role and gives it an in-crew handle. The same role can fill several slots, each with a different handle. A slot can override the runtime, model, effort and Codex speed. Changing the runtime resets engine-specific settings to the new runtime's defaults before its overrides are applied.
Editing a role does not type instructions into an already-running terminal. Use a message for an immediate instruction, and review the launch settings when starting new work.
See Build a crew for a complete coder/reviewer example and CLI reference for role commands.