Agents & model roles

A model, a role, and an agent configure different layers:

An agent can point at a role, and the role points at a model. For example, the reviewer agent normally uses @slow; changing the slow role changes the model used by future reviewer runs without changing what the reviewer does.

A simple workflow

1. Enter /model, open Roles, and assign the common slots you care about. Start with default, smol, and slow; leave the rest automatic until you need predictable routing.

2. Enter /agents to inspect bundled and custom agents. Select one to see its source, enabled state, effective model, prewalk choice, and advisor choice.

3. Ask omp in ordinary language to use the specialist by name:

   Use the librarian to verify the upstream API behavior, then summarize the source evidence.

   Ask the reviewer to inspect the current change for correctness. Do not edit files.

   Parallelize the UI polish and security check: use the designer for the interface and the security-reviewer for a read-only audit.

4. Supervise the worker in Agent Hub. Read its activity and usage, open its transcript, send a normal follow-up, or stop it if the assignment is going wrong.

You never need to describe omp's internal delegation protocol. Name the outcome and specialist, add scope or safety limits, and let the main session coordinate the work.

Open and navigate Agent Hub

Press Alt+A to open Agent Hub. Ctrl+S opens the same view through the legacy session-observe binding.

There is also a navigation gesture that is easy to miss:

• From an empty main-session editor, press ← twice. Agent Hub opens when the current session has a worker to show.
• While focused in a worker, leave its editor empty and press ← twice to return to the main session.

Select a worker and press Enter to open its live or persisted transcript. A message sent there steers a running worker or follows up with an idle one. Agent Hub also shows status, resolved model, current activity, lineage, tokens, requests, tool calls, active time, and measured cost when available. Use r to revive a parked worker and x to kill one whose work should not continue.

See Subagents & Agent Hub for statuses, isolation, steering, limits, and the complete control reference.

Choose a bundled agent

These agents ship with omp:

Use the narrowest suitable specialist. A read-only agent is safer for investigation; task is appropriate when no specialist fits; sonic is for mechanical work, not ambiguous design or review. Open /agents for the effective definitions in your installation because project and user agents can add names or replace bundled ones.

Choose a role

Built-in roles route product features as well as agents:

Unassigned built-in roles are resolved automatically from available authenticated models. Assign a role in /model when you need stable behavior, cost, or provider choice. Changing the active model for the current conversation does not rewrite saved role assignments.

The Model roles page covers automatic selection, project storage, thinking levels, quick cycling, launch overrides, and retry fallback chains.

How an agent gets its model

For an ordinary named worker, omp tries these sources in order:

1. Settings override — task.agentModelOverrides.<agent-name>.
2. Agent default — the agent's model frontmatter, which may contain one selector or an ordered list.
3. Normal fallback — the parent session's active model, then its configured/default model fallback.

A selector in either of the first two layers may be a concrete provider/model or a role alias such as @slow. Role aliases are expanded through modelRoles at launch.

Use task.agentModelOverrides when you want to reroute an existing agent without copying or editing its definition. Prefer a role alias there when several agents or features should move together:

modelRoles:
  default: anthropic/claude-sonnet-4-5
  smol: openai/gpt-4.1-mini
  slow: openai/gpt-5.4:high
  review: openai/gpt-5.4:high

task:
  agentModelOverrides:
    reviewer: "@review"

With that configuration, /model controls which concrete model fills review, while /agents controls whether reviewer uses that role. A concrete model under agentModelOverrides bypasses the agent's frontmatter choice and does not move when a role is reassigned.

User and project agents

Custom agent definitions are Markdown files with YAML frontmatter:

• User scope: ~/.omp/agent/agents/*.md is available across projects.
• Project scope: .omp/agents/*.md belongs to the current project.

/agents labels definitions as Project, User, or Bundled. Names are case-sensitive. When names collide, the project definition wins over the user definition, and a custom definition wins over the bundled definition. This makes it possible to tailor a standard name such as reviewer for one repository, but it can also explain why its behavior differs there.

The model-related part of a definition can stay small:

---
name: release-auditor
description: Check release readiness and report concrete blockers.
tools: read, grep, glob, bash
model: "@slow"
prewalk: false
advisor: "@advisor"
---

Inspect the assigned release scope. Report evidence and blockers; do not edit files.

Here model participates in the precedence above. prewalk and advisor provide defaults for this agent; /agents can override either without changing the file. Use New agent in /agents to begin a definition, or follow Authoring subagents for all supported frontmatter, tool restrictions, output shapes, skill loading, and validation.

After editing an agent file while omp is running, return to /agents and press Ctrl+R to reload the list.

Per-agent prewalk and advisor controls

Select an agent in /agents to configure four properties: enabled, model, prewalk, and advisor.

• Prewalk starts the worker on its resolved model for planning and early implementation, then makes a one-time handoff to a faster or cheaper target. on uses @smol; off disables it; a model or role pattern chooses another target.
• Advisor pairs that worker with an independent reviewer model. on uses @advisor; off disables it; a model or role pattern chooses another advisor.

The corresponding settings override agent frontmatter and can be edited in ~/.omp/agent/config.yml:

task:
  agentPrewalk:
    task: "@smol"
    reviewer: "off"
  agentAdvisor:
    reviewer: "on"
    security-reviewer: "@slow"

Use /settings for broader defaults and limits. The Generic Task Prewalk setting (task.prewalk) affects the bundled task agent; per-agent choices in /agents still take precedence. See Prewalk, Advisor, and Settings for the full behavior of those systems.

Cost and troubleshooting

Every worker is a separate model session. Parallel workers multiply provider requests and token use; an advisor adds its own review calls, and prewalk can use two models over one worker's lifetime. Agent Hub reports measured usage and cost when the provider exposes enough data. Start with the smallest useful fan-out, route lightweight work deliberately, and stop obsolete workers.

If the result is not what you expected:

• Wrong behavior: confirm the exact agent name and source in /agents. A project definition may be shadowing the user or bundled definition.
• Wrong model: inspect the effective model in /agents, then check task.agentModelOverrides, the agent's model frontmatter, and the referenced role in /model, in that order. Also confirm that the selected provider is authenticated.
• Unknown or disabled agent: check the case-sensitive name and enabled state, then press Ctrl+R after file changes.
• Prewalk or advisor does not start: check the per-agent override first, then frontmatter, role assignment, model availability, and credentials. An unavailable prewalk target is skipped rather than failing the worker.
• Double-left does nothing: empty the editor and confirm this session has a worker to show. Alt+A opens Agent Hub even when the roster is empty.
• Hub shows no worker: Agent Hub is scoped to the current session. Return to or resume the session that launched the worker.

For exhaustive behavior, continue with Model roles, Subagents & Agent Hub, and Authoring subagents.