agent-persona catalog resource

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.). When structured fields are present, they are the source of truth and any content in the request is ignored — the server re-renders content from the structured fields on every write. Provide content alone to author the persona as Markdown.

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). Parsed into the structured fields when it is the only input; ignored (and re-rendered) when structured fields are present. 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 for agents spawned with this persona (e.g. `claude-sonnet-4-6`). Overridden by an explicit spawn model or the `murmur.yaml` default; empty falls through to Claude Code’s built-in default — see Model Selection.
`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.

Input formats

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

murmur ls agent-persona

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

Platform-managed agent personas cannot be deleted.

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`	`either prompt or description is required`	The request has structured fields (e.g. `model`) but no `prompt` or `description`. Provide at least one.
`INVALID_ARGUMENT`	`either content or structured fields are required`	The request is empty. Provide `content` (Markdown with frontmatter) or structured fields.
`INVALID_ARGUMENT`	`agent-persona content is server-rendered and cannot be patched`	`content` cannot appear in a patch update mask — patch structured fields (`model`, `prompt`, etc.), or replace the whole resource with `murmur set`.
`INVALID_ARGUMENT`	`parse agent content: ...`	The Markdown frontmatter failed to parse as valid YAML. Check your `---` fences and YAML syntax.

Agent personas — concept overview
Agents — the resources that use personas at spawn time
murmur spawn — CLI command for spawning agents with a persona
murmur set — CLI command for creating and updating catalog resources
murmur get — CLI command for reading catalog resources

Getting Started

Core Concepts

Guides

agent-persona catalog resource

Fields

AgentTask fields

Follow-up overrides

Input formats

Markdown with frontmatter

Structured fields

Examples

Creating an agent persona

Listing agent personas

Reading a single agent persona

Spawning an agent with a persona

Tasks with activation conditions

Overriding follow-up instructions

Deleting an agent persona

Errors

​Fields

​AgentTask fields

​Follow-up overrides

​Input formats

​Markdown with frontmatter

​Structured fields

​Examples

​Creating an agent persona

​Listing agent personas

​Reading a single agent persona

​Spawning an agent with a persona

​Tasks with activation conditions

​Overriding follow-up instructions

​Deleting an agent persona

​Errors

​Related

Fields

AgentTask fields

Follow-up overrides

Input formats

Markdown with frontmatter

Structured fields

Examples

Creating an agent persona

Listing agent personas

Reading a single agent persona

Spawning an agent with a persona

Tasks with activation conditions

Overriding follow-up instructions

Deleting an agent persona

Errors

Related