Skip to main content

Overview

An agent in Xum owns two things for a given turn:
  • System prompt — what the assistant is and how it should behave
  • Tool policy — which tools it can call (and which it must call)
The same definition can be used in two places:
  • Selected in the UI as the workspace’s current mode (Exec, Plan, or your own)
  • Spawned via the task tool as a subagent in a child workspace
An agent definition is a Markdown file: YAML frontmatter declares metadata, policy, and AI defaults; the body becomes the agent’s instruction prompt.

Quick Start

Drop a Markdown file in .xum/agents/ (project) or ~/.xum/agents/ (global):
The filename (without .md) is the agent id, used by base: and task({ agentId }). IDs must match ^[a-z0-9]+(?:[a-z0-9_-]*[a-z0-9])?$ (1–64 chars, lowercase). Switch agents in the UI: Cmd/Ctrl+Shift+A opens the agent picker; Cmd/Ctrl+. cycles through visible agents.

Discovery and Precedence

Xum scans three roots, non-recursive (only direct .md children): Higher-priority definitions override lower-priority ones with the same id. Definitions larger than 1 MB are rejected at parse time. Filenames that don’t match the id schema are skipped with a warning.

Plugin agents in Claude Code or Cursor format

Agent plugins can ship agents/*.md files. A plugin agent that uses any Xum-only field (base, tools as an object, subagent, ui, ai, prompt, disabled) follows the Xum format below, unchanged. If such an agent also has a Claude Code disallowedTools list or a tools list, Xum skips it with a warning: Xum cannot tell which format the author meant, and ignoring the list would give the agent more tools than its author allowed. A plugin agent without any of those fields is read as a Claude Code or Cursor subagent. Both tools give such an agent every tool when it omits tools, so Xum maps it like this: So task({ agentId: "<file name>" }) spawns the agent with Exec’s tools, narrowed by any Claude Code tool list: without one, it can run shell commands and edit files. The body replaces Exec’s prompt. Xum still adds its sub-agent instructions (commit the work so the parent can apply the patch, and report back), because the parent depends on them. A readonly: true agent, or one with a read-only search list, gets Explore’s tools, prompt and sub-agent instructions instead, with its own body after Explore’s prompt. The agent does not appear in the agent picker. This mapping applies only to plugin agents. A project or global agent file in the same format keeps the Xum defaults (not runnable, no tools).

Plugin folder and spawn errors

A Claude Code or Cursor plugin agent often reads a file from its own plugin, for example ${CLAUDE_PLUGIN_ROOT}/agents/reviewer.md. Xum replaces ${CLAUDE_PLUGIN_ROOT} in the body of such an agent with the path of the plugin’s folder (C:/Users/... on a Windows host). ${CLAUDE_SKILL_DIR}, ${CLAUDE_PLUGIN_DATA}, ${CURSOR_PLUGIN_ROOT}, ${PLUGIN_ROOT} and ${PLUGIN_DATA} stay as written, and a plugin agent in the Xum format keeps its body unchanged. The review of a managed plugin does not cover the body, so the replacement never asks for a new review. A Claude Code or Cursor format agent whose body names ${CLAUDE_PLUGIN_ROOT} runs only where the workspace can read that folder: a local or worktree workspace for a plugin on the Xum host (also a multi-project workspace whose projects are all local or worktree), and an SSH or Docker workspace for a trusted plugin in that checkout. On any other workspace, such as an SSH, Docker or devcontainer workspace with a plugin from the Xum host, the task tool does not list the agent, and spawning it by ID fails with folder-unreachable. When task refuses a plugin agent that Xum loads, the error names the reason instead of saying unknown agentId: If a lower-precedence agent has the same ID, not-reviewed, ambiguous-file and invalid-definition skip the plugin agent, and that agent starts instead: the error appears only when no other agent has the ID. folder-unreachable never falls back. The unreachable agent keeps its ID, so Xum neither lists nor starts the lower agent: on an SSH workspace, a task spawn of a plugin agent named exec that names ${CLAUDE_PLUGIN_ROOT} fails with folder-unreachable and does not start the built-in Exec agent. Only a task spawn is refused: the main chat and an agent that has the unreachable agent as its base keep loading it. An agent ID that no scope has still fails with unknown agentId.

Claude Code tool lists

tools (allowlist) and disallowedTools (denylist) take Claude Code tool names, as a comma-separated string or a list. In tools, only the core tools grant Xum tools, and only the Xum tools that do the same job and no more, with one exception for read-only search lists. A name in disallowedTools removes every Xum tool that can do its job, so it can remove more: A name outside the core tools grants nothing, because its Xum tools do more than the Claude Code tool. For example, todo_write replaces the whole checklist, so TaskCreate cannot grant it. task_send_message and task_list reach workspaces outside the agent tree. heartbeat also deletes schedules. Claude Code never gives a sub-agent AskUserQuestion, EnterPlanMode, ExitPlanMode, Workflow or ScheduleWakeup. The provider-native search tools are not granted, because an MCP tool can have the same name. To search files, list Bash, or write a read-only search list. The rules follow Claude Code:
  • With tools, the agent gets only the granted Xum tools (within its base, Exec or Explore), and no MCP tools. Xum always keeps agent_report, because every sub-agent reports through it.
  • With disallowedTools, the agent gets every tool of its base except the removed ones. If both are set, a tool in both lists is removed.
  • The lists restrict this agent only. If it keeps Agent (the task tools), it can spawn sub-agents, which get their own tools, as in Claude Code. To restrict the whole tree, also deny Agent, or leave it out of tools.
  • If no tools entry grants a Xum tool, Xum skips the agent with a warning. Claude Code also refuses to launch such an agent.
  • disallowedTools names are matched without case (bash removes Bash). If Xum cannot read an entry, or does not know the name, it skips the agent with a warning, because the name can stand for a tool Xum has.
  • A removed family such as task_* can also remove MCP tools whose server name starts the same way (an MCP server named task).
  • A specifier such as Bash(git push *) in disallowedTools removes the whole tool, as in Claude Code. In tools, Xum cannot limit a tool to some of its calls, so it does not grant a tool with a specifier. Agent(worker) is the exception: Claude Code ignores its type list in sub-agents, so it grants the task tools. Commas inside a specifier do not split the list.
  • MCP entries (mcp__<server>, mcp__<server>__<tool>) are not translated yet. In tools they grant nothing. In disallowedTools, Xum skips the agent with a warning.
A changed list changes the agent’s definition, so a plugin update that changes it asks for consent again. The same holds for a change to readonly, model: fast or is_background: true. This Xum version changes how it maps those three fields, so each installed plugin agent that sets one needs one review after the upgrade.
Read-only search lists
Xum has no read-only search tool, so Grep and Glob in a tools list would leave a reviewer unable to search. A tools list is a read-only search list when every entry is exactly Read, Grep, Glob or LS, with the same case and no specifier, and at least one entry is Grep, Glob or LS. [read, grep], [Read, Grep(*.ts)], [Read, Edit, Grep] and [WebFetch, Grep] are not. This is the one place where a name grants more than the same job: such an agent is treated like a readonly: true agent (Explore’s tools, prompt and sub-agent instructions: no file edits, no task) and also gets the bash tools, so it can run rg and ls. Any other list keeps the mapping above, and Grep, Glob and LS grant nothing in it. disallowedTools names are removed first, as in Claude Code, and the rule then sees the entries that are left. With tools: [Read, Grep, Glob], disallowedTools: [Grep, Glob] ([grep, glob] and [Grep(*.ts), Glob] work too) leaves no search tool, so the agent gets no bash tools. disallowedTools: [Bash] keeps the Explore agent and removes its bash tools. LS in disallowedTools removes nothing and no longer makes Xum skip the agent. Bash on Explore is read-only by instruction only: a prompt injection in a document that the agent reads can run shell commands. Put Bash in disallowedTools to keep it off. An agent with model: inherit takes the model settings and the 5-minute prompt cache of Explore, not those of Exec. One review after the upgrade. The new mapping changes the definition of each installed plugin agent whose tools is a read-only search list. In Settings → Plugins, such an agent shows “Changed since you reviewed it” and does not load until you review it again. After a downgrade, the old mapping changes the definition back, and the agent needs another review. Project plugins and plugins in ~/.agents/plugins have no review: their agents get the bash tools as soon as Xum updates.

model: fast

A plugin agent with model: fast takes its model, thinking level, reasoning mode and prompt cache duration from Explore’s settings, as an Explore sub-agent does. Its tools and prompt still come from its base. For each field, the first source that sets it wins:
  1. Values pinned for this sub-agent: the model and thinking arguments of the task call, or a choice you sent in its chat.
  2. The agent’s own entry in Settings → Agents, then its frontmatter (a Claude Code effort lands here).
  3. Explore’s entry in Settings → Agents, then Explore’s definition.
  4. Exec’s entry in Settings → Agents, then Exec’s definition.
  5. At spawn, the parent’s model and thinking level. A reawakened agent keeps its current model and thinking level instead.
With no Explore model in Settings, a fast agent runs on Exec’s model from Settings, else on the parent’s model. The built-in Explore agent sets a 5-minute prompt cache, so a fast agent keeps 5 minutes unless its own card or Explore’s card sets another value. Fast and other spellings are not fast: they use the inherited model. Any agent can set ai.settingsBase. Xum reads the named agent as it would read the agent’s base, so a global agent’s settings base never resolves to a project agent. Xum ignores the settings base, and logs a warning, when it names a missing agent, the agent itself, an agent whose chain contains the agent, or an agent whose chain sets its own ai.settingsBase. It also ignores it when the agent’s own chain or the settings-base chain stops at a missing or cyclic base.

is_background: true

The task tool’s agent list marks such an agent with [meant to run in the background (run_in_background=true)]. This is a hint for the parent model. run_in_background still defaults to false.

File Format

Frontmatter

Markdown body

The body becomes the agent’s instruction prompt, layered with Xum’s base prelude, the workspace environment context, and AGENTS.md.
  • With prompt.append: true (default), a child’s body is appended to its base’s body, separated by a blank line.
  • With prompt.append: false, the child’s body replaces the base’s body. Tool policy, AI defaults, and other frontmatter still inherit normally.

Inheritance and Tool Policy

Base resolution

base: <id> walks the same discovery roots, with two non-obvious rules:
  • Same name as the current file — Xum skips the current file’s scope, so a project exec.md with base: exec resolves to the global or built-in exec (not itself).
  • Different name — Xum anchors the lookup at the current scope or lower. A built-in’s base: foo cannot pull in a project-level foo.md.
The chain is followed up to 10 levels deep. Cycles are detected and logged.

Tool patterns are anchored regex

Patterns in tools.add and tools.remove are regular expressions implicitly anchored as ^pattern$. task_.* matches task_await but not task — list task separately if you need both. If no agent in the resolved chain declares any tools, the agent has no tools.

Layer ordering

For each layer in the chain, from base → child:
  1. Apply every tools.add pattern as enable.
  2. Apply every tools.remove pattern as disable.
  3. If tools.require is present, the last literal entry becomes that layer’s effective required tool; child layers fully replace base layers.
Later rules win, so a child’s remove can drop something the base enabled, and a child’s add can re-enable something the base removed.

tools.require semantics

require is not the same as add:
  • It enables the tool and forces the model to emit a call to it this turn.
  • The value must be a literal tool name. Regex metacharacters cause the entry to be dropped silently.
  • Only one tool can be required per turn. Multiple entries collapse to the last one; child layers fully override the base layer.
  • The required tool must be one the agent is otherwise allowed to call — subagent hard-denies still apply.

Runtime restrictions

These rules are applied last and cannot be overridden by frontmatter: A chain is “plan-like” when the resolved tool policy enables propose_plan.

Task limits

Two limits in Settings → Behavior → Tasks apply to every sub-agent task: Depth counts from the workspace you chat in. That workspace has depth 0, its sub-agent has depth 1, and so on. With the default of 5, tasks can nest 5 levels below your workspace. Orchestration that nests a coordinator, workers, and their verifiers needs 4 levels, so the default leaves one level spare. A parent that waits in the foreground for its child does not count against the parallel limit. Each running task has its own workspace, model stream, and MCP servers. A higher parallel limit uses more memory and processes, and it sends more requests at the same time to your model provider, which can hit its rate limits. To cap the CPU and memory that agent commands use together, see Agent Resource Limits. When you upgrade from a version with the earlier defaults (16 parallel tasks, depth 3), Xum changes a limit that still has its earlier default to the new default, one time. Xum cannot tell whether you chose 16 or 3 yourself, so it changes those values too. If you want the earlier value, set it again after the upgrade. Xum keeps it from then on. Xum keeps every other value that you set.

Disabling and Extending Built-ins

Disable a built-in by creating a same-name file with disabled: true:
exec, plan, and compact are always enabled and cannot be disabled this way. Extend a built-in by giving your file the same id and using base:
This works because same-name base resolution skips the current scope. Use it to add repo-specific guidance (CI commands, test patterns) without copying the built-in body.

Using Agents

As the workspace agent

Switch via the agent picker in the chat input, Cmd/Ctrl+Shift+A, or Cmd/Ctrl+. to cycle. If a workspace’s stored agent has been disabled or deleted, top-level workspaces silently fall back to exec; subagent workspaces error out instead.

As a subagent via the task tool

For the normal task tool, the agent must have subagent.runnable: true. Workflow-owned agent steps may also use agents with subagent.workflow_runnable: true, such as the built-in Plan agent. Subagents see the body plus subagent.append_prompt. Non-plan subagents complete with their final assistant message and may call agent_report multiple times for incremental parent wake-ups; plan-like chains still complete via propose_plan.

Run-context AI defaults

Each agent has one defaults entry (agentAiDefaults), configured in Settings → Agents:
  • Base fields (modelString, thinkingLevel, reasoningMode) apply when you select the agent in the workspace.
  • Auto routing (with the Auto model routing experiment on): a UI agent’s model or reasoning can default to Auto, which routes each prompt you send by difficulty and keeps the base field as the fallback. An Auto or concrete choice you make in a workspace keeps winning for that agent in that workspace.
  • Delegated overrides (the sparse nested subagent profile) apply only when the agent is spawned via task, and win over the base fields per field.
Delegated overrides inherit per field from the base fields; base fields inherit per field from the agent’s frontmatter ai block. You can override one field (e.g. only thinkingLevel) and leave the others inherited. Subagents resolve their settings when spawned and again whenever an agent reawakens them (for example with task_send_message after the subagent reported), so a Settings change applies from the next reawakened turn. A subagent keeps its model until its current work ends.
  • Pins: values passed to task (model, thinking), and choices you pick in the subagent’s chat and then send, stay pinned until a plan subagent hands off to Exec.
  • Precedence for unpinned fields: Delegated overrides outrank both the parent chat’s Exec selection and the base defaults; an Exec subagent prefers the parent chat’s Exec selection over the base Exec default. A field that no setting configures keeps its current value.
  • Definition defaults are best effort at reawakening: if the agent definition can’t be read, the other settings still apply.
Subagents created before this behavior shipped keep their creation-time settings. Recreate them to get the new behavior. The internal Status Page agent (the status page agent experiment) runs in the background on the model you pick on its card in Settings → Agents. When its model is Inherit, it uses the workspace’s model. It always runs with reasoning off. Turn its Enabled switch off to stop it; the main agent then edits the status page itself.

Prompt cache duration

Each agent can set how long Anthropic keeps its prompt cache: 5 minutes or 1 hour. Set it with the Prompt cache control on the agent’s card in Settings → Agents, or with ai.cacheTtl in the agent’s frontmatter. It applies to the agent’s interactive and delegated runs alike, and only to Anthropic models (direct, custom Anthropic providers and Coder Anthropic routes). The first source that sets a duration wins:
  1. The agent’s Prompt cache value in Settings → Agents.
  2. The agent’s own frontmatter ai.cacheTtl (a project exec.md with base: exec refines the built-in one).
  3. Each declared base agent, child to root: its Settings value, then its frontmatter. With ai.settingsBase, Xum walks the settings-base agent and its bases instead.
  4. The global Prompt cache TTL for Anthropic in Settings → Providers (cacheTtl in providers.jsonc).
  5. Anthropic’s default, 5 minutes.
An agent without a base does not inherit Exec’s value. Inherit on the card shows the value the agent gets without its own Settings value. The built-in Explore and Compact agents set cacheTtl: 5m: their runs are short or one-shot, so a 1-hour cache costs more and is rarely read again. With a global 1-hour duration, Exec, Plan and custom agents use 1 hour while Explore and Compact keep 5 minutes, unless you pick another value on their cards. Agents based on Explore, and agents with ai.settingsBase: explore, also keep 5 minutes. See Prompt cache duration for the costs.

Examples

Security audit (read-only)

Documentation-only

Built-in Agents

Exec

Implement changes in the repository

Plan

Create a plan before coding

Compact (internal)

History compaction (internal)

Desktop (internal)

Visual desktop automation agent for GUI-heavy, screenshot-intensive workflows

Dream (internal)

Background memory consolidation (internal)

Explore (internal)

Read-only exploration of repository, environment, web, etc. Useful for investigation before making changes.

Name Workspace (internal)

Generate workspace name and title from user message

Status Page (internal)

Keeps the Agent interface status page current from the main agent’s updates (internal)