Models, helpers, and profiles

Concepts

Default model

• /model switches the live model. Persisting the choice writes defaultModel in the active profile’s config.yml.
• --model <provider/id> sets the model for one run and is never written back.
• defaultModel is an ordered chain: a comma-separated string or a list. The first entry that matches an available model is used, and later entries are retry fallbacks for it.
• Unset, a new session starts on an available model that has credentials.

# ~/.veyyon/profiles/default/agent/config.yml
defaultModel: anthropic/claude-sonnet-5:medium,openai/gpt-5

A model value may include a thinking suffix (:off, :auto, :minimal, :low, :medium, :high, :xhigh, :max). The model picker shows only variants the selected model supports. If a provider publishes effort tiers as separate upstream IDs, Veyyon presents one logical model and routes the chosen effort to the matching ID.

Ctrl+P and Shift+Ctrl+P (app.model.cycleForward, app.model.cycleBackward) cycle the scoped models when --models is set, and the available models otherwise.

Helpers

Each helper reads agent.helpers.<id>.model and agent.helpers.<id>.thinkingLevel.

A helper with no model runs the session’s live model, and one with no effort runs the session’s effort. A caller with no session, such as veyyon commit or a headless title, runs defaultModel instead. A helper model is an ordered chain like defaultModel; a :level suffix on the matching entry outranks the helper’s thinkingLevel. A configured chain that matches no available model leaves the feature without a model, and the feature reports the setting to fix.

Every helper request runs at the effort picked with its model, else the session’s effort, fitted to the efforts the model offers; off disables reasoning. Two helpers differ when no effort is set: autoThinking runs while the session’s effort is auto, the level it chooses, so it classifies with reasoning off, and veyyon commit has no session, so it sends no effort. A request that sends an effort has no output cap, because a provider that takes an effort counts reasoning inside the cap. A high session effort makes the unexpectedStop and speech helpers slower, and a speech rewrite that runs past 6 seconds falls back to plain cleanup; pick a model with a low effort for those helpers to keep them fast.

The vision helper searches further, because its job is to find a model that accepts images when the session model does not. inspect_image and image description for a text-only session model both take the first image-capable model from the vision chain, then defaultModel, then the session model, then any available model, skipping text-only models. A vision chain whose matched models are all text-only fails inspect_image with the setting to fix. The request runs at the vision helper’s effort, or a :level on its matched entry, else the session’s effort, fitted to the efforts the chosen model offers.

agent:
  helpers:
    title:
      model: openai/gpt-5-mini
      thinkingLevel: low
    plan:
      model: anthropic/claude-opus-4-5:high

In /settings, Agents → Roster lists the subagents, then the helpers, with the model and effort each one runs; a cell that reads session follows the session’s model or effort. Enter opens a helper’s page, which edits its model and effort, and Esc returns to the helper’s row. Choosing the first row of a picker, or Del or Backspace with an empty search, returns the value to unset.

A config from an earlier version that holds modelRoles is migrated on load. modelRoles.default becomes defaultModel. Each helper takes the first role that was set, in this order:

An @role reference in another model setting is replaced by that role’s models. slow, custom roles, cycleOrder, modelTags and role-keyed retry fallback chains are dropped, and the log lists each dropped value.

Agent policy and compaction overrides

agent:
  sharedModel: true
  model: deepseek/deepseek-chat:high,anthropic/claude-sonnet-5:low
  agents:
    scout:
      enabled: false
    reviewer:
      thinkingLevel: auto
compaction:
  model: openai/gpt-5-mini:low,anthropic/claude-haiku-4-5
  strategy: summary
  threshold: "80%"

In Settings, Enter edits the highlighted chain position. Add fallback appends a position. Delete removes only the highlighted position.

Profiles

Every profile including default:

~/.veyyon/profiles/<name>/agent/   # config.yml, sessions, MCP, skills, …

Instruction Files: Global vs Per-Profile (AGENTS.md)

Veyyon discovers two user-level instruction layers before every session:

1. Global User Layer (~/.veyyon/AGENTS.md): Applies across EVERY profile and workspace. Reserved for cross-profile standing rules.
2. Active Profile Layer (~/.veyyon/profiles/<profile_name>/...): Applies ONLY to the active profile. Scanned in descending priority order (first match wins; 1 file loaded per profile to prevent duplication):
   1. ~/.veyyon/profiles/<name>/agent/AGENTS.md (Highest)
   2. ~/.veyyon/profiles/<name>/AGENTS.md
   3. ~/.veyyon/profiles/<name>/agent/agent.md
   4. ~/.veyyon/profiles/<name>/agent.md (Lowest)

Global ~/.veyyon/config.yml holds cross-profile keys such as defaultProfile.
Activate: --profile, VEYYON_PROFILE, veyyon profile default <name>, TUI /profiles picker or /profile <name> (relaunch).
See Profiles, File locations.

Approvals

tools.approvalMode: plan | ask | ask-command | auto | yolo (schema default auto). Aliases: always-ask → ask, write and auto-edit → ask-command. See Approvals.

Related

• Models and providers
• Settings: models (repo docs/handbook/src/reference/settings.md)
• Compaction