> ## Documentation Index
> Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# agent-persona

> Catalog resource that defines a reusable agent template — system prompt, model, tool allowlists, default tasks, and per-persona turn limits.

An [agent persona](/concepts/agent-personas) is a catalog resource that defines a reusable template for [agents](/concepts/agents). When you spawn an [agent](/concepts/agents) with `--agent=<name>`, it inherits the persona's system prompt, model, tool configuration, and default tasks.

[Agent personas](/concepts/agent-personas) are tenant-scoped. Platform-managed [agent personas](/concepts/agent-personas) exist in every tenant. Custom [agent personas](/concepts/agent-personas) are authored via [`murmur set agent-persona`](/cli/set).

An [agent persona](/concepts/agent-personas) 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`](/cli/ls) 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](/concepts/agents) may use.                                                                                                                                                          |
| `disallowed_tools`    | string\[]           | no       | MCP tools the [agent](/concepts/agents) may not use.                                                                                                                                                              |
| `max_turns`           | int32               | no       | Maximum conversation turns. `0` means unlimited.                                                                                                                                                                  |
| `tasks`               | AgentTask\[]        | no       | Default tasks seeded into the [agent's](/concepts/agents) checklist on spawn.                                                                                                                                     |
| `follow_up_overrides` | FollowUpOverride\[] | no       | Per-event-class overrides for the instructions and tasks an [event](/concepts/events) generates. Authored as the `followups:` frontmatter map. See [follow-up overrides](#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](/concepts/agents) pushes changes matching this pattern. Empty matches any file. |

## Follow-up overrides

When an [event](/concepts/events) wakes an [agent](/concepts/agents) — 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.

```bash theme={null}
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
```

<Note>
  Frontmatter keys use camelCase: `disallowedTools`, `maxTurns`. This matches the format that the server renders on read.
</Note>

### Structured fields

Post individual fields as YAML. The `prompt` field carries the system prompt directly.

```bash theme={null}
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
```

<Warning>
  Do not combine `content` with structured fields (`description`, `prompt`, `model`, etc.) in the same request. The server rejects requests that provide both.
</Warning>

## Examples

### Creating an agent persona

```bash theme={null}
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

```bash theme={null}
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](/concepts/agent-personas) are marked `[platform]`.

### Reading a single agent persona

```bash theme={null}
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

```bash theme={null}
murmur spawn --agent=code-reviewer review-pr-42 "Review PR #42"
```

The [agent](/concepts/agents) inherits the [agent persona's](/concepts/agent-personas) prompt, model, tools, and default tasks.

### Tasks with activation conditions

```yaml theme={null}
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](/concepts/agents) pushes changes matching the glob pattern.

### Overriding follow-up instructions

```bash theme={null}
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

```bash theme={null}
murmur rm agent-persona code-reviewer
```

<Note>
  Platform-managed [agent personas](/concepts/agent-personas) cannot be deleted.
</Note>

## 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.                      |

## Related

* [Agent personas](/concepts/agent-personas) — concept overview
* [Agents](/concepts/agents) — the resources that use personas at spawn time
* [`murmur spawn`](/cli/spawn) — CLI command for spawning [agents](/concepts/agents) with a persona
* [`murmur set`](/cli/set) — CLI command for creating and updating catalog resources
* [`murmur get`](/cli/get) — CLI command for reading catalog resources