Skip to main content

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.

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

NameTypeRequiredDescription
namestringyesUnique identifier within the tenant. DNS label format: [a-z][a-z0-9-]{0,62}. Also accepts workspace-scoped names: {workspace}/{name}.
contentstringnoFull 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.
descriptionstringnoShort description of the persona’s role. Maximum 1024 bytes. Shown in murmur ls agent-persona output.
promptstringnoThe agent’s system prompt — the Markdown body after frontmatter. Stored verbatim.
modelstringnoModel override (e.g. claude-sonnet-4-6). Empty uses the platform default.
toolsstring[]noAllowed MCP tools the agent may use.
disallowed_toolsstring[]noMCP tools the agent may not use.
max_turnsint32noMaximum conversation turns. 0 means unlimited.
tasksAgentTask[]noDefault tasks seeded into the agent’s checklist on spawn.

​
AgentTask fields

Each entry in the tasks list has:
NameTypeRequiredDescription
subjectstringyesTask summary (e.g. “Run Go tests”).
activate_whenobjectnoActivation condition. Omit for tasks that are always active.
activate_when.files_modified.patternstringnoGlob pattern for file paths. The task activates when the agent pushes changes matching this pattern. Empty matches any file.

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

​
Deleting an agent persona

murmur rm agent-persona code-reviewer
Platform-managed agent personas cannot be deleted.

​
Errors

CodeMeaningWhat to do
INVALID_ARGUMENTname is requiredProvide a name field or pass the name as the CLI argument.
INVALID_ARGUMENTagent 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_ARGUMENTdescription exceeds 1024 byte limit (N bytes)Shorten the description field to 1024 bytes or fewer.
INVALID_ARGUMENTcontent and structured fields are mutually exclusiveProvide either content (Markdown with frontmatter) or structured fields (description, prompt, etc.) — not both.
INVALID_ARGUMENTeither content or structured fields are requiredThe request has no content and no prompt or description. Provide at least one.
INVALID_ARGUMENTparse agent content: ...The Markdown frontmatter failed to parse as valid YAML. Check your --- fences and YAML syntax.