Agent personas and system prompts
How an agent's persona shapes its sessions, when the system prompt reaches a session, and where to put standing rules.
Every launch config has two optional text fields: a persona and a system prompt. The persona reaches every session your agent runs. The system prompt reaches a session in one case only: an Evaluation attempt that uses that launch config.
Most agents carry a single launch config, so the persona opens every task the agent works on. An agent with more than one launch config can give each config its own persona. See Agents with more than one launch config.
Persona and system prompt
| aspect | Persona | System prompt |
|---|---|---|
| What it is | A short description of this agent’s role and identity | A longer block of text saved on the config |
| Where it appears | At the top of each session brief as “You are: …”. The agent knows its role before it reads the task | Saved on the config. config show and the web app display it. An Evaluation attempt that uses the config puts it in the brief under “Launch config instructions”, right after the “You are:” line. Other sessions do not get it |
| Effect on sessions | Shapes tone, focus area and how the agent describes itself | Only in an Evaluation attempt that uses this config. None in other sessions |
The persona applies to every stage the agent runs, such as plan, code and review. For an agent with more than one launch config, the config that runs a stage supplies that stage’s persona.
When the system prompt reaches a session
You can set a system prompt with --system-prompt or --system-prompt-file, or in the web app. CodeHerder saves it, shows it, and copies it when you copy the agent.
The agent sees the prompt in an Evaluation attempt whose setup names this launch config. Ordinary task sessions and other sessions get the persona only. They do not get the system prompt.
Do not rely on this field for rules the agent must follow in normal work. Use one of the options in Where to put standing rules.
To test a system prompt before you depend on it, compare launch configs in an Evaluation.
Viewing the current config
To see what an agent’s config currently holds, run:
ch agent config show <agent-id>
If the agent has more than one launch config, this shows only the top one. See Agents with more than one launch config. The output lists the config in full: command, args, environment, capabilities, persona and system prompt. It also shows a version number that increases each time the config is updated. A member below workspace owner or admin sees the same output, but with every argument and environment variable value (except some @secret: references) replaced by [redacted]. See Who can manage a launch config.
agent: Builder (a1b2c3d4-...)
harness: claude
command: /usr/local/bin/claude
capabilities: model:sonnet
persona: A senior Go engineer focused on correctness and clear, minimal code.
systemPrompt:
Always write a test before adding production code.
Prefer stdlib over third-party packages.
version: 3
Setting or updating a persona
Use ch agent config edit to store a persona on an agent. Like config show, this always acts on the agent’s top launch config:
ch agent config edit <agent-id> \
--persona "A senior Go engineer focused on correctness and clear, minimal code."
To read a longer persona from a file, use --persona-file:
ch agent config edit <agent-id> --persona-file persona.txt
Pass --persona-file - to read the persona from standard input.
The command, args, environment and capabilities stay exactly as they were. See What each edit actually changes.
What config edit changes
config edit is a partial update. It changes only the fields whose flag you pass and leaves everything else as stored.
The exception is a set of repeatable flags: --arg, --env, --cap, --credential-ref and --allowed-model. Each one replaces its field’s whole list when you pass it at all. If you set a persona in the same call as --arg, include every argument you want to keep.
To clear a persona, pass an empty string explicitly:
ch agent config edit <agent-id> --persona ""
Agents with more than one launch config
An agent can carry an ordered list of launch configs rather than just one. You might use this to run different coding-agent CLIs for different stages, or to keep a fallback config in reserve. Each launch config has its own persona, so the stages that run under different configs can present the agent differently.
ch agent config show and ch agent config edit always read and write the top config, which is the first one in the list. Running config edit --persona "..." on a multi-config agent updates only that top config. Every other config is untouched.
To give a persona to a config other than the top one:
- Set it when you create the config:
ch agent config create <agent-id> --harness <harness> --cap <capability> --persona "...". - Or edit the config from the Launch configs panel on the agent’s detail page in the web app. The panel has a Persona field.
You can also set the top config’s persona when you create the agent: ch agent create --harness <h> --config-cap <capability> --persona "...". See Creating a runnable agent in one call for the full flag set.
Reordering, enabling or disabling configs controls which config, and so which persona, runs a given stage. See Agents and the CLI for the commands and for how CodeHerder picks the config that runs a stage.
Who can change these
Setting a persona goes through ch agent config edit or ch agent config create. Both need workspace owner or admin. See Who can manage a launch config for the full permission split. Agents cannot change their own configs.
Writing a good persona
A persona works best when it is:
- Short. One or two sentences is ideal. The persona opens every session brief, and a long paragraph adds noise rather than focus.
- Role-focused. Say what kind of work this agent does and what it values. Skip the biography.
- Concrete. “A backend engineer who writes Go and prioritises correctness” is more useful than “A helpful coding assistant”.
- Written to follow “You are:”. The brief starts with “You are: “ and then your text, so write a role, not a command.
Examples:
A senior Go engineer who values correctness, minimal surface area, and thorough test coverage.
A frontend engineer specialising in React and TypeScript, focused on accessible, performant UIs.
A careful code reviewer who looks for correctness bugs, security issues, and clarity improvements.
Where to put standing rules
A standing rule is something that should hold on every task, such as a coding standard or a rule about what to commit. These places reach your agents:
- The repository’s instruction file. Put the rules in
CLAUDE.mdorAGENTS.mdat the root of the repository. The coding-agent CLI loads that file in every session. See Agents and the CLI. - Skills. A skill packages reusable instructions that agents can use across your workspace. You can also attach skills to a single stage. See Skills and Stage skills.
- Stage prompts. If a rule applies to one kind of work, such as review, put it in that stage’s instructions. See Stage library.
- Per-agent wiki pages. Pages in the
template_personascope belong to one agent. The agent’s brief lists them in its page index. See Workspace wiki. - The persona. Use it for a short role statement, not for a list of rules.
Tips:
- Keep rules specific and limited to things the agent might otherwise get wrong.
- Review them after a few tasks. If a rule keeps being ignored, make it more specific. If it never comes up, remove it.
To set up the rest of an agent’s launch config, such as the command, capabilities and environment variables, see Agents and the CLI. To see how capabilities route tasks to the right agent, see Capabilities. To watch a running agent, see Monitoring your agents.
Last updated