An agent persona is a catalog resource that defines a reusable template for agents. When you spawn an agent with --agent=<name>, it inherits the persona’s system prompt, model, tool configuration, and default tasks.
Agent personas are tenant-scoped. Platform-managed agent personas exist in every tenant. Custom agent personas are authored via murmur set agent-persona.
An agent persona accepts input in two formats: a Markdown file with YAML frontmatter (the content field), or individual structured fields (description, prompt, model, etc.). The two formats are mutually exclusive on write — provide one or the other, not both.
Fields
| Name | Type | Required | Description |
|---|
name | string | yes | Unique identifier within the tenant. DNS label format: [a-z][a-z0-9-]{0,62}. Also accepts workspace-scoped names: {workspace}/{name}. |
content | string | no | Full Markdown file (YAML frontmatter + body). Mutually exclusive with structured fields. The server parses this into the structured fields on write. Read responses always include the server-rendered content. |
description | string | no | Short description of the persona’s role. Maximum 1024 bytes. Shown in murmur ls agent-persona output. |
prompt | string | no | The agent’s system prompt — the Markdown body after frontmatter. Stored verbatim. |
model | string | no | Model override (e.g. claude-sonnet-4-6). Empty uses the platform default. |
tools | string[] | no | Allowed MCP tools the agent may use. |
disallowed_tools | string[] | no | MCP tools the agent may not use. |
max_turns | int32 | no | Maximum conversation turns. 0 means unlimited. |
tasks | AgentTask[] | no | Default tasks seeded into the agent’s checklist on spawn. |
follow_up_overrides | FollowUpOverride[] | no | Per-event-class overrides for the instructions and tasks an event generates. Authored as the followups: frontmatter map. See follow-up overrides below. |
AgentTask fields
Each entry in the tasks list has:
| Name | Type | Required | Description |
|---|
subject | string | yes | Task summary (e.g. “Run Go tests”). |
activate_when | object | no | Activation condition. Omit for tasks that are always active. |
activate_when.files_modified.pattern | string | no | Glob pattern for file paths. The task activates when the agent pushes changes matching this pattern. Empty matches any file. |
Follow-up overrides
When an event wakes an agent — a PR comment, a PR review, a CI result — Murmur delivers two things: the content (the platform-formatted facts: who, where, the comment body, the exact gh commands) and the instructions (the prose telling the agent what to do about them). A persona can override the instructions and the checklist tasks for a given event class. The content is always platform-formatted, so you never re-derive event formatting.
Author overrides as the followups: frontmatter map, keyed by event class. At most one override per class.
| Event class | Fires on |
|---|
pr_comment | A comment on the agent’s PR |
pr_review | A review on the agent’s PR |
ci_result | A CI run completing |
pr_merged | The agent’s PR being merged |
Each override has:
| Name | Type | Required | Description |
|---|
instructions | string | no | Plain text replacing the default instruction prose for this class, delivered after the platform-formatted content. Not a template — no variables, no escaping. Omit to keep the default instructions; a present-but-empty value is rejected. |
tasks | object[] | no | The exact tasks this class’s follow-ups generate, replacing the platform defaults wholesale. Each task has a subject (required) and an optional description. An override that lists no tasks generates none. |
Declaring an override for a class replaces that class’s default tasks entirely. Classes with no override keep their default instructions and tasks.
Markdown with frontmatter
Pipe a Markdown file where the YAML frontmatter contains the structured fields and the body is the system prompt.
cat <<'EOF' | murmur set agent-persona payments-reviewer
---
description: Domain-specific reviewer for payments code
model: claude-sonnet-4-6
tools:
- Bash
- Read
- Grep
disallowedTools:
- Edit
maxTurns: 50
tasks:
- Check idempotency keys in retry paths
- subject: "Verify minor-unit money representation"
activate_when:
files_modified: "*.go"
---
You are reviewing changes to the payments service. Read every changed file
end-to-end before forming an opinion. Money values must always be in minor
units (cents), never floats.
EOF
Frontmatter keys use camelCase: disallowedTools, maxTurns. This matches the format that the server renders on read.
Structured fields
Post individual fields as YAML. The prompt field carries the system prompt directly.
cat <<'EOF' | murmur set agent-persona payments-reviewer
name: payments-reviewer
description: Domain-specific reviewer for payments code
model: claude-sonnet-4-6
prompt: |
You are reviewing changes to the payments service. Read every changed file
end-to-end before forming an opinion.
EOF
Do not combine content with structured fields (description, prompt, model, etc.) in the same request. The server rejects requests that provide both.
Examples
Creating an agent persona
cat <<'EOF' | murmur set agent-persona code-reviewer
---
description: Thorough code reviewer
model: claude-sonnet-4-6
tools:
- Read
- Grep
- Bash
---
Review the PR diff. Check for correctness, test coverage, and style
consistency. Output a numbered list of findings with file:line citations.
EOF
Listing agent personas
code-reviewer Thorough code reviewer
programmer [platform] Mythical programmer obsessed with code quality
architect [platform] Designs systems and writes proposals
Platform-managed agent personas are marked [platform].
Reading a single agent persona
murmur get agent-persona code-reviewer
The response is the server-rendered Markdown — YAML frontmatter followed by the system prompt body.
Spawning an agent with a persona
murmur spawn --agent=code-reviewer review-pr-42 "Review PR #42"
The agent inherits the agent persona’s prompt, model, tools, and default tasks.
Tasks with activation conditions
tasks:
- Run the full test suite
- subject: "Check Go formatting"
activate_when:
files_modified: "*.go"
Plain strings become tasks that are always active. Structured entries with activate_when activate only when the agent pushes changes matching the glob pattern.
Overriding follow-up instructions
cat <<'EOF' | murmur set agent-persona payments-reviewer
---
description: Domain-specific reviewer for payments code
followups:
pr_comment:
instructions: |
Treat every comment as blocking until you have addressed it or
explained why it does not apply. Re-run the payments test suite
before replying.
tasks:
- subject: "Re-run payments tests after addressing the comment"
ci_result:
instructions: |
If CI failed, reproduce the failure locally before pushing a fix.
---
You are reviewing changes to the payments service.
EOF
A pr_comment follow-up now delivers the platform-formatted comment, then these instructions, and seeds the one listed task instead of the default. pr_review has no override, so it keeps its default instructions and tasks.
Deleting an agent persona
murmur rm agent-persona code-reviewer
Errors
| Code | Meaning | What to do |
|---|
INVALID_ARGUMENT | name is required | Provide a name field or pass the name as the CLI argument. |
INVALID_ARGUMENT | agent persona name must be a DNS label or {workspace}/{name} | The name must match [a-z][a-z0-9-]{0,62} or {workspace}/{name} where both segments match that pattern. |
INVALID_ARGUMENT | description exceeds 1024 byte limit (N bytes) | Shorten the description field to 1024 bytes or fewer. |
INVALID_ARGUMENT | content and structured fields are mutually exclusive | Provide either content (Markdown with frontmatter) or structured fields (description, prompt, etc.) — not both. |
INVALID_ARGUMENT | either content or structured fields are required | The request has no content and no prompt or description. Provide at least one. |
INVALID_ARGUMENT | parse agent content: ... | The Markdown frontmatter failed to parse as valid YAML. Check your --- fences and YAML syntax. |