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 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. The server ignores any content in the request and re-renders content from the structured fields on every write. Provide content alone to author the persona as Markdown.

Fields

Name	Type	Required	Description
`workspace_use`	object	no	For tenant-level names, which workspaces may use this resource: `scope` is `WORKSPACE_USE_SCOPE_NONE` (default), `WORKSPACE_USE_SCOPE_ALL`, or `WORKSPACE_USE_SCOPE_SELECTED` with a `workspaces` list. Scoped names carry no policy and are usable only in their own workspace. See resource admission.
`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 get agent-persona` list output.
`category`	string	no	Display category grouping this persona in picker UIs. Empty means Other.
`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.
`disable_autopilot`	boolean	no	When `true`, the first message using this persona turns off autopilot at turn start, whether you spawn a new agent or select the persona on a follow-up, through the CLI or dashboard. The message still runs. Ordinary later messages do not reapply the action. `false` or omission leaves current settings unchanged.
`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, such as a PR comment, PR review, or CI result, wakes an agent, Murmur delivers two things. The content contains platform-formatted facts, including who, where, the comment body, and the exact gh commands. The instructions tell the agent what to do. A persona can override the instructions and checklist tasks for an 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. prompt and content are not frontmatter keys: the body after the closing --- is the prompt.

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. When structured fields are present, the server ignores content and re-renders it from the structured fields.

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 get agent-persona

code-reviewer                  Thorough code reviewer
murmur-baker       [platform]  Wizard for murmur init interactive onboarding: schema discovery, repo investigation, provisioning script drafting, bake-iterate-fix loop, workspace + custom agent persona creation, and a smoke test that proves an agent can build and test the customer's code. Not directly spawnable — requires a human in the loop.
murmur-director    [platform]  Project director that manages murmur tasks, reviews PRs, and coordinates autonomous agents. The main interface for getting work done.
murmur-planner     [platform]  Planner agent for design docs, architecture review, and package boundaries.
murmur-programmer  [platform]  Full-stack programmer and frontend designer-engineer obsessed with code quality and visual polish. Reviews and simplifies code, self-provisions Playwright, and verifies visual changes with desktop and mobile screenshots.
murmur-researcher  [platform]  disabled — re-enable: murmur set agent-persona murmur-researcher

Each line shows the name, a [platform] marker for platform-managed agent personas, and the description. Disabled platform personas are listed last with the command that re-enables them.

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. The frontmatter opens with a generation: key (and managed_by: when a system manages the persona). Both are ignored when the document is piped back to murmur set.

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 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. murmur rm agent-persona <murmur-name> disables one instead, and murmur set agent-persona <murmur-name> with no input re-enables it.

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