Roles

A role is a named preset for sessions. Instead of re-specifying the agent, the system prompt, and the config every time you want, say, a code reviewer, you define a role once and apply it by name.

What a role bundles

Roles are declared in settings.kdl. A role can set:

• agent — which agent the session runs (claude or codex).
• prompt — the session's system prompt: its identity and behavioural guidance.
• description — a one-line summary, shown when roles are listed.
• use-subscription — whether to use subscription auth instead of an API key.
• config — default agent config keys for sessions of this role.

role "reviewer" {
    agent "claude"
    description "Careful code reviewer"
    prompt "You are a meticulous reviewer. Read the diff, flag real bugs and \
            risks, and report findings concisely. Do not rewrite code unless asked."
}

prompt is identity, not a task

The role's prompt is the session's system prompt — who it is — not the work it does. The task comes separately, as the prompt you pass when you start the session. They coexist:

actor new auth-review --role reviewer --prompt "Review src/auth/ for security issues."

Here the role supplies the reviewer identity and --prompt supplies the job.

The built-in main role

One role ships built in: main, the identity that actor claude gives your main session. It's what makes main coordinate sessions and manage by exception (see the main session). You don't have to declare it — it's always there as the lowest config layer.

You can override it, though. Roles merge by whole-role replacement, with no special case for main, so declaring a role "main" in your settings.kdl replaces the built-in one outright — its system prompt, agent, and config. That's how you customise the orchestrator (e.g. a tighter prompt, or pinning it to a specific model). As with any role, a project's .actor/settings.kdl wins over your user file, which wins over the built-in.

Discovering and applying roles

List what's defined:

actor roles

Apply a role when creating a session with --role <name> on the CLI, or role: "<name>" from the new_session tool. If no roles are defined, sessions run with the agent defaults.

Precedence

A role is one layer in the config merge. Explicit values you pass — a CLI --agent, a --prompt, individual config keys — win over the role's defaults, while the role's system prompt still applies (it's a different field from the task). The full ordering is in Actor Settings.