Agents & model roles

Understand the three layersCopy Anchor Link

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 workflowCopy Anchor Link

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 HubCopy Anchor Link

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 agentCopy Anchor Link

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 roleCopy Anchor Link

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 modelCopy Anchor Link

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 agentsCopy Anchor Link

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 controlsCopy Anchor Link

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 resource usageCopy Anchor Link

TroubleshootingCopy Anchor Link

RelatedCopy Anchor Link

Source: omp.sh — MIT, Stencil Labs. Initially imported on 2026-10-03; updates via automatic sync.