The Veyyon handbook

Veyyon runs in your terminal and edits real code. Bring your own model keys; the harness is tuned for coding work, not chat theater.

This handbook is for everyone who uses Veyyon or wants to understand it.

• Why Veyyon: value, design map, and benefits you should feel first.
• Install and first session: install, providers, quickstart, configuration.
• Everyday features: editing, sandbox, models, sessions, themes.
• Power features: plan mode, goals, branching, MCP, plugins, memory, profiles.
• How it works: deeper engineering account for contributors.

If you read nothing else: What Veyyon gives you, Getting started, Editing and repair, Models and providers.

What Veyyon is, in one paragraph

Veyyon is a fork of oh-my-pi: TypeScript and Bun for the CLI, TUI, tools, providers, and session loop; Rust natives for grep, PTY, and hashline edits. Install with bun install -g @veyyon/pi-coding-agent or bun dev from source. The command is veyyon (short alias vey). Config and state default to ~/.veyyon.

Shipped today: hashline edits, mnemopi memory, model roles, session trees, MCP, skills, and plan/goal modes.

Why it is different (shipped vs planned)

• Edits that land. Hashline and model-tuned edit tools with native verification; fewer retry loops on bad diffs.
• Explicit model slots. Pick the model you talk to, the model for subagents, and the model for compaction — three plain choices, no default-chain indirection.
• Honest interface. Veyyon Dark uses the silver palette; plan/goal modes and tool approval tiers are engine features.

Spec — not shipped: the full schema-based tool-call repair cascade, a unified single-write-path proof, and self-contained profiles. See What makes Veyyon different.

On honesty

This book states plainly what is built and what is planned. Pages marked Spec — not shipped describe target design not yet in the product. Credits: Acknowledgements.

Why Veyyon

This section explains why Veyyon exists and what it gives you. Veyyon is a coding agent that runs in your terminal, edits real code, and lets you bring your own model keys. The pages here are the value proposition: what changes, why it is faster and cheaper, and how the design behind it keeps the agent honest.

• What Veyyon gives you introduces the problem Veyyon solves and the concrete benefits you get from a harness built around each model’s strengths.

• What makes Veyyon different is the short design map behind those benefits: hashline-first editing, per-model harnesses, tiered tool approval, and stop-when-green control flow.

• Performance shows how fewer retries, an edit format that open models emit reliably, and a lightweight harness add up to faster turns and lower cost.

• Edits that land the first time explains how Veyyon repairs malformed tool calls and normalizes diffs so a change does not bounce back for a retry.

• Lower token cost and faster turns details how bounded tools, compaction, and early verification keep the context focused on what still matters.

• Model choice without lock-in covers the provider-agnostic engine and per-model profiles that let you point Veyyon at any supported model or API.

• Safety and honesty you can see describes the visible sandbox, loud failures, and honest telemetry that make the agent safe to use in real repositories.

Where to go next: install Veyyon with Install, then read the Core concepts section to learn how sessions, context, and the harness fit together.

What Veyyon gives you

Veyyon runs in your terminal and edits real code on your keys. The harness is built so capable models waste fewer turns on bad edits and opaque scaffolding.

The problem Veyyon solves

Most coding agents wrap every model in the same generic scaffolding. A model trained for one edit shape is forced into another. The result is wasted turns, malformed tool calls, diffs that fail to apply, and token bills that climb with every retry. The weights are often capable; the scaffolding holds them back.

Veyyon (oh-my-pi lineage) cuts that waste: hashline edits tuned per model, native search and read paths, provider-agnostic configuration, and a TUI that keeps sandboxing and approvals visible.

What you get today

• Edits that land. Hashline and related edit tools with model-specific prompts; fewer retry loops on bad diffs.
• Bring your own key. Dozens of providers via the bundled catalog; no vendor lock-in.
• Per-role models. Assign fast, thinking, vision, task, and other roles without reconfiguring every session.
• A real agent loop. Read, search, edit, bash, LSP, browser, MCP, compaction, and subagents, all inside approval and sandbox policy you control.
• Session trees. Branch, fork, and navigate conversation history without losing abandoned paths.
• Memory. mnemopi-backed recall across sessions (see Memory).
• Lower cost. Fewer format retries and leaner reads mean fewer tokens for the same outcome.

Who Veyyon is for

• Developers who want a capable terminal agent on their own keys.
• Teams running open or gateway models with a harness tuned for coding, not chat-only UIs.
• Anyone who wants visible sandbox boundaries and honest tool failures.

Where to go next

• Edits that land the first time
• What makes Veyyon different
• Getting started

What makes Veyyon different

These ideas set Veyyon apart. Each is shipped unless noted as Spec — not shipped.

For a reader-first pass, start with the benefit chapters. This page is the compact design map.

Hashline-first editing

Open models emit reliable hashline patches when the harness matches their training. Veyyon’s edit and write tools apply hashline patches with verification before bytes hit disk, so an edit either lands exactly or fails loudly with recovery hints.

See Editing and repair and The hashline edit engine.

Tool approval by tier (autonomy ladder)

tools.approvalMode (plan, ask, auto-edit, yolo; legacy always-ask / write aliases) and per-tool tools.approval overrides gate read, write, and exec tiers. Bash can force prompts on destructive patterns even in permissive modes.

See docs/approval-mode.md and /settings → Advanced → Safety.

Every model in the harness it fits

Model selection is three explicit slots — the interactive model (chosen with /model), the subagent model, and the compaction model (both set in settings). No default model stands in for the others. Optional named roles live in settings, scoped per profile, for anyone who wants specific work types pinned to specific models. Prompts and tool exposure adapt per model and per agent kind (main vs subagent).

Provider-agnostic runtime

The agent loop, TUI, session format, MCP, skills, hooks, and extensions are provider-neutral. You configure providers in ~/.veyyon/agent/config.yml or via /setup / /providers.

Control flow in the harness

Compaction, goal continuation, plan mode, vibe mode, and task subagents are engine features, not persona-only instructions. Goal mode can auto-continue idle sessions toward an objective; plan mode drafts a plan file before mutating the repo.

Spec — not shipped (documented elsewhere)

• A full schema-based tool-call repair cascade. General schema repair on tool calls is shipped; the broader cascade is planned. See Repair overview.
• Self-contained profiles that own isolated MCP/skills copies per profile. Today profiles relocate the agent directory to ~/.veyyon/profiles/<name>/agent/.
• A top-level veyyon doctor install-health command. Use veyyon plugin doctor and /debug today.

Where to go next

• Performance
• The thesis: the harness is the lever
• Roles and profiles

Performance

Speed in a coding agent is not one number. It is the sum of many small choices: how often a change lands on the first try, how much text the model has to emit, how quickly the harness gets out of the way. Veyyon is built so those choices add up in your favor. This page explains what that means for you.

Fewer wasted round trips

The largest cost in an agent is not the model thinking. It is the model redoing work. A malformed tool call, a bad diff, a value in the wrong shape: each one normally costs a full extra round trip, where the model receives an error, apologizes, and tries again. Veyyon repairs the common mistakes before they reach you, so the work lands on the first attempt. Fewer round trips means a faster answer and a smaller bill.

An edit format that does not fight the model

When the edit format is hard to emit correctly, a weak model burns its turns on retries and its budget on extra output. Veyyon uses an edit format that open models produce reliably, and it normalizes and applies edits in a single pass over the file, so editing a large file with many changes stays fast as the file grows.

A harness that gets out of the way

Veyyon is a lightweight Bun and TypeScript harness with Rust natives on the hot paths (grep, PTY, hashline edits). It starts quickly, it streams output as it arrives, and it does the internal bookkeeping of a turn without copying your data more than once. The work the harness does between you and the model is kept to the minimum, so the time you wait is the model’s time, not the harness’s.

Measured, not asserted

Every speed claim in Veyyon is backed by a benchmark that runs on every change. A change that would make a hot path slower fails the build before it ships. We hold even a correct fallback path to a speed bound, because a path that is correct but slow is still a path that wastes your time. The internal record of each change and its measurement is kept by the team and is not part of this public book, but the rule it follows is stated here: a performance claim that is not measured is not made.

What this adds up to

A clean edit format, automatic repair, a control flow that stops when the work is done, and a harness that copies nothing it does not have to. Individually each is small. Together they are the difference between an agent that feels heavy and one that feels instant, at a fraction of the cost of a frontier model.

Where to go next

• What makes Veyyon different is the design behind these gains.
• Getting started puts it to work.

Edits that land the first time

The most visible difference in Veyyon is simple: fewer failed edit turns.

Most coding agents lose time in small, boring ways. A model sends a tool call with one field named wrongly. It wraps a JSON array in a string. It emits a patch in the format the backend cannot carry. The agent bounces the error back to the model, the model apologizes, and the same edit gets tried again.

Veyyon removes that waste at the harness layer.

What improves

• Hashline edits anchor on read/grep snapshot tags for verifiable hunks.
• edit, write, and apply_patch modes share sandbox and approval gates.
• Stale anchors fail with recovery hints instead of silent wrong edits.
• General schema repair coerces almost-right tool calls into shape before dispatch.

Where the details live

• Editing and repair explains the user-facing behavior.
• Why repair exists explains the repair seam.
• The hashline edit engine explains the shipped edit path.

Lower token cost and faster turns

Veyyon treats cost as a product feature. The cheapest token is the one the model never has to spend.

Cost drops when the harness avoids retries, bounds tool output, keeps the working context small, preserves cache-friendly continuity, and verifies before spending more turns. These are not separate tricks. They compound.

What improves

• Bounded read, glob, and grep tools prevent one call from flooding the context.
• Tool output says exactly when and how it was truncated.
• Compaction preserves the task state instead of dropping history silently.
• The deterministic file working set survives compaction.
• Reviewer hints and verification stop wasted turns before they become expensive loops.

Why it matters

A long coding task fails when the model loses the plot. It also gets expensive when every tool call returns more text than the next decision needs. Veyyon keeps the context focused on the files, failures, and diffs that still matter.

Where the details live

• Performance explains the product-level speed story.
• Bounded reads and instant search explains the tool-output bounds.
• Compaction and project memory explains long-task context.
• Goal state explains how the harness keeps long tasks coherent.

Model choice without lock-in

Veyyon’s terminal engine is provider and API agnostic. You can point it at a local server, a direct provider API, or a compatible gateway. In every path, the harness adapts to the selected API and model instead of forcing every model through one generic shape.

What improves

• Provider details live in a data catalog, not scattered through code.
• Each backend gets the wire API and edit form it can actually carry.
• Per-model prompt order and tool exposure are assembled from the catalog.
• You can pin a specific model when you want explicit control.
• Provider-agnostic improvements such as tool repair, path repair, edit verification, goal/context handling, prompt profiles, and output bounds work with any compatible API you choose.

Why it matters

Open models are not interchangeable. A model that is strong at one language or patch shape can be weak at another. A generic harness hides those differences and pays for them in retries. Veyyon makes the differences explicit and uses them.

Where the details live

• Models and providers explains the user-facing model choice.
• Providers explains model and provider configuration.
• Execution-order prompts explains the prompt shape.
• Per-model posture explains per-model repair posture via harness profiles (bounded repair telemetry is spec, not shipped).

Safety and honesty you can see

Veyyon is useful because it can act. That only works if the boundary is visible and the results are honest.

The harness is designed to fail loudly when it cannot honor a safety rule, a schema, a config file, or a tool contract. Silent degradation is treated as a product bug.

What improves

• File writes and commands run through approval and sandbox policy.
• Tool output records truncation instead of hiding it.
• Bad config fails with context instead of falling back silently.
• Repair abstains when the schema does not prove a safe fix.
• Observability records coarse, bounded signals without logging secrets.

Why it matters

An agent that silently weakens its boundary is hard to trust. An agent that tells you exactly what it did, what it refused, and what it could not prove is much easier to use in a real repository.

Where the details live

• Configuration explains the knobs.
• Soundness and telemetry explains repair refusal and signals.
• Observability explains runtime signals.
• Architecture at a glance explains the boundaries.

Install

Veyyon ships as the npm package @veyyon/pi-coding-agent and installs the veyyon executable. It is a TypeScript + Bun agent loop with Rust natives (@veyyon/pi-natives) for hot paths (grep, walker, shell/PTY, hashline edits). After install, run veyyon plugin doctor.

Requirements

• Bun (recommended runtime) or a recent Node.js.
• Git — most workflows expect a repository.
• On Linux: user-namespace support for bubblewrap-based shell isolation (WSL2 yes; WSL1 no).
• On macOS: Seatbelt is used for the shell sandbox.

Install (npm / Bun)

$ bun install -g @veyyon/pi-coding-agent
$ veyyon --version

npm works too:

$ npm install -g @veyyon/pi-coding-agent
$ veyyon --version

bun install also builds @veyyon/pi-natives. Config and state default to ~/.veyyon.

After install

The first interactive veyyon opens the setup ceremony (splash → providers → glyphs → theme → outro). Force it again with veyyon setup. Re-open providers inside a session with /setup or /providers. See Getting started.

Build from source

$ git clone https://github.com/santhsecurity/veyyon.git
$ cd veyyon
$ bun setup      # installs workspace deps and builds @veyyon/pi-natives
$ bun dev --version

bun dev runs the in-repo build; use it while evaluating or contributing.

Shell completions

$ veyyon completions bash|zsh|fish

Verify the install

$ veyyon --version
$ veyyon plugin doctor
$ veyyon plugin doctor --fix

veyyon plugin doctor checks plugin health and warns when optional external binaries (sd, sg, git) or common API keys are missing. See Diagnostics.

Spec — not shipped: a top-level veyyon doctor with install-wide --summary / --json self-test. Today diagnostics are scoped to veyyon plugin doctor and the TUI /debug.

Relocate the config directory

By default Unix uses ~/.veyyon. PI_CONFIG_DIR renames the home-relative config directory, and PI_CODING_AGENT_DIR relocates the whole agent base (config.yml, agent.db, sessions, and more):

$ export PI_CODING_AGENT_DIR=/path/to/veyyon-agent
$ veyyon plugin doctor

Layout: File locations.

First credentials

On first interactive launch, the setup ceremony (or veyyon setup) walks sign-in and API keys. Inside a session, use /setup / /providers to re-open that panel, /login (or /login <provider>) for OAuth and key entry, or export the provider’s environment variable and skip the interactive step. See Authentication and Configuring providers.

Uninstall

Remove the global package:

$ bun remove -g @veyyon/pi-coding-agent
$ # or: npm uninstall -g @veyyon/pi-coding-agent

Then remove state if you want a clean machine:

$ rm -rf ~/.veyyon          # irreversible: config, secrets, sessions, plugins, skills, logs
$ # if you relocated the agent base:
$ rm -rf "$PI_CODING_AGENT_DIR"

Project-local files (AGENTS.md, .veyyon/ in a repo) are not removed by deleting the home directory — clean those per repository if desired.

To keep projects but wipe only sessions:

$ rm -rf ~/.veyyon/agent/sessions

Next

• Getting started — first interactive edit with sample terminal output.
• Model contract — choose credentials with the harness boundary in mind.
• Safety — approvals and fail-closed behavior.
• Troubleshooting / FAQ — when the doctor is not enough.

Signing in

Veyyon authenticates to whichever provider you point it at and calls provider APIs directly with keys you supply. It has no telemetry egress of its own. Logins are provider-scoped: authenticating anthropic does not authenticate openai, and each provider tracks its own credentials.

Sign in from the TUI

Use the interactive slash commands inside a session:

• /login — opens the OAuth/key selector.
• /login <provider> — jumps straight to one provider, e.g. /login anthropic, /login openai.
• /login <redirect-url> — completes an OAuth flow that needs a pasted callback URL.
• /logout — opens the provider selector to remove stored credentials.

On first run, the setup ceremony (veyyon setup, or /setup / /providers later) walks the same flow.

Headless and remote hosts

For CI, servers, or a shared team credential store, use the auth broker from the shell:

$ veyyon auth-broker login <provider>
$ veyyon auth-broker status
$ veyyon auth-broker list
$ veyyon auth-broker logout

import and migrate are also available. See Providers and docs/secrets.md for the broker model.

Using an environment variable instead

Every provider reads one or more environment variables, so a key already exported in your shell (or in a .env file) is used without an interactive sign-in.

The full provider → variable map lives in Providers. .env files are loaded from <cwd>/.env, ~/.veyyon/agent/.env, ~/.veyyon/.env, and ~/.env, with earlier sources winning.

How keys are resolved

When a provider needs a key, Veyyon resolves it in order (first match wins):

1. A runtime --api-key for the current process (never persisted).
2. A models.yml apiKey on a custom provider.
3. A stored API key in the auth store.
4. A stored OAuth credential (refreshed as needed).
5. The provider’s environment variable (including .env).

Stored credentials live in the auth store at ~/.veyyon/agent/agent.db (or the configured auth-broker snapshot in broker mode). PI_CODING_AGENT_DIR relocates the agent base, and the auth store moves with it.

Provider data is data-driven

Provider identity (display name, env var, OAuth parameters) and endpoints (base URL, API kind) come from the bundled model catalog plus your ~/.veyyon/agent/models.yml. A new BYOK provider becomes selectable by adding a providers: entry — not by changing code. See Configuring providers and docs/providers.md.

See also: Models and providers and the CLI reference.

Quickstart

From install to a first approved code change in about five minutes. Full path: Getting started.

Before you start

which veyyon
veyyon --version

If missing:

bun install -g @veyyon/pi-coding-agent

Or from source: bun setup && bun dev in the repo root.

Check the environment

Shipped today: plugin and extension health checks:

veyyon plugin doctor

Optional: /debug in the TUI for interactive diagnostics.

Spec — not shipped: a top-level veyyon doctor install health command. Use veyyon plugin doctor and the TUI /debug today. See Diagnostics and health.

Config and sessions live under ~/.veyyon/agent/ by default (VEYYON_CONFIG_DIR / OMP_CONFIG_DIR / PI_CONFIG_DIR can rename the home-relative dir).

Start your first session

cd my-project
veyyon

First interactive launch shows the setup ceremony (splash → providers → glyphs → theme → outro), then the welcome screen and composer. Resume / VEYYON_SKIP_SETUP=1 skips it. Re-open providers later with /setup or /providers, or run veyyon setup from the shell.

After that you should see the TUI composer, model indicator, and workspace path.

Ask for a small edit

> Add a name argument to greet() in greet.py, default 'world'.

Veyyon reads the file, proposes an edit or hashline change, and may pause for approval depending on tools.approvalMode. Press y to accept when prompted.

Composer conveniences

• @ — file/skill/plugin completion
• / — slash commands (/help, /tree, /settings, …)
• Esc — interrupt a running turn
• ? — shortcut hints on empty composer

Next steps

• Editing and repair
• Safety
• Configuration
• CLI reference

You now know the loop: start veyyon, ask, approve tools, inspect diffs.

Getting started

Install Veyyon, complete the first-run ceremony, and land your first approved edit. Budget about five minutes.

1. Install

npm / Bun (recommended)

$ bun install -g @veyyon/pi-coding-agent
$ veyyon --version

From source (repo root):

$ git clone https://github.com/santhsecurity/veyyon.git
$ cd veyyon
$ bun setup
$ bun dev --version

bun setup installs workspace deps and builds @veyyon/pi-natives. Config and state default to ~/.veyyon.

Shell completions: veyyon completions bash|zsh|fish. See Install.

2. First launch — the setup ceremony

The first interactive veyyon (or an explicit veyyon setup) opens a fullscreen ceremony:

1. Splash — silver wordmark reveal
2. Providers — sign in to a model provider; optional web search tab
3. Glyphs — Nerd Font / Unicode / ASCII for your terminal
4. Theme — Titanium (default dark), Light, or browse
5. Outro — handoff into the session welcome

Re-run the provider panel later with /setup or /providers inside the TUI. Skip the ceremony with VEYYON_SKIP_SETUP=1 (or resume an existing session).

API key (example): set DEEPSEEK_API_KEY in the environment, then pick a DeepSeek model in /model.

Custom gateway — add a provider in ~/.veyyon/agent/models.yml:

providers:
  my-gateway:
    baseUrl: https://gateway.example.com/v1
    api: openai-completions
    apiKey: MY_GATEWAY_API_KEY
    models:
      - id: claude-sonnet
        name: Claude Sonnet via Gateway
        contextWindow: 200000
        maxTokens: 8192

OAuth providers: /login or /login anthropic inside the TUI (same flows the Providers scene uses).

Details: Models and providers, Configuring providers, engine doc docs/providers.md.

Local Ollama (keyless when the daemon is up):

$ ollama serve
$ veyyon

Then /model and choose an ollama/… model from discovery.

3. Run your first task

$ cd ~/code/my-project
$ veyyon

Describe a small task:

Add a function add(a, b) in src/lib.rs and a unit test. Run the test.

Typical flow:

1. Veyyon reads relevant files (read, search, …).
2. It proposes an edit through hashline/edit/write tools.
3. When policy requires it, you approve the tool call (tools.approvalMode — see Safety).
4. The change lands; diffs appear in the TUI.
5. If you asked for tests, approve bash or cargo test as needed.

4. Work safely (defaults)

Tool approval tiers (read, write, exec) combine with tools.approvalMode:

Legacy names always-ask (→ ask) and write (→ auto-edit) are still accepted.

Use /settings or config to tighten policy on unfamiliar repos. Deep dive: Sandbox, Safety, docs/approval-mode.md.

5. Three things to try next

1. Multi-file change — ask for a refactor across modules; watch hashline edits batch paths.
2. Session tree — /tree to jump to an earlier user message and branch in the same session file.
3. Switch models — /model for the model you talk to; set the subagent and compaction models in settings. See Models, roles, and profiles.

Where to go next

• Quickstart — shorter walkthrough.
• Configuration
• Sessions
• Memory — mnemopi backend
• Diagnostics — plugin doctor and debug tools

Configuring providers

Copy-paste setups for bring-your-own-key (BYOK) and local providers. For the day-to-day switching guide, see Models and providers. For the harness/provider boundary, see Model contract.

Custom providers live under providers: in ~/.veyyon/agent/models.yml. Keys are resolved from the environment, stored auth, OAuth, or a models.yml apiKey (see Providers and docs/providers.md).

Anatomy of a provider entry

# ~/.veyyon/agent/models.yml
providers:
  acme:
    baseUrl: https://api.acme.example/v1
    api: openai-completions
    apiKey: ACME_API_KEY        # env-var name if set, else literal text
    models:
      - id: acme-coder
        name: ACME Coder
        contextWindow: 128000
        maxTokens: 8192

Notes worth knowing:

• Custom providers are merged alongside built-ins; they do not silently replace openai.
• A custom ollama / lm-studio / llama.cpp entry replaces that engine’s built-in discovery.
• A YAML or schema error makes the registry skip the file loudly — validate with veyyon models.

After editing, restart the session or /reload.

OpenAI (API key)

$ export OPENAI_API_KEY=sk-...
$ veyyon --model openai/gpt-5

Managed OpenAI sign-in is also available with /login openai inside the TUI, so no key is pasted into the shell. See Authentication.

DeepSeek

providers:
  deepseek:
    baseUrl: https://api.deepseek.com
    api: openai-completions
    apiKey: DEEPSEEK_API_KEY
    models:
      - id: deepseek-chat
        name: DeepSeek Chat
        contextWindow: 128000
        maxTokens: 8192

$ export DEEPSEEK_API_KEY=sk-...
$ veyyon --model deepseek/deepseek-chat

deepseek is also a built-in catalog provider; the env var alone is enough if you do not need a custom endpoint.

OpenRouter (OpenAI-compatible gateway)

$ export OPENROUTER_API_KEY=...
$ veyyon --model openrouter/anthropic/claude-sonnet-4

Model ids are whatever OpenRouter lists; Veyyon discovers them at runtime.

Anthropic

Anthropic is a built-in provider. Sign in with /login anthropic (OAuth) or set ANTHROPIC_API_KEY:

$ export ANTHROPIC_API_KEY=sk-ant-...
$ veyyon --model anthropic/claude-sonnet-4-5

To reach Anthropic models through a gateway instead, add an OpenAI-compatible custom provider (OpenRouter, LiteLLM, a team proxy) and select the gateway’s model id.

Other OpenAI-compatible hosts

Any host that speaks Chat Completions works the same way — only baseUrl, api, and apiKey change:

providers:
  my-proxy:
    baseUrl: https://llm-proxy.example.com/v1
    api: openai-completions
    apiKey: PROXY_API_KEY
    authHeader: true
    models:
      - id: coder-large
        name: Org Coder Large
        contextWindow: 200000
        maxTokens: 8192

$ export PROXY_API_KEY=...
$ veyyon --model my-proxy/coder-large

Amazon Bedrock

Bedrock is a built-in provider. Use the usual AWS credential chain (AWS_PROFILE, instance role, or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY) expected by the AWS SDK on your machine.

Ollama (local)

Ollama is discovered automatically and is keyless when the daemon is running. Default base URL http://127.0.0.1:11434 (override with OLLAMA_BASE_URL).

$ ollama serve
$ ollama pull llama3.2
$ veyyon           # then /model and pick an ollama/… entry from discovery

LM Studio (local)

LM Studio (lm-studio) is also discovered automatically and keyless by default. Default base URL http://127.0.0.1:1234/v1 (override with LM_STUDIO_BASE_URL).

$ lms server start
$ veyyon           # then /model and pick an lm-studio/… entry

Pinning models for roles and CI

Set background roles under modelRoles in config.yml:

# ~/.veyyon/agent/config.yml
modelRoles:
  default: openai/gpt-5
  smol: openai/gpt-5-mini
  task: deepseek/deepseek-chat

For a hermetic CI run, pass an explicit model and a one-shot config overlay:

$ veyyon --config ./ci-settings.yml --model openai/gpt-5-mini \
    "summarize the staged diff in five bullets"

Verify

$ veyyon models
$ veyyon --model <provider>/<id> "reply with the model name you are"

If discovery or auth fails, the error names the provider and the missing key or unreachable base URL — fix that rather than retrying with a different silent default.

See also

• Models and providers
• Model contract
• Provider stack
• Authentication
• Configuration

Core concepts

This chapter is the mental model for how Veyyon runs. Read it when you need the vocabulary behind sessions, permissions, and the BYOK model boundary. Day-to-day commands live in Using Veyyon; feature guides live under Features.

What this chapter covers

Veyyon is a terminal coding harness. The CLI is veyyon. You point it at a model endpoint with a key you supply, and the harness drives a loop of read, edit, verify, and stop. The concepts below explain the units of that loop and the contracts that keep it predictable across providers.

Foundations that pair with these pages

Before or after this chapter, the foundations pages give the design spine without repeating the day-to-day workflow:

• Core concepts (foundations) defines session, thread, turn, rollout JSONL, and the state database in more detail.
• Architecture overview maps subsystems to responsibilities.
• Provider and model configuration: Providers and docs/providers.md.

How the pieces fit

  you ──► veyyon (TUI or a one-shot prompt)
            │
            ├─ session / thread / turn   (concepts/sessions-turns-threads)
            ├─ sandbox + approvals       (concepts/permission-model)
            └─ model call                (concepts/model-contract)
                  │
                  ├─ system prompt + tool schemas (harness)
                  ├─ endpoint + key               (your provider)
                  └─ model id                     (discovered or pinned)

The harness stays the same when you change providers. You change the endpoint, the key, and optionally the model id. Tool repair, edit verification, sandboxing, and context compaction remain harness behavior. See Configuring providers for copy-paste setups and Models and providers for day-to-day model selection.

Related reading

• Permission model and Sandbox for Landlock/Seatbelt details.
• Prefer --approval-mode auto-edit for bounded automation.
• Non-interactive mode for scripted veyyon launch patterns.

Sessions, turns, and threads

A Veyyon run is a loop of user requests and agent responses. The session holds the whole run. Each turn is one request and the agent loop that answers it. A thread is one path through the session tree. These three ideas are the foundation for branching, plan mode, and long-running context.

Lifecycle of a run

start session (veyyon / veyyon "prompt" / resume)
        │
        ▼
compose prompt ──► turn begins
        │
        ├─ assemble context (instructions, goal card, recent history, tools)
        ├─ call model
        ├─ dispatch / repair tool calls (edit, exec, MCP, …)
        ├─ approvals + sandbox gate
        └─ final reply ──► turn ends (or Esc abort)
        │
        ▼
append rollout entry ──► update active leaf
        │
        ├─ next user message ──► next turn
        ├─ /compact when the window is tight
        └─ /fork / /branch / /tree when exploring branches

Interactive veyyon, a non-interactive veyyon "prompt" run, and resume paths all share this loop. The difference is who supplies the next prompt and whether a TUI is attached.

What a session is

A session is the unit of interactive work. Start one with veyyon in the repository you want to change. The session records every turn, tool call, approval, edit, and verification result.

Sessions are stored as append-only rollout JSONL files. Each line is an entry with an id and a parent_id. Those two fields make the file a tree, not just a log. The session never rewrites history. It only appends new entries or pointer moves.

What a turn is

A turn is one user request plus the agent loop that responds to it. The loop calls the model, dispatches any tool calls, and produces the final reply. A turn ends when the model stops or when the harness decides to stop it.

While a turn runs you can steer it with Enter or queue a follow-up with Tab or alt+enter. A queued follow-up becomes a new turn after the current one finishes. Interrupting with Esc aborts the turn and returns queued messages to the composer.

Threads and the active leaf

At any moment, one path through the session tree is active. That path is the thread. The active leaf is the current entry at the end of that path.

Branching creates siblings in the tree. /tree browses every entry, including abandoned branches. /branch copies history up to a chosen user message into a new session file. /fork duplicates the entire current session into a new file (no entry picker). There is no /clone command. The original session is never modified.

Context pressure and compaction

Models have a finite token window. As a session grows, the raw transcript may no longer fit. Veyyon compacts history into a smaller, information-preserving summary instead of truncating it.

Compaction preserves the goal card, active user instructions, recent turns, and a deterministic working-set of files touched. This lets a resumed session show the model what matters without forcing it to read the entire transcript.

Prefer /compact when you need a summary to retain state. Prefer the new_context tool when prior transcript is no longer useful and you want a clean window without summarization. See Tools reference.

Where the details live

• For session commands and storage, see Sessions.
• For branching, forking, and cloning, see Session branching.
• For plan mode and goal tracking, see Plan mode and goals.
• For how compaction works, see Compaction and project memory.
• For goal state and long sessions, see Goal state and long sessions.
• For contributor-facing internals, see Session and turn internals.

Permission model

Veyyon separates two questions when a tool wants to act:

• When must Veyyon ask you first? That is the approval mode.
• What may a shell command actually touch? That is the OS sandbox.

Together they decide whether a call runs, runs restricted, or pauses for your yes.

Approval modes

The approval mode is an autonomy ladder set with tools.approvalMode, overridable per run with --approval-mode <mode> (and --auto-approve / --yolo).

The legacy names always-ask (→ ask) and write (→ auto-edit) are still accepted.

Per-tool policy is a second layer: tools.approval maps a tool name to allow, deny, or prompt and wins over the mode for that tool. For example veyyon config set tools.approval '{"bash":"prompt"}' always prompts for bash even in yolo.

# ~/.veyyon/agent/config.yml
tools:
  approvalMode: auto-edit
  approval:
    bash: prompt
    read: allow

OS sandbox for shell commands

When Veyyon runs a shell command it can confine that process at the OS level so it can only touch what the task needs. Enforcement is platform-native:

• Linux — Landlock and seccomp, with bubblewrap providing the mount (and, when needed, network) namespace. A bundled bwrap is used when the system one is missing; Veyyon warns so you can install the OS package. User namespaces are required — WSL1 cannot create them, so use WSL2.
• macOS — a Seatbelt profile.

OS-level isolation is enforced by native code. If enforcement cannot be established, Veyyon fails closed — that is an error, not a silent run without confinement.

How they combine

The sandbox is the hard boundary; the approval mode is the interaction. A command the sandbox forbids does not run regardless of approvals. A command the sandbox permits may still pause for your approval, depending on the mode. Choose a permissive approval mode only alongside a sandbox you trust for the task.

Fail-closed behavior

When enforcement cannot be established, Veyyon fails closed rather than silently running unsandboxed. Silent fallback to a weaker boundary is treated as a bug. After changing approval or sandbox settings, verify enforcement with veyyon plugin doctor.

Spec — not shipped: the named sandbox policies (read-only, workspace-write, danger-full-access, external-sandbox) and the -a / --ask-for-approval policy names (untrusted, on-request, granular, never). Veyyon ships approval modes (tools.approvalMode) plus OS-level shell isolation, not a sandbox_policy config key.

Where the details live

• Sandbox and approvals for the deep reference and runtime commands.
• Using Veyyon safely for the honesty guarantees and the checks to run.
• CLI reference for the launch flags.

Model contract

The terminal engine is provider and API agnostic. You choose an endpoint, choose a model when that endpoint exposes model choice, provide the key, and Veyyon calls that API directly. The endpoint can be a local server (Ollama, LM Studio), a direct provider API (OpenAI, Anthropic, Google), or any OpenAI-compatible gateway.

This page is the contract between the harness and the model. For copy-paste provider setup, see Configuring providers. For day-to-day model switching, see Models and providers.

The three things you bring

A BYOK (bring-your-own-key) run needs three facts:

Veyyon does not route your requests through a service of its own for BYOK providers and does not add telemetry egress. The key is used only to talk to the provider you chose.

Example shape

# ~/.veyyon/agent/models.yml
providers:
  deepseek:
    baseUrl: https://api.deepseek.com
    api: openai-completions
    apiKey: DEEPSEEK_API_KEY   # env-var name or literal
    models:
      - id: deepseek-chat
        name: DeepSeek Chat
        contextWindow: 128000
        maxTokens: 8192

$ export DEEPSEEK_API_KEY=sk-...
$ veyyon --model deepseek/deepseek-chat

What the harness owns

These behaviors stay constant no matter which endpoint you point at:

• The workflow: read, edit, verify, stop when the work is done.
• Tool dispatch, argument handling, and edit verification through the hashline edit engine (with apply_patch / patch / replace available via edit.mode).
• OS-level shell isolation (Landlock/seccomp on Linux, Seatbelt on macOS) and approval modes.
• Context compaction, goal cards, session branching, and rollout persistence.
• Per-model prompt order and tool-form selection once a model (or API kind) is known.

You are not locked to any provider. Point the harness at any compatible API and keep the same commands.

What the provider owns

The provider owns the wire protocol, auth scheme, model list, rate limits, and the tokens it returns. Veyyon adapts to that surface through the provider’s api kind:

• Chat-Completions-style endpoints (api: openai-completions) talk /chat/completions.
• Responses-style and native provider endpoints use their own request shape.
• Model ids come from the provider’s discovery endpoint when discovery runs. There is no hardcoded allowlist for BYOK providers, and discovery fails loud rather than serving a silent empty list.

Everything beyond the built-in catalog is data in models.yml — see Providers and docs/providers.md.

System prompts and tool schemas

Each turn the harness builds a request that includes:

1. Base instructions for the active model or backend (execution order, stop-when-green, format-neutral tool guidance). See Execution-order prompts.
2. User and project instructions (AGENTS.md / SYSTEM.md layers and any session steers).
3. Tool schemas the model is allowed to call on this turn (bash, edit/write, web search, MCP tools, skills, and so on), filtered by approval mode, disallowed_tools, and feature flags.
4. Conversation context for the active thread, possibly compacted.

The model is expected to call tools using the schemas it was given. When arguments are almost right but malformed, hashline returns recovery hints so the model can retry inside the same turn budget.

Freeform vs Function tools

Veyyon advertises the structured edit tool in one of two shapes. The payload (the patch or edit body) is the same; only the transport differs.

The form is derived from the provider’s API kind by default; an optional catalog override can pin the apply_patch tool to function, freeform, or none. The Function form makes a structured edit tool real for chat-wire endpoints (Ollama, LM Studio, DeepSeek, and similar) that historically saw no Freeform tool at all. See The hashline edit engine for the default edit wire format.

Harness vs provider: a clear split

┌──────────────────────── harness (veyyon) ─────────────────────┐
│ session / turn loop                                           │
│ prompts, tool schemas, edit, sandbox, approvals, compaction   │
└────────────────────────────┬──────────────────────────────────┘
                             │ HTTPS / local HTTP
                             ▼
┌──────────────────────── provider ─────────────────────────────┐
│ endpoint auth + model discovery + completions/responses       │
│ model weights, rate limits, provider-side refusals            │
└───────────────────────────────────────────────────────────────┘

If something fails, ask which side owns it:

• Config rejected at load, malformed models.yml, missing key → harness / your config.
• HTTP 401 / 429 / empty model list → provider or key.
• Patch applied but tests red → harness did its job; the change still needs work.
• Sandbox denial → permission model, not the model provider.

Provider data at load time

For BYOK providers, model and provider entries are data in models.yml:

• A YAML or schema error makes the registry skip the custom file loudly; it does not silently drop models.
• Custom providers are merged alongside the built-in catalog. A custom entry with the same id as an implicit local engine (ollama, lm-studio, llama.cpp) replaces that engine’s discovery.
• Provider availability requires the id not be in disabledProviders and the provider be keyless or have resolvable credentials.

Malformed provider data fails at load. Silent fallback to a weaker provider is treated as a bug.

Per-role models

The conversation model (/model or --model) is separate from background roles. Roles are configured under modelRoles:

• modelRoles.task — default for spawned subagents unless an agent definition pins its own model.
• modelRoles.tiny (or smol) — lightweight background work (titles, memory, auto-thinking).

Precedence for subagents is explicit: an agent definition’s own model pattern wins, otherwise modelRoles.task, otherwise the conversation model. There is no silent blend. /status and veyyon plugin doctor report the effective values. See Models and providers.

Automation note

For non-interactive runs, pass the prompt and pick an approval mode that matches your trust boundary:

$ veyyon --approval-mode auto-edit "run the unit tests and fix failures"

Use --yolo (auto-approve everything) only in trusted automation, ideally with an outer sandbox.

What stays constant

• The workflow stays the same: read, edit, verify, and stop when the work is done.
• Edit verification, OS isolation, approvals, and context handling are harness behavior.
• You are not locked to any provider; point the harness at any compatible API.

Next

• Configuring providers — Ollama, LM Studio, Anthropic, and custom OpenAI-compatible endpoints.
• Models and providers — choosing and switching models in a session.
• Safety — boundaries around tool use and model output.
• Permission model — approval modes + OS sandbox.
• Signing in — interactive and env-var auth paths.

Core concepts

Veyyon is built around a few persistent, composable units. This page defines the units that shape a conversation and explains how they fit together.

Session

A session is the persisted unit of work. It holds a thread, a working directory, optional goal state, and a JSONL log on disk. When you run veyyon inside a repository, you start a new session. When you resume from the picker, you pick up an existing one.

Sessions are durable: they survive a TUI restart, a context compaction, or a machine reboot. The file on disk is the source of truth, not the in-memory state.

See Sessions for day-to-day commands and File locations for where the files live.

Thread

A thread is the conversation lineage inside a session. It is the sequence of turns from the start of the conversation to the current point. A session can contain more than one thread if you branch or fork.

The thread is the path the harness follows when it builds context for the next turn. It is not the same as the raw log file: the log file contains every entry, including branches you are no longer on.

Turn

A turn is one model pass. It starts with a prompt, runs through model inference, tool calls, approvals, and edits, and ends with a final response. The TUI and CLI display each turn as one back-and-forth block.

During a turn, Veyyon can dispatch tools, apply edits, run verification, and wait for user approval. A single turn may contain many tool calls, but it is still one turn because it is one top-level model invocation with a single final response.

How context history is preserved

Context history is preserved in two layers.

Rollout / JSONL storage

Every event in a session is appended to a rollout file as a JSONL line. The rollout file lives under the sessions directory below the config home (~/.veyyon/.../sessions/). Each line is a rollout item: a user message, an agent response, a tool call, a compaction, a goal update, or a leaf move.

Rollout files are append-only. Nothing is ever rewritten. This property makes branching and resume safe and auditable. See Sessions for day-to-day commands and Session and turn internals for the persistence format.

State database

Thread metadata, goal cards, and queued follow-ups are also mirrored into a local SQLite index. The index lets the harness list and resume sessions quickly without replaying the entire rollout log.

How context history is updated

A turn updates the thread by appending new entries to the rollout file. The in-memory view is rebuilt from the thread’s path through the log.

When a turn grows too long, the harness may compact the transcript. Compaction summarizes older turns into a smaller form while preserving the goal, recent user messages, file working sets, and verification facts. The compacted prefix is then used as the older context for later turns, while the recent tail remains intact. See Compaction & project memory for how summaries are built and what survives.

Relationships

• A session owns one or more threads and stores them on disk.
• A thread is a path through the session’s tree of turns.
• A turn is one step on that path.
• The rollout is the append-only log that contains every turn, branch, and system event.
• The state database is the runtime index for resume and active metadata.
• The goal card is a separate context slot that carries the current objective across turns and compactions. See Goal state.

Branching and forking

Because rollout files are append-only, branching does not delete or rewrite history. A branch is recorded as a new entry whose parent points to an earlier entry. The active leaf can be moved to any existing entry, and new turns start from there.

Use /tree to browse the session tree, /fork to copy history into a new session, /clone to duplicate the current branch, and /side to open a short-lived side thread. See Session branching for commands and behavior.

Plan mode

Plan mode changes how a turn behaves. In Plan mode, the agent is constrained to non-mutating investigation and planning; it cannot edit files or run mutating commands. It produces a <proposed_plan> that you approve before implementation begins. This makes a plan a first-class turn result, not just prose in the transcript. See Plan mode and goals.

What to remember

• A session is the saved work unit.
• A thread is the conversation path inside that session.
• A turn is one model pass with a beginning, middle, and end.
• Rollout files are append-only JSONL; the state database is the runtime index.
• Compaction preserves task-critical facts while shrinking the transcript.
• Branching and forking are safe because history is never rewritten.

How to read this book

This handbook has three kinds of chapters. Knowing which is which keeps the record honest.

Chapter status labels

Every chapter opens with a status line:

• Built & verified, the feature is shipped and works end to end.
• In progress, partially built; the chapter says exactly what works and what does not yet.
• Spec — not shipped, a mechanism with a clear target shape, documented with the failure mode it fixes. Spec chapters do not claim the work is done.

Conventions

• Provenance. When a technique is adapted from prior art, the source and its license are named briefly and collected in Acknowledgements. Veyyon adapts MIT/Apache code with attribution and studies proprietary code clean-room.
• Numbers have sources. A quoted measurement names who measured it. Veyyon’s own numbers are marked as such; cited third-party numbers are marked as theirs.
• The lever. Each optimization names which thesis lever it moves, edit format, control flow, or a supporting concern (cost, robustness, coherence). If it doesn’t move a lever, it doesn’t belong.

Features

Veyyon’s features are split into two groups: everyday interactions you use while working, and power-user customization tools that shape how the agent behaves.

Everyday features

• Cockpit customizes the status line and monitors multi-agent work; a terminal title composer and TUI pet are spec only.
• Keybindings remaps shortcuts and toggles Vim mode in the composer.
• Composer conveniences (prompt history, @ / / completion, empty-state hints, Esc interrupt) are documented in Quickstart and Keybindings.
• Web search lets the model look up current information from the web.

Power features

• Plan mode plans complex changes through grounded conversation before editing code.
• Skills are reusable capabilities defined on the filesystem and shared across projects.
• Plugins bundle skills, MCP servers, hooks, apps, and TUI customizations from marketplaces.
• Hooks run commands or inject context in response to lifecycle events.
• MCP connects Veyyon to external tools and data sources via the Model Context Protocol.
• Branching explores alternative paths by forking, cloning, or branching the session tree.
• Memory collects guidance and decisions from past runs to keep future threads consistent.
• Profiles bundle and switch between groups of configuration settings.
• Personalities changes the agent’s communication style without changing its capabilities.
• Export and import saves sessions to files and migrates settings from Claude Code.
• Connectors reach provider-hosted apps and data sources behind your account.

Task-oriented guides

Feature pages are reference-shaped. For goal-shaped recipes that stitch hooks, exec, MCP, skills, plugins, memory, and branching together, start with Task guides.

Where to go next

For command and file reference, see the Reference chapter. For how Veyyon is designed, see Foundations.

Editing and repair

Editing reliably is the core of a coding agent. Veyyon’s default edit surface is hashline: numbered lines from read/grep, snapshot tags, and edit with SWAP/DEL/INS operations.

For design background see Edits that land the first time and The hashline edit engine.

Why this matters

Models often emit slightly wrong tool JSON or stale line anchors. Hashline detects stale [path#TAG] tags and returns recovery hints. General schema repair runs on all tool calls before validation — see Repair overview.

Write path vs edit path

There is one hashline edit applier for anchored edits; write is intentionally separate for whole-file creation. Both honor the same approval and sandbox policy.

Tools

Set edit.mode to hashline, apply_patch, patch, or replace in config.yml, or PI_EDIT_VARIANT for one-shot overrides.

Hashline workflow

1. read (or grep) returns [relative/path#TAG] and LINE:text rows.
2. Model calls edit with sections anchored on the same TAG.
3. On success, output includes a fresh [path#NEW_TAG] and a compact diff.

write strips pasted hashline prefixes when appropriate and can mint new tags after whole-file writes.

Safety

Edits honor approval mode and sandbox roots like bash. Denied tools are removed from the model’s tool list via disallowed_tools / plan mode.

Spec — not shipped: a single V4A applier that routes every mutation through a make_update_patch envelope. Veyyon uses hashline as the primary path; apply_patch is a compatibility mode.

Sandbox and approvals

Spec — not shipped: the OS-enforced sandbox described on this page — Landlock/seccomp on Linux, Seatbelt on macOS, bundled bwrap, the read-only / workspace-write / danger-full-access / external-sandbox policies, and the -s / --sandbox, --full-auto, and --dangerously-bypass-approvals-and-sandbox flags. Veyyon does not ship an OS-level command sandbox yet. What ships today is the tools.approvalMode autonomy ladder that decides when the agent pauses before write and exec tools: plan (read-tier tools only), ask (prompt before write/exec), auto-edit (auto write, prompt exec), yolo (auto-approve all). Set it with --approval-mode <mode>, --auto-approve (alias --yolo), or tools.approvalMode in config.yml. Read the rest of this page as the reference for the target sandbox model.

Veyyon separates two questions: what a command is allowed to touch (the sandbox) and when Veyyon must ask you first (the approval policy). Together they decide whether a tool call runs automatically, runs inside a restricted environment, or waits for your yes.

This page is the deep reference. For the short mental model, see Permission model. For the approval UX walkthrough, see Permissions and approvals. For the honesty guarantees, see Safety.

Two controls, one decision

A command the sandbox forbids never runs, regardless of approvals. A command the sandbox permits may still pause for your approval. Choose a permissive approval policy only alongside a sandbox you trust for the task.

Sandbox policies

The sandbox bounds filesystem and network access for commands the agent runs.

Set it in config.yml, with -s / --sandbox <policy>, or per run with -c sandbox_policy=....

Additional writable roots for a single run:

$ veyyon --print --sandbox workspace-write --add-dir /tmp/veyyon-scratch "…"

Defaults you should expect

• Interactive veyyon: prefer a bounded sandbox (workspace-write for normal coding) plus an approval policy that still asks for risky work (on-request or untrusted).
• Headless veyyon --print: approvals default to never (no TTY to answer), so the sandbox is the containment. Prefer --sandbox workspace-write (or read-only) explicitly in CI.
• Network egress is off by default for read-only and workspace-write. Enabling network is a deliberate permission change, not an ambient side effect of “running a command.”

How enforcement works per OS

Veyyon does not implement a toy “please don’t touch that file” filter as its only defense. It builds and applies a platform sandbox so a command can only touch what the active policy permits. If enforcement cannot be established, Veyyon fails closed — that is an error, not a silent run-without-confinement.

Linux — Landlock, seccomp, and bubblewrap

On Linux the platform sandbox type is Linux seccomp (with Landlock / bubblewrap in the helper):

1. Veyyon self-invokes a helper (veyyon-linux-sandbox) with the permission profile, policy cwd, and command cwd.
2. The helper applies the profile: bubblewrap provides the mount (and, when needed, network) namespace; seccomp restricts syscalls; Landlock (including a legacy Landlock path) further constrains filesystem access when selected.
3. A bundled bwrap is used when the system bubblewrap is missing; Veyyon warns so you can install the OS package. If user namespaces are unavailable, you get an explicit warning — sandboxing needs them.
4. WSL1 cannot create the required user namespaces; use WSL2 for sandboxed shell commands. Veyyon surfaces this instead of pretending confinement worked.

Managed / proxy-only networking (when configured) requires bubblewrap’s isolated network namespace and the helper flag that allows proxy egress only — not a silent hole in the default deny.

macOS — Seatbelt

On macOS the platform sandbox type is Seatbelt. Veyyon launches the command under a Seatbelt profile derived from the permission policy (base profile plus network policy). Filesystem and network isolation come from the OS sandbox, not from hope.

Windows — restricted token (when enabled)

On Windows, when Windows sandboxing is enabled, Veyyon can use a restricted-token sandbox. Unsupported configurations fail with an explicit reason rather than falling back to full access.

external-sandbox

Use this when the process is already inside Docker, a VM, or another outer jail. Veyyon will not double-wrap; it trusts the outer boundary and still honors the network setting you provide. Pair with headless approvals carefully — the outer jail is doing the hard work.

Network egress

Network policy is separate from “can the shell start.”

Practical guidance:

• Keep network off for pure local edit/test loops.
• Enable network only when the task needs package downloads, API calls, or live search — and prefer asking (untrusted / on-request) the first time in an unfamiliar repo.
• In CI, prefer a runner firewall or external-sandbox plus an explicit allowlist at the job layer; do not rely on the model to “be careful.”

Approval policies

The approval policy decides when a command or sensitive tool action is shown to you before it runs. Set it with -a, --ask-for-approval <policy> or in config.

What the approval prompt looks like

Veyyon would like to run a shell command

Command:  npm test
Directory: /home/you/proj
Sandbox:   workspace-write

[y] yes   [n] no   [a] always for this session   [p] show policy

Veyyon would like to edit a file

File:      src/main.rs
Sandbox:   workspace-write
Change:    update the function signature and add a null check

[y] yes   [n] no   [a] always for this session   [p] show policy

• y — run once.
• a — allow this kind of action for the rest of the session.
• n — deny; the model is told so it can try another approach.
• p — show the active policy details.

Trust/allowlists also come from execpolicy .rules files (user and project). In automation you can skip loading them with veyyon --print --ignore-rules when you want a hermetic policy (see Non-interactive mode).

How they combine (recipes)

Never pair danger-full-access with never unless the environment is disposable and the inputs are fully trusted. That combination removes both containment and human review.

Deprecated: --full-auto

On veyyon --print, --full-auto is a legacy compatibility trap. It prints a warning and maps to --sandbox workspace-write behavior. Prefer the explicit flag:

$ veyyon --print --sandbox workspace-write "run the unit tests and summarize failures"

Do not document new automation as --full-auto.

Dangerous escape hatch

$ veyyon --print --dangerously-bypass-approvals-and-sandbox "…"

(--yolo is an alias.) This skips confirmation prompts and sandboxing. Intended solely for environments that are externally sandboxed. Prefer external-sandbox when you can express the outer jail cleanly.

Extending the boundary at runtime

You can widen read access or escalate without editing config.yml mid-thought:

Use profiles for repeatable combinations (for example a reviewer profile with read-only + untrusted).

Fail-closed behavior

Security-control failures are operator-visible:

• Missing Linux sandbox helper → error, not unsandboxed execution.
• Seatbelt unavailable off macOS → unsupported operation, not a silent skip.
• Bubblewrap / user-namespace problems → warning or hard failure depending on whether the policy requires a platform sandbox.
• WSL1 → explicit unsupported message pointing at WSL2.

Treat a silent fallback to a weaker boundary as a bug. After changing sandbox or approval settings, confirm the active tools.approvalMode in /settings (Advanced → Safety).

Choosing settings (checklist)

1. Is the repo trusted? If no → read-only + untrusted.
2. Does the task need writes? If yes → workspace-write, keep network off until needed.
3. Are you headless? If yes → set --sandbox explicitly; do not rely on interactive approvals.
4. Is there an outer jail? If yes → external-sandbox (or --dangerously-bypass-… only when you understand the outer jail).
5. Would a wrong rm -rf hurt? If yes → never combine full access with never.

See also

• Safety — honesty guarantees and what to verify.
• Permissions explainer — approval UX.
• Non-interactive mode — CI flags (--ignore-user-config, --ignore-rules, sandbox).
• CLI reference — launch flags.
• Exit codes — how failures surface in scripts.

Permissions and approvals

Spec — not shipped: the named sandbox-policy vocabulary on this page (read-only / workspace-write / danger-full-access / external-sandbox) and the -s / --sandbox and -a / --ask-for-approval flags. The shipped control is the tools.approvalMode autonomy ladder — plan, ask, auto-edit, yolo — set with --approval-mode <mode>, --auto-approve / --yolo, or tools.approvalMode in config.yml. The approval-flow UX below is accurate; the sandbox-policy tables are the target shape. See Sandbox and approvals for the same distinction.

Veyyon can run commands and edit files on your behalf. Two controls shape that power: the sandbox (spec) decides what a command is allowed to touch, and the approval policy decides when Veyyon pauses to ask you first. This page explains the user-facing flow, the choices, and how to combine them. For the complete reference, see Sandbox and approvals.

Why two controls?

The sandbox is a hard boundary. It says “this command may read here, write there, and reach the network, and nothing else.” The approval policy is an interaction choice. It says “this kind of action should stop for a yes before it runs.” A command that the sandbox forbids never runs, even if the approval policy would allow it. A command that the sandbox allows may still ask you, depending on the policy.

Separating the two lets you pick the right trade-off for the task. You can be strict on both, permissive on one but strict on the other, or fully hands-off for trusted automation.

The approval flow

When Veyyon wants to run a command or edit a file, it shows a short prompt. The prompt tells you what is about to happen, where, and under which policy. You choose whether to allow it once, allow it for the session, or deny it.

A typical command prompt looks like this:

Veyyon would like to run a shell command

Command:  cargo test
Directory: /home/user/my-project
Sandbox:   workspace-write

[y] yes   [n] no   [a] always for this session   [p] show policy

A file-edit prompt looks like this:

Veyyon would like to edit a file

File:      src/main.rs
Sandbox:   workspace-write
Change:    update the function signature and add a null check

[y] yes   [n] no   [a] always for this session   [p] show policy

If you choose y, the action runs once. If you choose a, the same kind of action in the same session runs without asking again. If you choose n, the action is cancelled and Veyyon tells the model so it can try a different approach. p shows the active policy details.

Sandbox backends

The sandbox bounds filesystem and network access. There are four backends.

On Linux, read-only and workspace-write are enforced with Landlock and seccomp. On macOS, they use the Seatbelt profile. Where the system sandbox is unavailable, Veyyon uses a bundled bwrap mount namespace. If enforcement cannot be established, Veyyon fails closed rather than running unsandboxed.

Approval policies

The approval policy decides when Veyyon stops for permission. Set it in configuration or per run with -a, --ask-for-approval <policy>.

The granular policy is useful when you want one behavior for some tools and another for others. For example, you can let tests run automatically while still requiring approval for file edits or network calls.

How the two combine

The sandbox is the last line of defense; the approval policy is the speed bump. Choose a permissive approval policy only when the sandbox already limits damage.

• Exploring an unfamiliar repo: read-only + untrusted. Veyyon can read and search, but cannot write or run anything risky without asking.
• Everyday coding: workspace-write + on-request. Veyyon can edit files in the project and run commands, but it asks for anything risky.
• Trusted CI automation: workspace-write or read-only with headless never ask (the default for veyyon --print). The run completes without interruption, and the sandbox still limits what can be touched.
• Dangerous work: danger-full-access + untrusted. The sandbox is gone, so every risky action must be approved by you.

Never pair danger-full-access with never unless the environment is disposable and the inputs are fully trusted. That combination removes both containment and human review.

Tuning trust for a session

You can change the boundary without editing a file.

• -c sandbox_policy=read-only or -a untrusted overrides the policy for a single run.
• veyyon --print defaults to never ask in headless mode with the active sandbox, so automation runs unattended but still bounded. --full-auto is deprecated; prefer explicit --sandbox.
• /sandbox-add-read-dir <absolute_path> grants read access to a directory for the current session.
• /elevate-sandbox walks you through setting up the elevated sandbox when a task needs more than the default.
• /reload re-reads the configuration file after you edit it, so you can update policies without restarting Veyyon.

Use profiles for repeatable combinations. For example, a reviewer profile can use read-only + untrusted, while a deploy profile uses workspace-write + never inside a CI runner that already has an external sandbox.

What to verify

After changing approval settings, confirm the active tools.approvalMode in /settings (Advanced → Safety). A silent fallback to a less restrictive state is treated as a bug. See Safety for the broader guarantees and how to inspect what Veyyon has done.

Safety

Veyyon is allowed to act on your machine, so the boundary has to be explicit — and visible.

Commands and file writes run through approval policy and sandbox policy. The approval policy decides when Veyyon pauses for permission. The sandbox policy decides what commands may read, write, or reach on the network. If Veyyon cannot prove the requested behavior fits the active boundary, it fails closed or asks. Silent degradation is treated as a product bug.

Deep policy reference: Sandbox and approvals. Mental model: Permission model. Product framing: Safety and honesty you can see.

The honesty story

An agent that silently weakens its boundary is hard to trust. Veyyon is designed so you can see:

Tool calls follow the same rule as shell. A recoverable malformed call can be repaired against the advertised schema; an unrepairable call is reported back to the model with coaching and is not dispatched as garbage. Output truncation, disabled safety nets, bad configuration, and missing provider data are operator-visible conditions.

What Veyyon refuses

Veyyon would rather miss a fix than invent one:

• Ambiguous argument repair — if two repairs are plausible, the call fails instead of guessing.
• Stale patch hunks — update context that no longer matches the file is rejected before write.
• Non-unique exact edits — oldText that matches many places is rejected with a count and coaching.
• Sandbox / helper setup failures — no “run unsandboxed just this once” fallback.
• Destructive Git as a way to “clean uncertainty” — treat a dirty worktree as normal active context; inspect with git status --short, git diff, and git diff --cached. Do not ask Veyyon to clear uncertainty with git reset --hard, git checkout --, git restore, or git clean.

Approvals you can see

When a command or edit needs approval, the prompt shows what is about to run, where, and under which sandbox. You can allow once, allow for the session, deny, or inspect the policy. Denied actions return to the model so it can change approach — they do not silently become success.

In headless veyyon --print, approvals default to never (there is no interactive prompt). Containment is then the sandbox you pass (--sandbox workspace-write is the usual CI choice). See Non-interactive mode.

Trust, allowlists, and rules

If you decline directory trust during onboarding, Veyyon exits with next-step advice instead of a silent quit: project-local config, hooks, and exec policies stay unloaded until you trust the workspace. You can re-run and accept trust, or explore without trusting via veyyon -a untrusted -c sandbox_policy=read-only. On Windows, when sandboxing is disabled by config, the trust prompt says so and continues in standard mode rather than implying a sandbox will be created immediately.

On first-run welcome, if a newer install is already known from the update cache, Veyyon shows an Update available badge while the background version probe refreshes.

• Keep approvals enabled when working in repositories you do not fully trust.
• Prefer exact workspace roots and explicit provider config over ambient shell state.
• Execpolicy .rules files (user and project) can allowlist or require prompts for command classes. For hermetic CI, veyyon --print --ignore-rules skips loading them; --ignore-user-config skips $VEYYON_HOME/config.yml while auth still uses VEYYON_HOME.
• Network egress stays off by default in bounded sandboxes; turn it on deliberately.

What to check

• Run veyyon plugin doctor after install and after changing provider or sandbox configuration. It exits non-zero when a check fails — treat that as a real setup problem.
• Confirm the active sandbox and approval policy (/status, approval p, or the exec startup line).
• Prefer workspace-write (or read-only) over danger-full-access unless the machine is disposable.
• Never combine danger-full-access with never outside a disposable, externally controlled environment.
• Treat a silent fallback as a bug: if confinement or credentials disappeared without a message, that is not “working as intended.”

Risk surfaced in the loop

Risk is not only a startup checkbox:

1. Before — policy + sandbox chosen; doctor can verify readiness.
2. During — approvals, sandbox denials, repair refusals, and truncated outputs appear in the turn.
3. After — turn diffs and (for veyyon --print --json) structured events record what ran, what failed, and what the final message was.

Next

• Configuration — set the policies Veyyon will enforce.
• Sandbox and approvals — OS backends, egress, recipes.
• Editing and repair — why refused repairs protect your tree.
• Diagnostics — diagnostics options and exit status.

Models and providers

This page is the day-to-day guide for choosing and switching models. Veyyon is provider/API agnostic: you choose the endpoint, choose the model when that endpoint exposes model choice, supply the key, and Veyyon calls that API directly. The endpoint can be a local server, a direct provider API, or a compatible gateway.

• Contract (what the harness owns vs the provider): Model contract
• Copy-paste provider setups: Configuring providers
• Built-in provider stack internals: Provider stack and BYOK

Bring your own key

When you use a non-managed BYOK provider, Veyyon does not route your requests through a service of its own and does not add telemetry egress. It uses your key only to talk to the provider you chose.

Set the key through:

• The provider’s environment variable (see Providers for the full map), or
• /login inside the TUI, which stores the credential in the auth store, or
• A models.yml apiKey on a custom provider (env-var name or literal).

See Signing in for storage modes and Configuring providers for full models.yml examples.

Minimal BYOK shape

# ~/.veyyon/agent/models.yml
providers:
  deepseek:
    baseUrl: https://api.deepseek.com
    api: openai-completions
    apiKey: DEEPSEEK_API_KEY
    models:
      - id: deepseek-chat
        name: DeepSeek Chat
        contextWindow: 128000
        maxTokens: 8192

$ export DEEPSEEK_API_KEY=sk-...
$ veyyon --model deepseek/deepseek-chat

Built-in providers

Veyyon ships a large built-in catalog (Anthropic, OpenAI, Google, Groq, OpenRouter, Mistral, xAI, Bedrock, and many hosted gateways) plus three auto-discovered local engines. A provider becomes selectable when it is not in disabledProviders and it is keyless or has resolvable credentials.

Once a provider is available, model ids come from its discovery endpoint — there is no hardcoded BYOK allowlist. Discovery fails loud rather than serving a silent empty list.

Local models: Ollama and LM Studio

Both are discovered automatically once the engine is running; no models.yml entry and no key are required.

$ ollama serve
$ ollama pull llama3.2
$ veyyon                # then /model and choose an ollama/… entry

$ lms server start
$ veyyon                # then /model and choose an lm-studio/… entry

Override the base URL with OLLAMA_BASE_URL / LM_STUDIO_BASE_URL if a daemon listens elsewhere. An explicit models.yml entry for one of these ids replaces its built-in discovery.

Mid-session model switch

Switching the interactive model mid-session never blends through a fallback chain into the subagent or compaction model. /status shows all effective models. veyyon plugin doctor warns about missing external binaries and keys.

$ veyyon --model openai/gpt-5
# later, inside the TUI:
/model deepseek/deepseek-chat
/status

Model selection: three explicit slots

Veyyon separates the model you talk to from the models that work in the background. There are three explicit slots, each set on its own — no default model stands in for the others:

• Interactive model — the conversation you are in. Chosen with /model (or --model for a run).
• Subagent model — task subagents. Set once in settings (subagent.model).
• Compaction model — context compaction. Set once in settings (compaction.model).

Leave a background slot unset and it uses the interactive model. Switching the interactive model mid-session never blends through a fallback chain into the background slots. /status shows all effective models.

# ~/.veyyon/agent/config.yml
model: openai/gpt-5               # interactive
subagent:
  model: deepseek/deepseek-chat
compaction:
  model: openai/gpt-5-mini

Roles (optional)

If you want named model assignments for specific work types (planning, review, …), configure roles in settings → Models → Roles. Roles are optional, scoped per profile, and live in settings — not the model picker. default is not a role or a model. See Models, roles, and profiles.

The harness adapts to the model

A model does not run in a generic harness. Prompt order, repair enablement, and tool exposure can be tuned per model via harness profiles (MVP) and model roles. You choose the model; Veyyon applies defaults that match how that model behaves. See Execution-order prompts and Model contract.

Per-model harness profiles (MVP)

Optional overrides in config.yml or ~/.veyyon/agent/harness-profiles.yml:

harness:
  profiles:
    "openai/gpt-4.1":
      repair: true
      tools: ["read", "edit", "grep", "bash", "write"]

Keys: exact provider/model-id or provider/*. See Per-model repair posture. Full backends.toml posture tables remain Spec.

Switching providers

Switching providers does not change how you work. Set the key for the new provider, choose its model, and continue. Your workflow, tools, sandbox, and approvals stay the same. There is no lock-in, because there is nothing holding you to one vendor.

$ export OPENROUTER_API_KEY=...
$ veyyon --model openrouter/anthropic/claude-sonnet-4

Comparison guidance: how to choose

Use this as a starting heuristic, not a benchmark claim. Always verify against your own tasks.

Rough capability vs cost/latency trade-off:

capability
    ^
    |  frontier hosted
    |        *
    |              mid-tier hosted
    |                   *
    |                        local 30B+
    |                             *
    |                                  small local / flash
    |                                       *
    +----------------------------------------> cost / latency
         (pay more / wait more)     (cheap / fast)

Pin models explicitly in CI and shared profiles (--model, modelRoles). Floating “latest” aliases are convenient interactively and risky in automation.

Where to go next

• Configuring providers — full copy-paste setups.
• Model contract — harness vs provider boundary.
• Getting started — first key and first task.
• Configuration — model defaults and overrides.
• Authentication — login, logout, secret storage.

Sessions

A Veyyon session is the unit of interactive work. Start one in the repository you want to modify:

veyyon

The session records turns, tool activity, approvals, edits, and verification output. Long-running work should survive context pressure through explicit goal state, compacted history, working-set facts, and resume metadata rather than relying on the model to remember everything from raw transcript text.

Common session actions

• Start fresh with veyyon.
• Continue saved work from the session picker on launch, or /resume inside the TUI.
• Branch a previous conversation with /branch (from a chosen user message) or duplicate the whole session with /fork.
• Manage saved sessions with /session; garbage-collect old artifacts with veyyon gc.
• Run a bounded non-interactive task by passing a prompt: veyyon "…".

Spec — not shipped: top-level veyyon resume / fork / archive verbs. Veyyon resumes from the launch picker or /resume, and branches with /branch / /fork (there is no /clone).

Long work

For large tasks, make the desired outcome explicit. The harness should preserve active instructions, recent turns, working files, verification facts, and unresolved blockers through compaction. When a session resumes, Veyyon should make the important state visible to the next model turn instead of presenting a clean-looking summary that dropped the real constraint.

Session files are trees

A session file (~/.veyyon/agent/sessions/**/<timestamp>_<id>.jsonl) is an append-only log, but its entries form a tree. Every recorded line carries an id and a parent_id, and a leaf_move line moves the session’s active leaf to any earlier entry, so the next recorded entry starts a sibling branch from that point. Nothing is ever rewritten: branches you navigate away from stay in the file, and resuming a session materializes only the entries along the active path (for a session with no branches, that is the entire file, exactly as before).

Two properties are guaranteed by the storage layer:

• No history rewriting. Branching appends a pointer move; abandoned entries remain addressable.
• Fail closed on corruption. A file whose linkage is broken (duplicate ids, unknown parents, a leaf move to a missing entry) refuses to load with an error naming the bad entry, rather than silently flattening or truncating the conversation.

Session files written by older Veyyon versions have no linkage fields; they load as a linear chain, which is the exact shape they recorded.

Navigating the tree

Run /tree in the TUI to browse every entry of the session, including branches you previously abandoned. Picking an entry opens a small action menu:

• Jump here continues from that point. For a user message the jump lands just before it and places the full message text in the composer, ready to edit and resubmit; the start of conversation resets to an empty conversation with the original prompt recalled; anything else (an agent reply, a compaction) branches from that entry with an empty composer.
• Label… attaches a short free-text label to the entry so you can find it again later. Labels render as [label] tags in the tree; the corresponding tui option in config.yml also shows when each label was set. Submitting empty text, or picking Clear label, removes it.

The tree view filter modes (treeFilterMode in config.yml, also toggled in the /tree UI) are:

Typing filters rows by preview and label text. There is no separate Conversation/User/Labeled/All tab chrome beyond these filter modes — see Branching.

Forking and branching to a new file

/fork and /branch both create a new session file and never modify the original; /tree navigation above stays inside the current file.

• /fork duplicates the entire current session — every entry, including sibling branches — into a new persisted file. There is no entry picker; for a slice from a chosen point, use /branch. veyyon --fork <session-id> does the same at startup, and the launch session picker forks a recorded session the same way.
• /branch picks an earlier user message and copies the history up to that point (or resets to a fresh root if the picked message is the first one) into a new session file, then recalls the message text into the composer for edit-and-resubmit.

There is no /clone slash command in the shipped registry.

Labels are stored in the session file itself as append-only bookkeeping lines (last write wins), so they survive resume and never rewrite history.

Exporting a session

/export writes a copy of the current session to a file you keep, for backup, inspection, or moving a conversation between machines. The copy is the session’s rollout file (append-only JSONL, Veyyon’s own portable session format), so it is faithful and self-contained.

• /export: copy to the session’s working directory under the rollout’s own file name.
• /export <path>: copy to <path>. The path may be absolute, relative to the working directory, or ~-prefixed; if it names an existing directory, the rollout’s file name is used inside it.

The command reports the destination and the number of bytes written, and never modifies the live session.

Programmatic access uses the Agent Control Protocol (veyyon acp) or SDK embedding; no separate daemon is required. Session tree operations in the TUI use /tree, /branch, and /fork.

Typing while the agent works

Input entered during a running turn goes to one of two places, and the bottom pane always shows which:

• Steer (Enter). The message is injected into the current turn: the model sees it at the next tool boundary and adjusts course without abandoning its work.
• Queue a follow-up (Tab, or alt+enter). The message is queued on the server and starts a new turn once the current one finishes. Follow-ups survive TUI restarts and session resumes because the queue lives with the session, not the client. Slash commands and ! shell escapes queue client-side instead; they are local actions, not model input.

Queued follow-ups render under the composer (“Follow-ups queued to run after this turn settles”) until they are delivered. They are never delivered after an interrupt: pressing Esc aborts the turn and pulls every queued follow-up back into the composer so nothing you typed is lost. To edit a queued follow-up without interrupting, press the edit-queued-message chord (alt+up by default, also shift+left): the most recent follow-up returns to the composer and older ones stay queued.

Delivery is governed by steeringMode and followUpMode (both one-at-a-time by default; set to all to deliver every queued message at the next boundary):

# ~/.veyyon/agent/config.yml
steeringMode: all
followUpMode: all

Programmatic clients use turn/followUp to queue a follow-up on an active thread and thread/followUps/recall to take every queued follow-up back off the queue (the response returns the recalled messages). Queueing an empty message is refused loudly.

Next

Read Examples for concrete prompts and workflows.

Cockpit: monitoring multi-agent work

Veyyon’s interactive TUI is the primary cockpit. Today it shows one session at a time with a configurable status line, session tree navigation, background jobs, and optional swarm orchestration. A full IRC-style live multi-agent dashboard (model-per-subagent, drill-in panels) is not shipped yet.

Status line (built)

The bottom status bar summarizes model, path, git, tokens, cost, context, subagents, and related session state. Configure it in Settings → Appearance → Status Line, reached via /statusline (jumps straight to this group) or /settings, or in config.yml:

There are 24 built-in segment IDs (StatusLineSegmentId): pi, model, mode (plan/goal/loop indicators), path, git, pr, subagents, token_in, token_out, token_total, token_rate, cost, context_pct, context_total, time_spent, time, session, hostname, cache_read, cache_write, cache_hit, session_name, usage, and collab.

Shipped today: /statusline opens Settings pre-focused on the Status Line group (preset, separator, and toggles), and preset: custom + leftSegments/rightSegments in config.yml give full control over which of the 24 IDs appear and in what order.

Spec — not shipped: an in-TUI interactive picker that lets you toggle/reorder individual segment IDs without hand-editing config.yml (no per-segment checkbox/drag UI exists), a terminal title composer (/title), and terminal pets (/pets).

Session tree and branching (built)

Session files are append-only JSONL trees under ~/.veyyon/agent/sessions/. See Sessions.

Inter-agent messaging (built)

Subagents and the main agent can use the irc tool (send, wait, inbox, list) over a process-global mailbox. /btw runs an ephemeral side question; /tan and /omfg spawn background agents for tangential work.

Swarm extension (built)

@veyyon/swarm-extension runs multi-agent DAG workflows from YAML: pipeline, parallel, or sequential modes. Each agent is a full subagent with normal tools.

Standalone: veyyon-swarm path/to/swarm.yaml (bin from @veyyon/swarm-extension).

In the TUI: add the package to extensions, then:

/swarm run path/to/swarm.yaml
/swarm status <name>
/swarm help

State and logs persist under <workspace>/.swarm_<name>/ (state/pipeline.json, logs/*.log).

IRC-style live cockpit

Shipped: /cockpit (alias /hub) opens the Agent Hub overlay: every registered agent except Main, with status, unread IRC count, model badge, and drill-in transcript chat. Same surface as the app.agents.hub keybinding.

Spec — not shipped: full IRC-style dashboard with channel tabs, terminal title composer, and an interactive per-segment status-line picker (/statusline opens settings, not a picker — see above). Use /cockpit, /jobs, /tree, swarm status files, and the irc tool for multi-agent visibility today.

Keybindings and Vim mode

Remap TUI shortcuts from ~/.veyyon/agent/keybindings.yml (YAML map of action ID → chord or chord list). Run /hotkeys in a session to see active bindings.

Customize keybindings

app.model.cycleForward: Ctrl+P
app.model.selectTemporary: Alt+P
app.plan.toggle: Alt+Shift+P
app.history.search: []   # disable

Chord names match the UI (Ctrl+P, Alt+Shift+P, Shift+Enter). Older keybindings.json files migrate to .yml on load.

Common action IDs include app.model.cycleForward, app.model.select, app.plan.toggle, app.history.search, app.tools.expand, app.thinking.toggle, app.thinking.cycle (Shift+Tab), app.editor.external (Ctrl+G), app.message.followUp, app.retry, app.display.reset, and app.clipboard.pasteImage.

Engineering detail: docs/keybindings.md.

Slash commands

Spec — not shipped: a /keymap interactive remapper and nested [tui.keymap.*] tables. Veyyon uses keybindings.yml + /hotkeys instead.

Vim mode

When enabled in settings, the composer supports Normal/Insert modal editing (i, Esc, motions, operators). Toggle via the settings UI if exposed in your build.

Web search

Web search lets the model look things up while it works, using the provider’s native web_search tool. It is useful for current library versions, API details, and error messages that need a reference the model was not trained on.

Modes

Web search has four modes, set with the web_search config value:

Enabling it

For a single session, override the config value at launch:

$ veyyon -c web_search=live
$ veyyon -p -c web_search=live "what is the current stable Rust release?"

The web_search tool is then available to the model without a per-call approval prompt.

To set it persistently, put it in config.yml:

web_search: live

You can also scope it to a profile, so one profile searches live and another stays offline. A profile stores its own settings under its agent dir; set the key in that profile’s config.yml:

# ~/.veyyon/profiles/research/agent/config.yml
web_search: live

Provider support

Web search relies on the provider exposing the web_search tool. It is available on providers and models that implement it; on providers that do not, the setting has no effect. See Models and providers.

Approvals

With web search enabled, the tool runs without a per-call approval prompt, because it reads public web content rather than touching your machine. It is bounded by the selected mode: cached never makes a live request, live does. If you want the model to never reach the network, use disabled. See Sandbox and approvals.

Code review

Spec — not shipped: a standalone veyyon review subcommand and the approvals_reviewer / auto_review / review_model config keys. What ships today is the interactive /review slash command and the passive advisor runtime (--advisor, which reviews each turn and injects notes). For non-interactive or CI review, drive /review through veyyon --print with a review prompt. The /review and advisor sections below are real; the veyyon review CLI and auto-review config are the target shape.

Veyyon can review code changes as a first-class task, separate from an ordinary chat turn. A review reads a set of changes, reasons about them against review instructions, and reports the issues it finds.

Non-interactive review (spec: veyyon review)

The veyyon review subcommand below is the target CLI shape. It selects the changes to review with mutually exclusive flags:

You can also pass a positional prompt with custom review instructions; pass - to read the instructions from stdin. The change-selection flags and a custom prompt are mutually exclusive, so a run either targets a change set or follows a free-form instruction.

$ veyyon review --uncommitted
$ veyyon review --base main
$ veyyon review --commit 1a2b3c4 --title "Cache the parsed config"
$ echo "focus on error handling and missing tests" | veyyon review -

Like veyyon --print, review runs are scriptable and exit non-zero on failure, so you can gate CI on them. Prefer --sandbox workspace-write when you need bounded automation; --full-auto on exec is deprecated.

Worked walkthrough: review uncommitted work

Suppose you are mid-change on a config parser and want a second pass before you commit.

1. Confirm the working tree has the changes you care about:

$ git status -sb
## feature/config-cache
 M crates/core/src/config/mod.rs
?? crates/core/tests/suite/config_cache.rs

2. Run a review against that working tree:

$ veyyon review --uncommitted

3. Veyyon loads the staged, unstaged, and untracked diffs, runs the review model, and prints a human-readable summary. A typical successful run looks like this:

Overall: the cache path is sound, but the new helper fails closed incorrectly when the
override file is missing, and the unit test never exercises a malformed TOML value.

Full review comments:

- Missing file should not fail the whole load: crates/core/src/config/mod.rs:214-228
  When `model_catalog_json` points at a path that does not exist, the loader returns a
  hard error. Prefer a clear config diagnostic that names the path and continues with the
  bundled catalog, matching the other override keys.

- Add a malformed-TOML regression: crates/core/tests/suite/config_cache.rs:1-40
  The new test covers the happy path only. Add a case with a trailing comma (or similar
  invalid value) and assert the surfaced error names the file and key.

What to notice:

• The summary leads with an overall explanation, then a findings block.
• Each finding has a short title and a path:start-end location, then a body explaining the risk and the smallest fix.
• Empty findings still produce a fallback message rather than silent success with no output; treat a clean review as an explicit “nothing to report” result when you automate.

4. Fix the named issues, then re-run the same command until the review is clean enough to commit. For CI, capture the process exit status rather than scraping prose:

$ veyyon review --uncommitted
$ echo $?
0

Worked walkthrough: review a branch against main

Use --base when the interesting surface is “everything this branch introduces,” not just the dirty working tree.

1. Make sure you are on the feature branch and that main (or your integration branch) is reachable:

$ git switch feature/config-cache
$ git fetch origin main

2. Review the branch delta:

$ veyyon review --base main

3. Sample output for a branch that still needs tightening:

Overall: the branch improves cold-start latency, but the cache key ignores the active
profile, so two profiles can silently share stale catalog data.

Full review comments:

- Include profile in the cache key: crates/core/src/config/mod.rs:88-101
  `load_catalog_cached` hashes cwd and catalog path only. Two profiles with different
  `model_catalog_json` overrides can collide. Fold the active profile name (or the
  resolved override path) into the key.

- Document the invalidation rule: docs/handbook/src/using/models.md:40-52
  Operators need to know that changing the active profile busts the cache. Add one
  sentence next to the catalog override docs.

Compared with --uncommitted:

For pull-request bots, --base origin/main (or your repo’s default branch) is usually the right choice. Keep the working tree clean or stash local noise first if you want the review to match the pushed commits exactly; otherwise dirty files are not included unless you also use --uncommitted.

Custom instructions

When the default review rubric is too broad, pass a prompt instead of a change-selection flag:

$ veyyon review "focus on authz boundaries and secret handling in the diff against main"
$ echo "ignore style nits; report only correctness and missing tests" | veyyon review -

The prompt form is mutually exclusive with --uncommitted, --base, and --commit. If you need both a change set and custom instructions, prefer /review … in the cockpit, or phrase the prompt so it names the change set explicitly.

Interactive review (/review)

Inside the cockpit, /review reviews your current changes and surfaces the issues it finds without leaving the session. You can pass inline instructions to focus the review, for example /review look at the auth changes for missing input validation. The findings are reported in the conversation so you can act on them immediately.

/review is the right tool when you are already mid-session and want findings in context. veyyon review is the right tool for scripts, git hooks, and CI.

Auto-review guardian (Spec — not shipped)

Spec — not shipped: everything in this section is the target shape, not shipped behavior. There is no approvals_reviewer / auto_review / review_model config key, no continuous auto-review approval path, and no /auto-review or /approve command in the shipped registry today. Approvals are governed by tools.approvalMode (always-ask / write / yolo) and per-tool policy overrides; see Safety.

The target design would turn review into a continuous guardian. Instead of you approving each sensitive action, an auto-reviewer would inspect the agent’s proposed actions against a policy and approve or deny them, selected by setting the approvals reviewer to auto_review.

Target config shape (not read by Veyyon today):

# TARGET SHAPE — not implemented. Route approval decisions to the guardian
# instead of prompting the user.
approvals_reviewer: auto_review

# Extra policy instructions inserted into the guardian's prompt.
auto_review:
  policy: "Deny any command that deletes files outside the workspace."

The model used for auto-review would be configurable through review_model, defaulting to a dedicated review model rather than the main session model so the guardian’s judgment is independent of the agent it is reviewing.

When the guardian denies an action, the design calls for a retry path rather than silently dropping it: a /auto-review command (also /approve) would let the action proceed once without changing the standing policy. None of this exists in the shipped command registry.

See also: Safety for how review fits the shipped approval model (tools.approvalMode), Connectors and Apps for tool approval tiers, and Slash commands for the full command list.

Non-interactive mode (veyyon --print)

Spec — not shipped: a veyyon exec subcommand. Non-interactive mode is the --print launch flag (short -p): veyyon -p "prompt". JSON output is --json, and resume is --resume / --continue. The veyyon exec resume / veyyon exec review subcommand forms and several flags (--output-schema, --oss) below are the target shape; run veyyon --help for the current flag set. The JSON event schema and the recipe shapes are accurate.

veyyon --print (short -p) runs Veyyon without the interactive cockpit: give it one prompt, it does the work and exits. It is how you drive Veyyon from scripts, CI, git hooks, and other programs.

$ veyyon -p "add a unit test for parse_config and run it"
$ echo "summarize the diff on this branch" | veyyon -p
$ veyyon -p - <<'EOF'
Review src/auth.rs for missing error handling.
EOF

The prompt can be an argument or read from stdin. If stdin is piped and a prompt argument is also provided, stdin is appended as a <stdin> block.

Run veyyon --help for the generated, always-current flag set. This page documents the intended integration surface and recipes.

Flag reference

Session and config

Model and local OSS

Sandbox and trust

Headless exec defaults approval policy to never (no TTY to answer). The sandbox is therefore your containment — set it explicitly in CI.

--full-auto is deprecated

--full-auto is a legacy compatibility trap. It still parses on veyyon --print, prints:

warning: `--full-auto` is deprecated; use `--sandbox workspace-write` instead.

and maps onto workspace-write sandbox behavior. Do not use it in new scripts:

# preferred
$ veyyon --print --sandbox workspace-write "run unit tests and fix failures"

# deprecated (warns)
$ veyyon --print --full-auto "run unit tests and fix failures"

Output

Combine them: --json for the full trace, --output-schema when you need a fixed answer shape, -o when you only care about the final text.

Subcommands

veyyon exec resume

Resume a previous session by id or pick the most recent.

$ veyyon exec resume <SESSION_ID> "continue from the failing test"
$ veyyon exec resume --last "try the next approach"
$ veyyon exec resume --last --all "…"        # do not filter sessions by cwd
$ veyyon exec resume --last -i shot.png "what is in this screenshot?"

veyyon exec review

Run a code review against the current repository (non-interactive).

$ veyyon exec review --uncommitted
$ veyyon exec review --base main
$ veyyon exec review --commit abcdef1 --title "fix auth timeout"
$ veyyon exec review "Focus on unsafe blocks and unwrap()"

For a richer interactive review workflow, see Review.

--json event schema

Events are JSON Lines (type tag). Top-level ThreadEvent variants:

Item payloads (item → type, snake_case) include:

Example lines:

{"type":"thread.started","thread_id":"01234567-89ab-cdef-0123-456789abcdef"}
{"type":"turn.started"}
{"type":"item.completed","item":{"id":"item_3","type":"file_change","changes":[{"path":"src/lib.rs","kind":"update"}],"status":"completed"}}
{"type":"item.completed","item":{"id":"item_4","type":"agent_message","text":"Done."}}
{"type":"turn.completed","usage":{"input_tokens":1200,"cached_input_tokens":800,"output_tokens":200,"reasoning_output_tokens":0}}

Pipe into jq:

$ veyyon --print --json "…" | tee run.jsonl \
    | jq -r 'select(.type=="item.completed" and .item.type=="agent_message") | .item.text'

Exit codes

veyyon --print follows the handbook exit code contract:

A failure is never reported as 0, so veyyon --print … && next-step is safe in a pipeline.

CI and automation recipes

1. Hermetic unit-test fix loop

$ veyyon --print --sandbox workspace-write \
    --ignore-user-config \
    --ephemeral \
    --skip-git-repo-check \
    -m gpt-5-mini \
    "Run cargo test -p mycrate. Fix compile and test failures only. Stop when green."

2. PR review bot with JSON artifact

$ veyyon exec review --base origin/main --json \
    | tee review.jsonl

$ jq -r 'select(.type=="item.completed" and .item.type=="agent_message") | .item.text' \
    review.jsonl > review.md

Or constrain the final message:

$ cat > /tmp/review-schema.json <<'EOF'
{
  "type": "object",
  "required": ["findings", "verdict"],
  "properties": {
    "verdict": { "enum": ["approve", "request_changes", "comment"] },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["severity", "path", "summary"],
        "properties": {
          "severity": { "enum": ["P0", "P1", "P2"] },
          "path": { "type": "string" },
          "summary": { "type": "string" }
        }
      }
    }
  }
}
EOF

$ veyyon --print --sandbox read-only --json \
    --output-schema /tmp/review-schema.json \
    -o review-out.json \
    "Review the staged diff; return JSON matching the schema."

3. Pre-commit hook (staged diff only)

#!/usr/bin/env bash
set -euo pipefail
veyyon --print --sandbox workspace-write --ephemeral --json \
  "Review the staged diff. Fail the turn if you find a P0 bug; otherwise summarize." \
  | tee /tmp/veyyon-pre-commit.jsonl \
  | jq -e 'select(.type=="turn.failed") | length == 0' >/dev/null

4. Batch refactor across a path

$ veyyon --print --sandbox workspace-write -C "$REPO" \
    --add-dir /tmp/veyyon-scratch \
    "Rename FooConfig -> AppConfig under src/config/. Update call sites. Run cargo check."

5. Resume a long CI job

$ THREAD=$(veyyon --print --json --ephemeral "start the migration plan" \
    | jq -r 'select(.type=="thread.started") | .thread_id')
# … later …
$ veyyon exec resume "$THREAD" "continue; finish applying the plan"

(Omit --ephemeral if you need the session on disk for resume.)

Safety notes for automation

• Prefer --sandbox workspace-write or read-only over bypass flags.
• Use --ignore-user-config / --ignore-rules when the runner’s home directory must not affect the job.
• --dangerously-bypass-approvals-and-sandbox is for outer jails only — prefer external-sandbox when you can express that cleanly (Sandbox).
• Never commit API keys into CI logs; use the runner secret store and env_key.

See also

• Sessions — resuming and branching.
• Sandbox and approvals — policies for CI.
• Exit codes
• ACP / SDK for programmatic control.
• CLI reference

Themes and identity

Veyyon’s interface is built around near-black, near-white, and a persistent Veyyon silver accent (#B8BDC7).

Shipped themes

Spec — not shipped: Veyyon Light with inverted black/white poles and a persistent silver accent.

Changing theme

• Settings UI: /settings → Appearance → theme (or the theme picker on first run).
• Config: theme in ~/.veyyon/agent/config.yml (profile-specific when using --profile).
• Custom themes: drop JSON under ~/.veyyon/agent/themes/; schema in docs/theme.md.

Terminal capability detection maps the same hierarchy for truecolor, ANSI-256, ANSI-16, unknown background, and no-color modes. Reduced-motion settings remove decorative animation without hiding state changes.

What the theme covers

The contract applies to onboarding, composer, menus, dialogs, status line, markdown, tables, diffs, tool output, approvals, progress, and errors — not only the chat pane.

Identity elsewhere

• CLI binary: veyyon
• Config root: ~/.veyyon (PI_CONFIG_DIR overrides the directory name; XDG paths after veyyon config init-xdg)
• npm packages: @veyyon/*

Full brand rules: Brand and identity and the repo docs/brand-system.md.

Examples

Use Veyyon from the repository root for tasks where the harness can inspect files, edit, and verify.

Understand a code path

Explain how model/provider configuration is loaded and where an invalid setting is surfaced to the user.

Veyyon should read the relevant configuration files in your project, name the boundary where state enters, and point at tests or missing tests.

Make a small fix

Fix the config error so it names the invalid file and the setting to change. Add the regression test.

Veyyon should edit through hashline or write, run the focused test (bun test in the relevant package), and stop when the test proves the behavior.

Improve docs with code truth

Make the MCP setup page match the MCP config loader in this project. Verify against the schema.

Inspect the live schema source, update the handbook, and avoid claims not backed by code. Engineering notes live under docs/.

Review a change

Review the staged diff for correctness, security, missing tests, and public/private boundary leaks.

A useful review names concrete files and lines, separates correctness from style, and recommends the smallest fix that makes the behavior true. Use /advisor when a second model should comment on each turn.

Recover a malformed tool call

Use the edit tool with a stale hashline tag and observe the mismatch error.

Malformed tool JSON is repaired when the fix is unambiguous, otherwise it fails loudly with coaching rather than dispatching garbage. Hashline returns actionable stale-tag errors. See Repair overview.

Continue through long context

Keep the security requirement, touched files, and next action intact after compaction.

Use /compact with a focus string; goal mode (/goal) preserves objectives across compaction when enabled. See Compaction and memory.

Verify before claiming done

Run the package test gate for the area you changed.

Example: bun run test in packages/coding-agent or the project’s documented cargo_full / CI script from STANDARD.md when touching Rust natives.

Use the hosted model contract

Point Veyyon at a hosted model and rely on the same behavior contract every provider must satisfy.

See Model contract and Providers.

Plan mode and goals

Veyyon ships plan mode and goal mode as engine features. They are separate modes with different tools and continuation behavior.

Spec — not shipped: three enforced chat phases, <proposed_plan> cards, Shift+Tab collaboration cycling, and a plan_mode_reasoning_effort config key. Veyyon’s plan mode works as described below.

Plan mode (shipped)

Plan mode is read-focused exploration that drafts a plan file before you approve implementation.

Enabling

• Setting: plan.enabled (default true; toggle in /settings Advanced → Plan).
• Slash: /plan toggles plan mode; /plan <prompt> enters plan mode and submits the prompt.
• Related: /plan-review reopens plan review while plan mode is active.

Plan mode blocks goal mode and vibe mode (and vice versa).

Behavior

When plan mode is on:

1. Veyyon selects a plan file path (per-session) and sets mode state on the session.
2. Active tools are adjusted: resolve is added for plan approval; built-in write may be activated so the agent can draft the plan file.
3. The agent explores and writes the plan using read-oriented work plus plan-file write/edit as configured.
4. Finalization uses the resolve tool with plan approval semantics (plan_approval), not a <proposed_plan> XML tag.
5. Exiting: /plan again (with confirmation if a draft exists) pauses or disables plan mode; session records mode entries in the session file.

Plan mode uses the plan model role when configured.

Goals (shipped)

Goal mode tracks a persistent objective on a saved session and can auto-continue when idle.

Enabling

• Setting: goal.enabled (default true).
• Slash commands:
  • /goal set <objective> — create or replace goal
  • /goal show — status, tokens, budget
  • /goal pause / /goal resume
  • /goal drop — remove goal
  • /goal budget <N|off> — token budget
• /guided-goal — interview flow before enabling goal mode

Goal mode blocks plan mode and vibe mode.

Goal state

Stored on the session. Fields include:

id, objective, status, tokenBudget?, tokensUsed, timeUsedSeconds, createdAt, updatedAt

Statuses: active, paused, budget-limited, complete, dropped.

Goal tool

When goal mode is active, the agent can call the goal tool with ops: create, get, complete, resume, drop. Continuation prompts inject on idle turns per goal.continuationModes.

Walkthrough (real commands)

$ veyyon

/goal set Add workspace-write default for headless runs and document it in the handbook

Work in normal mode; use /goal show for progress. When blocked, /goal pause. When done, the agent should complete via the goal tool or you /goal drop.

Spec — not shipped (goal card richness)

Goal state and long sessions describes a richer goal card (verification ledger, working-set fields, reviewer carry-forward) as a future expansion layer. The shipped card is the bounded objective + budget + status model above.

See also

• Sessions — goals require a persisted session
• Context: goal state — architecture notes

Skills

Skills are reusable capabilities Veyyon can draw on. They are defined as data on the filesystem rather than compiled into the Veyyon binary. This structure lets you add, customize, and share capabilities without editing code.

For general information on Veyyon extension capabilities, see Tools, skills, and extension data.

Skill locations

Veyyon loads skills from several locations depending on the desired scope.

Other tools’ skills and config (on by default)

By default Veyyon also discovers skills, context files (CLAUDE.md, standalone AGENTS.md), rules, and MCP servers authored for other AI coding tools — Claude, Codex, Gemini, Cursor, opencode, Windsurf, Cline, and similar — found on disk. Your global CLAUDE.md and existing external skills load as a shared base layer, so Veyyon works with the config you already have.

To run Veyyon on its own config only, turn off the single toggle in Settings › Providers › Discovery › Import Other Tools’ Config, or set it in config.yml:

discovery:
  importForeignConfig: false

When it is off, those foreign sources are skipped entirely — they never appear in /skills, in the enable/disable list, or in the model’s context. When it is on (the default), the per-source toggles under skills.* (for example skills.enableClaudeUser) give finer control. Veyyon’s own AGENTS.md lives in .veyyon/ (project) and $HOME/.veyyon/agent (user); those are always read and are not affected by this toggle.

Profiles isolate skills

Each profile is a separate config root ($HOME/.veyyon/profiles/<name>/agent). Every skill source Veyyon owns — user skills, managed (auto-learn) skills, and plugin skills — resolves under that root, so profiles never share a skill directory:

• Switching profiles re-homes user and managed skills to the active profile.
• The discovery.importForeignConfig toggle and all skills.* settings are stored per profile, so one profile can import other tools’ skills while another stays clean.

Two things are shared on purpose: project skills (.veyyon/skills next to your code) belong to the repository, not a profile; and another tool’s own skill directory ($HOME/.claude/skills, …) is global to the machine — a profile cannot relocate it, so per-profile isolation there means each profile decides independently whether to import it (via discovery.importForeignConfig, which is stored per profile and on by default).

Skill structure

Each skill is defined in its own subdirectory containing a SKILL.md file.

The skill file (SKILL.md)

The SKILL.md file defines the skill’s system prompt instructions and must start with a YAML frontmatter block delimited by ---.

Here is an example SKILL.md file.

---
name: my-custom-skill
description: Performs a custom code audit or analysis.
metadata:
  short-description: Audit code for typical issues.
---

# My Custom Skill

Use this skill when analyzing source files. Ensure you focus on:
1. Logic errors.
2. Unhandled edge cases.

The frontmatter contains these fields.

• name: The name of the skill (optional). Defaults to the name of the parent folder.
• description: A description of what the skill does (optional).
• metadata: Nested metadata block (optional).
  • short-description: A short summary of the skill (optional).

Optional configuration (agents/openai.yaml)

You can configure dependencies, policy settings, and interface preferences by adding an agents/openai.yaml file in the skill’s subdirectory. This file name is inherited from oh-my-pi’s upstream skill format.

Here is an example agents/openai.yaml file.

interface:
  display_name: "Code Auditor"
  short_description: "Audit code for typical issues"
  brand_color: "#B8BDC7"
  default_prompt: "Audit the files in the current workspace"
dependencies:
  tools:
    - type: "command"
      value: "cargo check"
      description: "Checks Rust project compilation"
policy:
  allow_implicit_invocation: true
  products:
    - veyyon

The following fields are available in agents/openai.yaml.

• interface: TUI presentation settings (optional).
  • display_name: The display name shown in TUI lists (optional).
  • short_description: A short description (optional).
  • icon_small / icon_large: Filesystem paths to icons (optional).
  • brand_color: A hex color code or color name (optional).
  • default_prompt: Pre-filled text when launching the skill (optional).
• dependencies: List of tools needed for the skill (optional).
  • tools: A list of dependency blocks. Each block can specify a type (for example, command or url), a value (for example, the command name or URL), a description, an optional transport, an optional command path, and an optional url.
• policy: Restrict how the skill is invoked (optional).
  • allow_implicit_invocation: A boolean (defaults to true). If false, the skill will not be implicitly suggested or automatically injected by the model.
  • products: A list of product names to restrict the skill to (for example, veyyon). If set, the skill only loads for matching products.

Configuration

Skills are configured in the skills block of Veyyon’s config.yml file.

Include instructions

By default, Veyyon formats and appends system instructions for all active skills to the system rules block on every turn. You can disable this automatic injection.

skills:
  include_instructions: false

Enable or disable bundled skills

To disable all embedded system skills, use this configuration.

skills:
  bundled:
    enabled: false

Manage individual skills

You can selectively enable or disable individual skills by name or by their absolute path.

skills:
  config:
    - name: my-custom-skill
      enabled: false
    - path: /home/user/.agents/skills/other-skill/SKILL.md
      enabled: true

Interactive TUI controls

In the terminal user interface, you can manage and list skills interactively.

Slash commands

• /skills opens a selection menu with these choices.
  • List skills shows all active skills. Typing @ or $ (depending on whether the mentions_v2 feature is active) in the composer opens the mentions list directly.
  • Enable/Disable Skills opens a toggle list of all discovered skills. You can select individual skills to turn them on or off.

When you close the toggle list, the TUI displays a status message stating how many skills were enabled or disabled.

Related recipes

For goal-shaped “give the agent a new capability” flows that stitch skills with MCP and plugins, see Task guides.

Skills authoring

A skill is a folder that adds a reusable capability to Veyyon. This page explains how to write one from scratch. For background on how skills are discovered and loaded, see Skills.

Directory structure

Skills are placed on the filesystem according to the scope where they should apply. Veyyon loads skills from these locations in order:

Create a new skill by making a directory inside one of these scopes and adding a SKILL.md file. The name of the directory is the default name of the skill.

A skill directory may contain additional files:

my-skill/
├── SKILL.md
├── agents/
│   └── openai.yaml
└── scripts/, references/, assets/ ...optional

Only SKILL.md is required. The other files are loaded when the skill is active or when the model explicitly asks for them.

SKILL.md frontmatter

Every SKILL.md must begin with a YAML frontmatter block between --- lines.

---
name: my-skill
description: Describe what this skill does and when to use it.
metadata:
  short-description: Short summary shown in skill lists.
---

The frontmatter fields are:

• name: The skill identifier. Optional; defaults to the parent directory name. Use lowercase letters, digits, and hyphens. Keep it under 64 characters.
• description: A clear explanation of what the skill does and when it should be triggered. This is the main signal the model uses to decide whether to invoke the skill.
• metadata.short-description: A short summary shown in the TUI and other skill lists. Optional; keep it to one line.

Be specific in the description. A vague description makes the skill less likely to be selected at the right moment.

Writing the body

The body of SKILL.md is a Markdown document that contains the instructions, context, and workflow for the skill. The body is loaded only after the skill has been selected, so the frontmatter acts as the gate and the body acts as the guide.

Guidelines for the body:

• State the purpose at the top.
• List the conditions that trigger this skill.
• Provide a step-by-step workflow or a set of rules the model should follow.
• Include examples of inputs and expected outputs.
• Mention any bundled scripts, references, or assets and when to use them.
• Keep it concise. Long skills consume context and may be ignored. Split detailed reference material into files under references/ and link to them from SKILL.md.

Example body:

# Code review

Use this skill when the user asks for a review of a code change or pull request.

1. Check for logic errors, unhandled edge cases, and test coverage.
2. Verify that the change matches the project style and conventions.
3. Flag any breaking changes or missing documentation.
4. Report findings as a numbered list with file paths and line numbers.

Do not leave comments on external platforms unless the user explicitly asks for it.

Optional agents/openai.yaml

The agents/openai.yaml file controls how the skill appears in the TUI and how it may be invoked. It is optional but recommended for skills that users interact with directly.

Example:

interface:
  display_name: "Code Review"
  short_description: "Review code for quality and correctness"
  brand_color: "#B8BDC7"
  default_prompt: "Review the current diff"
dependencies:
  tools:
    - type: "command"
      value: "git diff"
      description: "Inspect local changes"
policy:
  allow_implicit_invocation: true
  products:
    - veyyon

Available fields:

• interface: Presentation settings.
  • display_name: Name shown in the TUI skill list.
  • short_description: One-line description shown in the TUI.
  • icon_small / icon_large: Paths to optional icons relative to the skill directory.
  • brand_color: A hex color or color name for the skill chip.
  • default_prompt: Pre-filled text when the skill is opened from the TUI.
• dependencies: Tools the skill needs.
  • tools: A list of dependency blocks. Each block may specify type, value, description, transport, command, and url.
• policy: Invocation restrictions.
  • allow_implicit_invocation: Whether the skill may be suggested or injected automatically. Defaults to true. Set to false to require explicit selection.
  • products: A list of product names that may load this skill (for example, veyyon). If omitted, the skill loads for all products that support it.

Registering in config.yml

Skills are configured under the skills section of config.yml. You can control whether skill instructions are included automatically, whether bundled skills are enabled, and which individual skills are on or off.

Disable automatic inclusion of all skill instructions:

skills:
  include_instructions: false

Disable all bundled system skills:

skills:
  bundled:
    enabled: false

Enable or disable individual skills by name or by absolute path:

skills:
  config:
    - name: my-skill
      enabled: true
    - path: /home/user/.agents/skills/other-skill/SKILL.md
      enabled: false

Worked example: a project-local skill

This example creates a skill inside a project that adds a custom onboarding check.

Create the skill directory:

mkdir -p .veyyon/skills/onboarding-check

Create .veyyon/skills/onboarding-check/SKILL.md:

---
name: onboarding-check
description: Review the project for missing onboarding files and recommend improvements.
metadata:
  short-description: Check onboarding completeness.
---

# Onboarding check

Use this skill when the user asks whether the project is ready for a new contributor.

1. Check that the project has a README, CONTRIBUTING guide, and LICENSE file.
2. Verify that the build command is documented and can be run from the README.
3. List any missing or incomplete files.
4. Suggest concrete additions that would help a new contributor start quickly.

Report the result as a short checklist with `done` or `missing` for each item.

Create .veyyon/skills/onboarding-check/agents/openai.yaml:

interface:
  display_name: "Onboarding Check"
  short_description: "Check project onboarding completeness"
  default_prompt: "Is this project ready for a new contributor?"
policy:
  allow_implicit_invocation: true
  products:
    - veyyon

Register it in the project config.yml:

skills:
  config:
    - name: onboarding-check
      enabled: true

Invoking the skill

In the TUI, you can invoke the skill in two ways:

1. Type /skills and select List skills, then choose Onboarding Check from the list. The default_prompt will be pre-filled if one is configured.
2. Type a natural request such as “Is this project ready for a new contributor?” in the composer. The model reads the skill description and selects the skill automatically when the request matches.

From a command-line invocation, refer to the skill by its name. The exact command depends on the Veyyon CLI version; run veyyon --help or see the CLI reference for the current syntax.

Plugins

Veyyon supports extending the agent’s capabilities with plugins. A plugin can add custom skills, Model Context Protocol (MCP) servers, applications, lifecycle hooks, and terminal user interface (TUI) customizations.

Plugin Structure

Every plugin is a directory with a .veyyon-plugin/plugin.json manifest file. The manifest describes the plugin’s metadata and lists its integration points.

Plugin Manifest (plugin.json)

The following fields are defined in the plugin.json schema:

Marketplaces

Marketplaces are collections of plugins. A marketplace is a directory or Git repository containing a marketplace.json catalog manifest.

Veyyon checks the following relative paths under a marketplace root to locate its catalog manifest:

1. .agents/plugins/marketplace.json (canonical path)
2. .agents/plugins/api_marketplace.json
3. .claude-plugin/marketplace.json

The marketplace catalog defines:

• A name and optional presentation metadata.
• A plugins list. Each entry contains the plugin name, installation policy, authentication policy, supported products, and its source. The source can point to a local directory or a Git repository (with optional branch, tag, commit ref, or subdirectory path).

File Locations

Veyyon stores plugins and marketplaces under the home directory (VEYYON_HOME). If VEYYON_HOME is not set, it defaults to ~/.veyyon.

Command Line Interface

You can manage plugins and marketplaces using the veyyon plugin and veyyon plugin marketplace command groups.

Managing Plugins

Add a Plugin

Install a plugin from a configured marketplace. Specify the plugin as plugin_name@marketplace_name, or use the --marketplace option.

$ veyyon plugin add sample@debug
$ veyyon plugin add sample --marketplace debug

Use the --json flag to print the installation result as JSON.

List Plugins

List installed plugins and their statuses.

$ veyyon plugin list

Options:

• -m, --marketplace <name>: Filter listing to a specific marketplace.
• --json: Print the output as JSON.
• --available: Include uninstalled but available plugins from the marketplaces (requires --json).

Remove a Plugin

Uninstall a plugin from local cache and config.

$ veyyon plugin remove sample@debug

Use the --json flag to return the removal result as JSON.

Managing Marketplaces

Add a Marketplace

Add a local path or Git repository to your configured marketplace sources.

$ veyyon plugin marketplace add ./path/to/marketplace
$ veyyon plugin marketplace add owner/repo --ref main
$ veyyon plugin marketplace add https://github.com/owner/repo --sparse plugins/foo

Options:

• --ref <ref>: Git branch, tag, or commit SHA to fetch.
• --sparse <path>: Limits the Git clone to a specific subdirectory. Can be repeated.
• --json: Print the result as JSON.

List Marketplaces

List all configured marketplaces and their filesystem root directories.

$ veyyon plugin marketplace list

Use the --json flag to output the list as JSON.

Upgrade Marketplaces

Fetch the latest revisions for configured Git marketplaces. Omit the marketplace name to upgrade all configured Git marketplaces.

$ veyyon plugin marketplace upgrade
$ veyyon plugin marketplace upgrade debug

Use the --json flag to output the upgrade result as JSON.

Remove a Marketplace

Remove a configured marketplace by name.

$ veyyon plugin marketplace remove debug

Use the --json flag to output the result as JSON.

TUI Integration

Veyyon TUI integrates plugin management directly.

Slash Commands

• /plugins: Opens the interactive plugins catalog popup. You can browse all available plugins, install or uninstall them, and toggle plugins on or off.
• /apps: Opens the apps and connectors status and configuration popup.

TUI Keybindings

When the /plugins popup is open, you can use the following keyboard shortcuts on the selected marketplace tab:

• Ctrl+R: Remove the selected configured marketplace.
• Ctrl+U: Upgrade the selected configured Git marketplace.

Configuration File

Marketplaces and plugin settings are stored persistently in your config.yml file.

Marketplaces Section

Marketplaces are registered under the marketplaces map, keyed by marketplace name.

marketplaces:
  debug:
    source_type: git
    source: https://github.com/owner/repo.git
    ref: main
    sparse_paths: ["plugins/"]
    last_updated: "2026-07-13T10:00:00Z"

Plugins Section

Each installed plugin has an entry under the plugins map keyed by <plugin_name>@<marketplace_name>. You can toggle the plugin or configure tool settings for its contributed MCP servers.

plugins:
  "sample@debug":
    enabled: true
    mcp_servers:
      sample_server:
        enabled: true
        default_tools_approval_mode: always
        enabled_tools: ["compile", "test"]
        disabled_tools: ["delete_all"]

Related recipes

Install and discovery tools (list_available_plugins_to_install, request_plugin_install) are documented in Tools reference. For task-shaped recipes that combine plugins with MCP and skills, see Task guides.

Hooks

Veyyon supports lifecycle hooks via the extension runner. The shipped model is a TypeScript hook module: files discovered under .veyyon/hooks/ are imported by the Bun runtime and export a factory that registers pi.on(...) handlers.

Spec — not shipped: the JSON hooks.json file, config.yml hooks: tables, and the { "type": "command" } external-subprocess model with the PreToolUse / PostToolUse / matcher / trust-level semantics documented on the rest of this page. Veyyon does not load hooks from JSON or run them as external subprocess commands. Those shapes are documented as the target compatibility surface; to write a hook that runs today, use a TypeScript module that calls pi.on(...).

Event Lifecycle

Startup and Compaction Matchers

For SessionStart, the matcher filters against the startup source. The possible values are:

• startup (a new Veyyon session starts)
• resume (resuming a saved session)
• clear (starting a clean conversation)
• compact (starting a compaction turn)

For PreCompact and PostCompact, the matcher filters against the trigger name.

Configuration

Spec — not shipped: the two JSON/YAML configuration paths in this section describe the target model, not the shipped TS pi.on(...) loader. They are documented for compatibility only.

The spec model configures hooks in two ways:

1. In config.yml (either system-level, user-level, or project-local config) under a hooks section.
2. In a standalone hooks.json file inside the config folder (such as the project’s .veyyon/hooks.json or the user’s $VEYYON_HOME/hooks.json).

Hook Handler Schema

Every hook handler configuration supports the following parameters:

Configuration Examples

In config.yml (spec model)

hooks:
  PreToolUse:
    - matcher: "^Bash$"
      hooks:
        - type: command
          command: "echo 'Running bash command'"
          timeout: 30

In hooks.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Running bash command'",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Security and Trust Model

Veyyon requires user-level and project-local hooks to be trusted before they can execute. Every hook handler has a calculated cryptographic hash derived from its event name, matcher, and normalized settings.

Upon discovery, Veyyon classifies hooks into one of four trust levels:

• Managed: Hooks loaded from administrator-enforced requirements layers (such as /etc/veyyon/config.yml or MDM profiles) are always trusted.
• Trusted: User-level or project-local hooks whose calculated hash matches a trusted hash stored under the hooks.state section in $VEYYON_HOME/config.yml.
• Modified: Hooks that were previously trusted, but their command or matcher settings have been modified.
• Untrusted: Newly discovered hooks that have no trust record.

Veyyon disables project-local configuration, hooks, and execution policies in untrusted project directories. You can bypass trust verification by running Veyyon with the --dangerously-bypass-hook-trust command-line flag.

Execution Mechanics

Command hooks run as subprocesses. On Unix-like systems, Veyyon runs commands using the shell specified in the SHELL environment variable, falling back to /bin/sh with the -lc arguments. On Windows, Veyyon uses the shell program in the COMSPEC environment variable, falling back to cmd.exe with the /C argument.

Hook Input (Standard Input)

Veyyon writes a JSON object to standard input (stdin) containing the event details. Every event payload shares these properties:

{
  "sessionId": "a-unique-session-id",
  "turnId": "active-turn-id",
  "agentId": "active-subagent-id",
  "agentType": "active-subagent-type",
  "transcriptPath": "/absolute/path/to/transcript.jsonl",
  "cwd": "/absolute/path/to/cwd",
  "hookEventName": "PreToolUse",
  "model": "model-name",
  "permissionMode": "permission-mode"
}

Event-specific stdin properties include:

• PreToolUse: toolName (string), toolInput (JSON arguments), toolUseId (string)
• PermissionRequest: toolName (string), toolInput (JSON arguments)
• PostToolUse: toolName (string), toolInput (JSON arguments), toolResponse (JSON output), toolUseId (string)
• PreCompact & PostCompact: trigger (string)
• SessionStart: source (string)
• SubagentStart: agentId (string), agentType (string)
• UserPromptSubmit: prompt (string)
• Stop: stopHookActive (boolean), lastAssistantMessage (string or null)
• SubagentStop: stopHookActive (boolean), agentId (string), agentType (string), lastAssistantMessage (string or null), agentTranscriptPath (string or null)

Hook Output (Standard Output)

Hooks communicate their results to Veyyon by writing to standard output (stdout):

• If stdout is empty, Veyyon proceeds normally.
• If stdout is not valid JSON, Veyyon treats it as a plain-text message and injects it into the LLM context.
• If stdout is JSON, it must conform to the hook schema.

Universal JSON Output Properties

{
  "continue": true,
  "stopReason": "Optional explanation",
  "suppressOutput": false,
  "systemMessage": "Optional warning text to show in the TUI"
}

If continue is set to false, Veyyon aborts the action (this is ignored by SubagentStart).

Event-Specific JSON Output Properties

Hooks can return structured updates under the hookSpecificOutput key or direct properties:

• PreToolUse:

  • decision (string): Set to "block" or "approve".
  • reason (string): Required if decision is "block".
  • hookSpecificOutput:
    • hookEventName: "PreToolUse".
    • permissionDecision (string): Set to "allow", "deny", or "ask".
    • permissionDecisionReason (string).
    • updatedInput (JSON): Rewrites the arguments of the tool before Veyyon runs it.
    • additionalContext (string): Text to append to the LLM context.

• PermissionRequest:

  • hookSpecificOutput:
    • hookEventName: "PermissionRequest".
    • decision:
      • behavior (string): Set to "allow" or "deny".
      • message (string). (Note: updated_input, updated_permissions, or setting interrupt to true will cause the hook to fail closed).

• PostToolUse:

  • decision (string): Set to "block".
  • reason (string): Required if decision is "block".
  • hookSpecificOutput:
    • hookEventName: "PostToolUse".
    • additionalContext (string): Text to append to the LLM context.
    • updatedMCPToolOutput (JSON): Rewrites the output returned by the MCP tool.

• SessionStart, SubagentStart, UserPromptSubmit:

  • hookSpecificOutput:
    • hookEventName: Match the event name.
    • additionalContext (string): Text to append to the LLM context.

• Stop, SubagentStop:

  • decision (string): Set to "block".
  • reason (string): Required if decision is "block".

The /hooks TUI Command

You can view and manage lifecycle hooks using the /hooks slash command in the Veyyon TUI. Running /hooks fetches the active hooks configuration and opens the hooks browser in the bottom pane.

Interface Navigation

Use the following keyboard shortcuts in the hooks browser:

• Arrow Up / Down: Navigate through the list of events or individual handlers.
• Page Up / Down: Scroll by page.
• Enter (on Events page): Opens the handlers configured for the selected event.
• Enter or Space (on Handlers page): Toggles the enabled state of the selected trusted hook.
• t (on Handlers page): Trusts the selected hook.
• t (on Events page): Trusts all untrusted or modified hooks discovered in the current directory.
• Escape (on Handlers page): Returns to the events list.
• Escape (on Events page): Closes the hooks browser.

Related recipes

For a worked “run a check after every edit” flow that pairs hooks with non-interactive veyyon --print runs, see Task guides.

Custom hooks guide

Spec — not shipped: this guide documents the target hook model — subprocess command hooks configured in JSON/YAML and driven by PreToolUse / PostToolUse / matcher / trust-level semantics (the same shape as Claude Code). Veyyon loads hooks as TypeScript modules that call pi.on(...), not from JSON and not as external subprocess commands. Read this page as the compatibility reference for the target model; to write a hook that runs today, author a TS module.

Hooks let you run logic at specific points in Veyyon’s lifecycle. You can use them to guard tool calls, enrich context after a tool runs, log events, or enforce local policy.

For a full reference of events, fields, and output formats, see Hooks.

What hooks are

A hook is a command that Veyyon runs when a lifecycle event occurs. The hook receives event details as JSON on stdin and can respond on stdout to approve, block, modify, or annotate the event. Most hooks can use a regular expression matcher so they only run when the context matches, for example only for Bash tool calls or only for compact events.

Use hooks for tasks like:

• Blocking or approving specific tools before they run.
• Adding policy warnings to the context after a tool runs.
• Injecting project-specific instructions when a session starts.
• Logging or auditing tool usage outside the TUI.

The ten lifecycle events

Hooks can attach to ten events. Eight of them support a matcher.

UserPromptSubmit and Stop do not support matchers. The other events can use a regex to decide whether the hook should run.

Regex matchers

A matcher is a regular expression that filters the event. The hook only runs when the matcher matches the target value for that event.

Match patterns are anchored where you want them. ^Bash$ runs only for the Bash tool, not BashBackground or ReadOnlyBash.

Authoring a command hook

A command hook has this schema:

In config.yml (spec model)

hooks:
  PreToolUse:
    - matcher: "^Bash$"
      hooks:
        - type: command
          command: "python3 ~/.veyyon/hooks/audit_bash.py"
          timeout: 30
          statusMessage: "Auditing Bash command..."

In hooks.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.veyyon/hooks/audit_bash.py",
            "timeout": 30,
            "statusMessage": "Auditing Bash command..."
          }
        ]
      }
    ]
  }
}

Stdin and stdout payload formats

Input

Veyyon writes a JSON object to the hook’s stdin. All events share these fields:

{
  "sessionId": "uuid",
  "turnId": "turn-id",
  "agentId": "agent-id",
  "agentType": "agent-type",
  "transcriptPath": "/path/to/transcript.jsonl",
  "cwd": "/path/to/cwd",
  "hookEventName": "PreToolUse",
  "model": "model-name",
  "permissionMode": "permission-mode"
}

Event-specific fields are added on top. For example, PreToolUse includes toolName, toolInput, and toolUseId. See the Hooks reference for the full list.

Output

The hook prints to stdout:

• Empty stdout: Veyyon continues as if the hook did not intervene.
• Non-JSON stdout: Veyyon treats the text as additionalContext and appends it to the LLM context.
• JSON stdout: Veyyon parses it as a structured response.

Shared optional fields on JSON responses:

{
  "continue": true,
  "stopReason": "Optional reason",
  "suppressOutput": false,
  "systemMessage": "Optional message shown in the TUI"
}

Do not use continue: false on PreToolUse or PermissionRequest. Those events reject it as unsupported. Block a PreToolUse call with one of:

{
  "decision": "block",
  "reason": "Forbidden destructive command detected."
}

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Forbidden destructive command detected."
  }
}

PostToolUse and other events have different fields; see Hooks for the full matrix.

Verification scripts

Write and test hooks outside the TUI first. A simple test harness is to run the script with a sample JSON payload:

# test_pre_hook.sh
python3 - <<'PY'
import json, sys
payload = json.load(sys.stdin)
if payload.get("toolName") == "Bash":
    tool_input = payload.get("toolInput", {})
    command = tool_input.get("command", "")
    if "rm -rf /" in command:
        print(json.dumps({
            "decision": "block",
            "reason": "Refusing destructive command.",
            "systemMessage": "Blocked a destructive Bash command."
        }))
        sys.exit(0)
print("")
PY

Run it manually with a sample payload:

cat <<'JSON' | bash test_pre_hook.sh
{
  "hookEventName": "PreToolUse",
  "toolName": "Bash",
  "toolInput": { "command": "rm -rf /" }
}
JSON

If the output is valid JSON and the behavior matches your intent, register the hook and trust it using /hooks or by recording its hash.

Trust levels

Veyyon assigns each hook a trust level before it runs:

Untrusted hooks do not run. Veyyon also disables project-local config, hooks, and execution policies in untrusted directories. You can review and trust hooks inside the TUI with the /hooks command. You can bypass trust verification entirely with --dangerously-bypass-hook-trust, but only for local testing.

Worked example: PreToolUse guard

This hook blocks Bash commands that contain a destructive pattern.

.veyyon/hooks.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .veyyon/hooks/block_destructive.py",
            "timeout": 10,
            "statusMessage": "Checking Bash command..."
          }
        ]
      }
    ]
  }
}

.veyyon/hooks/block_destructive.py:

import json, sys

payload = json.load(sys.stdin)
if payload.get("toolName") != "Bash":
    sys.exit(0)

command = payload.get("toolInput", {}).get("command", "")
forbidden = ["rm -rf /", "mkfs.", ":(){ :|:& };:", "> /dev/sda"]
if any(pattern in command for pattern in forbidden):
    print(json.dumps({
        "decision": "block",
        "reason": "Forbidden destructive command detected.",
        "systemMessage": "This Bash command was blocked by a local hook."
    }))
    sys.exit(0)

When a Bash command matches the forbidden list, Veyyon blocks the tool using the decision/reason pair and shows the optional systemMessage in the TUI.

Worked example: PostToolUse enrichment

This hook adds a project note after the Read tool runs, so the model sees the note in the next turn.

.veyyon/hooks.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "^Read$",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .veyyon/hooks/read_notes.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

.veyyon/hooks/read_notes.py:

import json, sys, os

payload = json.load(sys.stdin)
if payload.get("toolName") != "Read":
    sys.exit(0)

file_path = payload.get("toolInput", {}).get("path", "")
if os.path.basename(file_path) == "Cargo.toml":
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PostToolUse",
            "additionalContext": "When editing Cargo.toml, remember to run `cargo check` afterward."
        }
    }))

The additionalContext text is appended to the model context after the Read tool completes, so it influences the next assistant response.

Managing hooks with the /hooks command

Open the hook browser at any time by typing /hooks in the TUI. The browser shows events and their handlers, lets you enable or disable trusted hooks, and lets you trust new or modified hooks. You can also trust hooks by recording their hash in the hooks.state config section in your user config, but /hooks is the fastest way to review and approve hook changes.

MCP

Model Context Protocol (MCP) lets Veyyon connect to external tools and data sources. Veyyon is an MCP client by default; agent control protocol (ACP) and SDK paths can expose Veyyon as a server.

Transports

Configure servers

Preferred: JSON files managed by Veyyon:

Example:

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "sqlite": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/sqlite-mcp/index.js"],
      "env": { "DB_PATH": "/var/data/app.db" }
    }
  }
}

Veyyon also discovers MCP entries from Claude, Cursor, VS Code, OpenCode, and related tool configs.

Setup walkthrough: MCP server setup.

Engineering detail: docs/mcp-config.md.

In the TUI

Tool names appear namespaced as mcp__<server>__<tool>.

Running Veyyon as an MCP server

Use the ACP integration or SDK embedding rather than a separate veyyon mcp-server subcommand unless your build registers it.

Spec — not shipped: a [mcp_servers.*] config table and a veyyon mcp CLI. Veyyon configures MCP through mcp.json and the /mcp command instead.

MCP server setup

Veyyon can connect to third-party Model Context Protocol (MCP) servers so external tools and data sources become available to the agent. This guide explains how to register those servers, choose a transport, authenticate, and fix the most common connection problems.

For an overview of what MCP does in Veyyon, see MCP. Engineering reference: docs/mcp-config.md.

Where servers are configured

MCP servers are configured as JSON in mcp.json, not in config.yml:

Veyyon also discovers MCP entries from Claude, Cursor, VS Code, and OpenCode configs. The easiest way to add a server is /mcp add in the TUI, which writes to mcp.json for you.

File shape

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "sqlite": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/sqlite-mcp-server/index.js"]
    }
  },
  "disabledServers": []
}

Top-level keys: mcpServers (map of name to config) and disabledServers (names to turn off). Server names match ^[a-zA-Z0-9_.-]{1,100}$. Shared per-server fields: enabled, timeout (milliseconds; 0 disables the client-side timeout), auth, and oauth.

Choose a transport

type is optional for stdio because it is inferred from command.

A minimal streamable HTTP server:

{
  "mcpServers": {
    "analytics": {
      "type": "http",
      "url": "https://analytics.example.com/mcp"
    }
  }
}

Pass environment variables

Local stdio servers often need environment variables:

{
  "mcpServers": {
    "sqlite": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/sqlite-mcp-server/index.js"],
      "env": { "DB_PATH": "/var/data/app.db", "SQLITE_LOG_LEVEL": "warn" }
    }
  }
}

For HTTP servers, pass credentials or account ids as headers:

{
  "mcpServers": {
    "analytics": {
      "type": "http",
      "url": "https://analytics.example.com/mcp",
      "headers": { "Authorization": "Bearer ${ANALYTICS_MCP_TOKEN}", "X-Account-Id": "acct_123" }
    }
  }
}

Authenticate

Bearer token via header

Keep the token in the environment and reference it from a header rather than committing the raw value:

$ export ANALYTICS_MCP_TOKEN="your-token-value"

OAuth

Some HTTP servers require an interactive OAuth flow. Add an oauth block, then authenticate from the TUI with /mcp reauth <name>:

{
  "mcpServers": {
    "crm": {
      "type": "http",
      "url": "https://crm.example.com/mcp",
      "oauth": { "clientId": "veyyon-crm-client" }
    }
  }
}

Approve tools

Every tool an MCP server exposes appears namespaced as mcp__<server>__<tool> and is governed by the global tools.approvalMode plus per-tool tools.approval. To require a prompt for a specific server’s tools, set a per-tool policy:

# ~/.veyyon/agent/config.yml
tools:
  approval:
    mcp__sqlite__query: prompt

To turn a server off entirely, add its name to disabledServers in mcp.json.

In the TUI

Run /mcp verbose to see exactly which tools, resources, and templates Veyyon registered.

Resolve common errors

Server not found

For a stdio server, the command is usually not on PATH or the path is wrong. Check it directly:

$ node /path/to/sqlite-mcp-server/index.js

Fix the path, or add the directory to env.PATH. For an http server, check the URL with curl:

$ curl -i https://analytics.example.com/mcp

Timeout

If /mcp shows the server but tool calls time out, raise the per-server timeout (milliseconds), or set VEYYON_MCP_TIMEOUT_MS (legacy OMP_MCP_TIMEOUT_MS) for the whole process:

{ "mcpServers": { "analytics": { "type": "http", "url": "…", "timeout": 60000 } } }

Authentication failure

For header tokens, confirm the environment variable is set in the same shell that starts Veyyon. For OAuth, run /mcp reauth <name> again. If a 401/403 persists, the token may have expired or the server may require additional headers.

Model cannot see the tools

If a server is connected but the model never uses its tools, check that the server is not in disabledServers, that enabled is not false, and that no tools.approval entry denies the namespaced tool. Run /mcp verbose to see what was registered.

Where to go next

• MCP for the full feature overview, including running Veyyon as an MCP server.
• Configuration for config file layout and precedence.
• Tools, skills, and extension data for other ways to extend Veyyon.

Connectors and Apps

Spec — not shipped: provider-hosted connectors (/apps, [apps] config tables, account-gated app tools). Veyyon does not ship this subsystem today.

What ships instead

Extend Veyyon with tools that are implemented and documented today:

Tool policy uses tools.approvalMode and tools.approval.<tool> — same machinery for bash, MCP, and custom tools (docs/approval-mode.md).

Roadmap note

If provider-hosted connectors ship, they will add a feature flag, account discovery, an /apps UI, and [apps] config. Until then, apps tables are not current behavior.

See also

• MCP setup
• Safety
• Plugins

Session branching

Veyyon sessions are trees, not linear chat logs. Each entry has id and parentId; the active position is the current leaf. Branching appends from the chosen parent without deleting sibling branches.

Engine reference: docs/tree.md, docs/session-tree-plan.md.

Navigate in place: /tree

/tree opens the session tree selector (TreeSelectorComponent). It moves the leaf within the same session file — no new session id.

Also opens via:

• Keybinding app.session.tree
• Double-Escape when doubleEscapeAction = "tree" (default)
• /branch when doubleEscapeAction = "tree" (routes to tree instead of user-message branch picker)

Filters

treeFilterMode setting (cycle with Ctrl+O / Shift+Ctrl+O, or Alt+D/T/U/L/A shortcuts):

Search is fuzzy, case-insensitive, AND across tokens.

Selection behavior

• User / custom_message: leaf moves to parent; message text prefills composer for edit/resubmit.
• Other entry types: leaf becomes selected node; empty composer.
• Current leaf: no-op.

Labels: Shift+L set/clear; stored as append-only label entries.

Optional branch summary when branchSummary.enabled is true: after picking a node, choose summarize abandoned path before continuing.

New session file: /branch and /fork

/fork and /branch change session files. /tree does not.

There is no /clone slash command in the shipped registry.

Ephemeral side questions: /btw

/btw <question> (not /side) runs an ephemeral side thread with inherited context, then returns. See implementation handleBtwCommand in interactive-mode.ts.

/tan runs tangential background agent work — separate from /btw.

Configuration

doubleEscapeAction: tree   # tree | branch | none
treeFilterMode: default    # default | no-tools | user-only | labeled-only | all
branchSummary:
  enabled: false
  reserveTokens: 16384

Command availability

Branching commands require a started session (at least one turn). Some commands are disabled while tasks run; /btw may remain available for steering — see TUI status when blocked.

See also

• Sessions
• Session operations

Memory

Veyyon can remember durable project context across sessions. Memory is off by default; pick a backend in config.yml or /settings.

Backends (built)

Enable in config:

memory:
  backend: mnemopi   # or local, hindsight, off

Mnemopi (recommended for long-running work)

With memory.backend: mnemopi, Veyyon:

1. Opens scoped SQLite banks (global, per-project, or per-project-tagged).
2. Recalls relevant memories into a <memories> block on the first turn (and refreshes the base prompt when recall runs from agent_start).
3. Retains completed turns on a configurable interval (mnemopi.retainEveryNTurns, default 4).
4. Supplies pre-compaction context from the memory backend when compaction runs.

Key settings: mnemopi.scoping, mnemopi.recallLimit, mnemopi.autoRecall, mnemopi.autoRetain, mnemopi.polyphonicRecall, mnemopi.noEmbeddings. See docs/mnemosyne-memory-backend.md.

Dedicated tools when enabled: memory_recall, memory_retain, memory_reflect, memory_edit. The /memory slash command exposes view, stats, diagnose, clear, and enqueue.

Local summary pipeline

With memory.backend: local, a background pipeline at startup extracts durable signal from past session JSONL files, then consolidates into MEMORY.md, memory_summary.md, and optional skills/. The agent reads artifacts via memory:// URLs on the read tool.

Engineering detail: docs/memory.md.

Compaction (three knobs)

Context compaction is separate from durable memory. Settings → Compaction (or config.yml) exposes exactly three fields:

handoff writes a structured session transfer; snap archives history via the snapcompact engine. Run on demand with /compact. See Compaction and project memory.

What the model sees

Recalled or summarized memory is background context, not instructions. Current user messages, tool output, and repo state win on conflict. The agent should cite memory paths when memory changes a plan and pair citations with fresh repo evidence.

Configuration

Use /memory or /settings (Memory group), or set keys under memory.*, mnemopi.*, hindsight.*, or memories.* depending on the active backend.

Per-profile: the active backend, its settings, and its stored data (mnemopi SQLite path, local Markdown artifacts, hindsight bank id) are all scoped to the active profile (VEYYON_PROFILE). Two profiles never share memory — switching profiles switches to an independent memory.backend and an independent database/artifact set under that profile’s agent directory.

Spec — not shipped: rollout-DB memory phases, <oai-mem-citation> blocks, rollout_summaries/, and a /memories settings pane. Veyyon uses the backends above instead.

Profiles

A profile is a named config root that relocates Veyyon’s user-level agent directory. It lets you keep separate settings, sessions, MCP config, skills, and hooks for different kinds of work (for example work vs bounty) while sharing one veyyon binary.

For the mental model and roles, see Roles and profiles.

What a profile owns (shipped)

When --profile <name> is active (or VEYYON_PROFILE is set), native Veyyon paths under ~/.veyyon/agent/ resolve to:

~/.veyyon/profiles/<name>/agent/

That relocation is uniform across settings, sessions, blobs, slash commands, rules, prompts, hooks, tools, extensions, skills, MCP, keybindings, theme, and top-level instruction files (SYSTEM.md, RULES.md, AGENTS.md) discovered from the user agent dir. A named profile does not read another profile’s agent/ tree at runtime.

Keybindings: each profile owns agent/keybindings.*. New profiles seeded with veyyon profile new --from default copy the default profile’s keybindings once. On first launch of an older named profile that has no keybindings file, Veyyon performs the same one-time seed and logs it. There is no live merge from the default profile after that.

Project-level dirs (<cwd>/.veyyon, .claude, etc.) are not profile-scoped; they follow the working directory.

Other tools’ config (skills and CLAUDE.md/AGENTS.md written for Claude, Codex, and similar) is on by default and controlled per profile by discovery.importForeignConfig, so one profile can keep importing it while another opts out to run native-only. Another tool’s own global dir (~/.claude/skills, …) cannot be relocated into a profile — see Skills › Profiles isolate skills.

Activating a profile

• CLI: veyyon --profile <name> (no short form; -p is --print).
• Env: VEYYON_PROFILE=<name> (legacy: OMP_PROFILE, PI_PROFILE).
• Shell alias: veyyon --profile work --alias mywork installs a managed block in your shell rc (see cli/profile-alias.ts).

Profiles are chosen at process start. There is no /profile slash command in the shipped TUI; start a new veyyon invocation to switch.

Creating and managing profiles

$ veyyon profile list
$ veyyon profile new work
$ veyyon profile new bounty --from blank
$ veyyon profile rm work --yes

• new creates ~/.veyyon/profiles/<name>/agent/ with the expected identity dirs (skills/, commands/, …).
• --from default (default) seeds config.yml, keybindings, MCP, skills, and other identity files from the default profile. Sessions, blobs, and databases are not copied.
• --from blank creates an empty agent tree.
• rm refuses the default profile, the active profile, and destructive deletes without --yes.

You can still create a profile implicitly by running veyyon --profile <name> once; use profile new when you want seeding without launching the TUI.

Do not document inline [profiles.<name>] tables or standalone <name>.config.yml files as shipped; settings use config.yml under the active agent dir.

Model slots and roles (per profile)

Each profile’s config.yml owns the three model slots and optional roles:

model: openai/gpt-5                 # interactive (also set live with /model)
subagent:
  model: deepseek/deepseek-chat
compaction:
  model: openai/gpt-5-mini
  strategy: handoff                 # or snap
  thresholdPercent: 80
modelRoles:                         # optional; settings → Models → Roles
  plan: openai/o3

default is not a model or role. Switching profiles switches these assignments with the profile.

See also

• Models, roles, and profiles
• Configuration
• File locations

Models, roles, and profiles

Veyyon keeps model selection explicit and simple. Three ideas stay separate:

• the model you talk to — chosen live,
• roles — optional named model assignments, configured in settings and scoped per profile,
• profiles — separate user config trees.

Three model slots

Veyyon gives you three explicit model choices. Each is set on its own — there is no default model that silently stands in for the others.

Leave the subagent or compaction model unset and that slot uses your interactive model.

Picking the interactive model

Use /model, the model carousel, or the CLI (--model). Your choice is saved to the active profile’s config.yml and applies to the conversation. This is the only model you choose from the picker.

Subagent and compaction models

Set them once in settings → Models, or in config.yml:

model: anthropic/claude-sonnet-5   # interactive
subagent:
  model: anthropic/claude-haiku-4-5
compaction:
  model: openai/gpt-5

They are plain fields — one model each, no per-role matrix and no indirection. When a task subagent spawns, it runs on subagent.model. When context is compacted, it runs on compaction.model.

Roles (optional)

A role is a named model assignment for a kind of work (task, plan, advisor, …). Roles are optional. Edit them in /settings → Model → Roles → Role Models: pick a role, then use the searchable model selector (auth / local / no auth shown on each row). Never edit config.yml for this — settings writes the active profile’s assignments for you.

default is not a role and not a model. The model you pick with /model is simply your interactive model; nothing falls back through a default slot.

Task subagents

The main agent spawns task subagents for parallel scoped work. They run on subagent.model. Task isolation (task.isolation.*) and concurrency (task.maxConcurrency) are settings — not a surface you configure every turn.

Compaction settings

Compaction has exactly three settings, in settings → Models → Compaction:

1. Auto-compaction threshold (compaction.thresholdPercent) — when to compact.
2. Type (compaction.strategy) — handoff or snap.
3. Model (compaction.model) — the compaction model above.

See Memory and compaction for what each type does.

Profiles

A profile relocates ~/.veyyon/agent/ to ~/.veyyon/profiles/<name>/agent/ for native Veyyon config (settings, sessions, MCP, skills, hooks, and your role assignments and model slots). Activate with veyyon --profile <name> or VEYYON_PROFILE.

Profiles are chosen at process start, not mid-session. See Profiles for the lifecycle commands (veyyon profile list/new/rm).

Tool approval

Behavior is governed by tools.approvalMode (plan, ask, auto-edit, yolo) and per-tool tools.approval overrides. Configure in /settings → Safety or --approval-mode on launch.

Where each choice lives

See also

• Profiles
• Models and providers
• Memory and compaction
• Configuration

Personalities

Spec — not shipped: a /personality slash command. Configure personality via /settings or the personality key in config.yml (below).

Personalities change how the agent writes replies, not which tools it has or what sandbox/approval policy applies.

Available personalities (shipped)

A personality injects a <personality> block into the system prompt when enabled, changing tone only.

Schema default: personality: default in settings-schema.ts. The setting is a free-form string, not a closed enum — see Extending the catalog.

Configuring personality

• Settings UI: /settings → Model tab → Prompt group → Personality. Options are resolved at render time (built-ins + your ~/.veyyon/personalities and project .veyyon/personalities files); changing the value refreshes the base system prompt immediately.
• Config file: in ~/.veyyon/agent/config.yml (or profile agent dir):

personality: pragmatic

There is no /personality slash command in the shipped registry. Subagents use none regardless of the main setting (sdk.ts).

Extending the catalog

The 3 shipped personalities are seeds, not a closed set. Add a <name>.md file and its filename stem becomes a selectable personality name; the file body is injected verbatim as the <personality> block:

• User-level: ~/.veyyon/personalities/<name>.md — available in every project.
• Project-level: .veyyon/personalities/<name>.md — available only in that project, and overrides a user or built-in personality of the same name.

Precedence for a given name is project > user > built-in. For example, dropping ~/.veyyon/personalities/pirate.md with the body You speak like a pirate. and setting personality: pirate renders <personality>You speak like a pirate.</personality> with no rebuild. A project .veyyon/personalities/default.md overrides the built-in default for that project only.

Edge cases:

• none is a reserved sentinel that disables the block; a file literally named none.md is ignored (it can never shadow the disable behavior).
• An empty or whitespace-only personality file is treated as absent — the next tier (or the built-in) is used instead, so the block is never emitted empty.
• Setting personality to a name that resolves to nothing (no built-in, user, or project file) falls back to default and prints a visible warning; the <personality> block is never silently emitted empty for a real (non-none) request.

See packages/coding-agent/src/personality/resolver.ts for the resolver implementation.

Boundaries

• Personality does not grant tools, change tools.approvalMode, or bypass sandboxing.
• Personality text is escaped and injected as a bounded system-prompt section; it cannot override project rules or tool policy.

See also

• Configuration
• System prompt customization (engine doc)

Export and import

Session export (built)

/export writes the current session transcript. Target format depends on the extension:

Paths resolve relative to the working directory, ~/, or absolute paths. Directory targets receive the default session filename inside the folder.

Migration from Claude Code (built)

/import is not in the builtin slash registry; Claude migration may be available through setup flows or extensions. When import runs, it merges compatible settings from .claude/ into Veyyon’s config tree (.veyyon/, ~/.veyyon/agent/), including MCP, hooks, skills, and agents.

Import works on local sessions; no background daemon is required.

Typical migrated items:

• Settings from .claude/settings.json → config.yml
• MCP servers → mcp.json
• Hooks → .veyyon/hooks.json or extension hooks
• Skills → .agents/skills / .veyyon/skills
• Subagents → .veyyon/agents
• CLAUDE.md → AGENTS.md

See Migration guide.

Task guides

Short, goal-shaped recipes for common jobs. Each guide points at the deeper feature pages; use those when you need full schemas or edge cases.

Related references: Hooks guide, Non-interactive mode, MCP, Skills, Memory, Branching, Sandbox.

Automate a check on every edit (hooks)

Goal: every time the agent finishes an edit, run a deterministic check and fail closed when it breaks.

The shipped hook model is a TypeScript module discovered under .veyyon/hooks/ (project) or ~/.veyyon/agent/hooks/ (user). The module exports a factory that registers handlers with pi.on(...).

// .veyyon/hooks/post-edit-check.ts
export default (pi) => {
  pi.on("PostToolUse", async (event) => {
    if (!/^(edit|write)$/.test(event.tool)) return;
    // run your check (spawn a test/linter) and block on failure
  });
};

The Bun runtime imports the module at startup; restart or /reload to pick up changes. See Hooks guide for the event names and handler contract.

Spec — not shipped: JSON hooks.json / config.yml hooks: tables and the { type: "command" } subprocess model with PreToolUse / PostToolUse matchers. Veyyon runs TS pi.on(...) modules, not external subprocess commands.

Run a bounded task from a script or CI

Use a one-shot prompt when the trigger lives outside the agent (pre-commit, CI, entr, watchexec):

$ veyyon --approval-mode auto-edit \
    "Run the focused tests for the files changed in the last commit and fail if any regress"

The prompt can be an argument or piped on stdin. Pick auto-edit for unattended write access with an exec prompt, or --yolo to auto-approve everything in a trusted, ideally externally-sandboxed environment. Keep the smoke set small; put heavy suites in CI.

Spec — not shipped: a dedicated veyyon exec subcommand with --json event streams, -o final-message capture, and veyyon review --uncommitted. See Non-interactive mode for the current scripted surface, and use /review in the TUI for a review pass.

Give the agent a new tool (MCP or skills)

Goal: teach Veyyon a capability you do not want to bake into the binary.

Choose the surface

Path 1: add an MCP server

Add it from the TUI, which writes mcp.json for you:

/mcp add

Or edit ~/.veyyon/agent/mcp.json (user) / .veyyon/mcp.json (project) directly:

{
  "mcpServers": {
    "database": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/db-mcp-server/index.js"],
      "env": { "DB_PATH": "/var/data/app.db" }
    }
  }
}

Confirm discovery with /mcp (or /mcp list), then ask the agent to use the new tool by name. If the server needs OAuth, run /mcp reauth <name>. Details: MCP, MCP setup.

Path 2: author a skill

Create a skill directory in user or project scope, for example ~/.veyyon/agent/skills/audit-config/SKILL.md (or .veyyon/skills/… in a repo):

---
name: audit-config
description: Audit Veyyon config.yml for unsafe approval and tool-policy combinations.
metadata:
  short-description: Config safety audit
---

# Audit config

When asked to audit configuration:
1. Read the active config.yml and any project overrides.
2. Flag `yolo` approval paired with broad tool allow-lists on untrusted repos.
3. Prefer concrete remediations over generic advice.

Restart or open a new session so skill discovery picks it up. Skills are data — you can version them in git and share them without shipping a new veyyon build. Prefer a skill when the “tool” is mostly prompting and local scripts; prefer MCP when the capability is a long-lived external process. See Skills.

Share context across sessions (memory and branching)

Goal: keep decisions, conventions, and alternate explorations available without pasting transcripts by hand.

Memory: carry guidance into new threads

Cross-session memory is off by default. Turn on a backend with memory.backend in config.yml:

# ~/.veyyon/agent/config.yml
memory:
  backend: mnemopi        # off (default), local, hindsight, mnemopi

Operate it from the TUI with /memory (/memory stats, /memory diagnose). Keep memory on for repos where conventions matter; leave it off for throwaway scratch sessions. See Memory.

Branching: explore without losing the main line

Use the session tree when you need parallel context inside one problem.

Typical flow: reach a decision point, /fork or /clone to try an alternate approach, and keep the branch worth keeping. Full behavior: Branching and Sessions.

Memory vs branching

• Memory shares durable, consolidated knowledge across different sessions and days.
• Branching shares live transcript context within or beside the current problem.
• Use both: branch to explore, then let memory capture the decision you kept.

See also

• Configuration for the keys these guides touch
• Examples for prompt-shaped tasks

Configuration

Veyyon is configurable without being fussy. Defaults are sensible; change only what you care about. This page is organized by goal, not by alphabetized key name. For provider setup see Models and providers and Authentication. For the full settings catalog, precedence rules, and every key’s type and default, see docs/settings.md.

Where settings live

Settings are YAML mappings. Persistent settings live in config.yml; custom model providers live in models.yml; MCP servers live in mcp.json.

Precedence, low to high:

defaults  <-  global config  <-  project config  <-  --config overlays  <-  runtime flags

Read and write from a shell with veyyon config:

$ veyyon config list                    # all settings with effective values
$ veyyon config get tools.approvalMode
$ veyyon config set compaction.type snap
$ veyyon config path                     # print the active agent directory

/settings does the same inside a live session. Keys must match a schema path exactly (theme.dark, not theme).

Pick models and providers

Three explicit model slots, each set on its own:

# ~/.veyyon/agent/config.yml
model: openai/gpt-5               # interactive
subagent:
  model: deepseek/deepseek-chat
compaction:
  model: openai/gpt-5-mini

/model changes only the interactive model. /status shows every effective model. default is not a model — nothing falls back through a default slot.

Stay safe (approvals and sandbox)

tools:
  approvalMode: auto-edit
  approval:
    bash: prompt
    read: allow

Per run, --approval-mode <mode> and --auto-approve / --yolo override the mode. The OS shell sandbox (Landlock/seccomp/Seatbelt) is a separate hard boundary — see Sandbox and approvals and Safety.

Run unattended or in CI

Lifecycle automation inside sessions uses hooks.

Control context, memory, and compaction

Compaction summarizes older history instead of truncating it. It has exactly three settings:

compaction:
  thresholdPercent: 80
  strategy: handoff
  model: openai/gpt-5-mini

memory:
  backend: mnemopi

See Compaction and project memory and Memory.

Restrict tools for a repo or role

Deny a tool with per-tool policy, or disable a built-in tool entirely:

tools:
  approval:
    bash: deny
    edit: deny

bash:
  enabled: false

Plan mode and agent definitions can narrow the tool set further. Enforcement removes the tool from both the model-visible set and the dispatch registry.

Use profiles for different kinds of work

A profile relocates the user agent directory so you can keep separate settings, sessions, MCP, and skills for different work (for example work vs bounty) while sharing one veyyon binary. With --profile <name> active, ~/.veyyon/agent/… resolves to ~/.veyyon/profiles/<name>/agent/….

$ veyyon --profile work
$ # edit ~/.veyyon/profiles/work/agent/config.yml

Activate with --profile <name> (no short form — -p is --print), or VEYYON_PROFILE=<name> (legacy OMP_PROFILE / PI_PROFILE). Profiles are chosen at process start; there is no /profile switch mid-session. See Profiles.

Spec — not shipped: self-contained <name>.config.yml profile files (a full environment per file, [profiles.<name>] tables). Veyyon relocates the agent directory and reads config.yml under it.

Wire MCP servers and hooks

MCP servers are configured as JSON, not in config.yml:

// ~/.veyyon/agent/mcp.json
{
  "mcpServers": {
    "database": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/db-mcp-server/index.js"]
    }
  }
}

Hooks are discovered from hooks/pre/* and hooks/post/* under a config dir. Recipes: Task guides. Schemas: MCP, Hooks.

Where to go next

• Getting started runs Veyyon with the defaults.
• Task guides for hooks, MCP/skills, and memory/branching recipes.
• Safety for how approval mode and the sandbox affect real tool use.
• Extending for tools, skills, and extension data.
• CLI reference for flags.

Feature flags

Spec — not shipped: a standalone veyyon features subcommand, the --enable-feature / --disable-feature launch flags, and a [features] config table. Today feature listing is a plugin subcommand — veyyon plugin features — experimental toggles are driven from /experimental in the TUI, and persistent toggles live in the features map of config.yml.

Veyyon gates optional and in-progress capabilities behind named feature flags. A flag lets you turn a capability on or off without a new build, and it lets the project ship a capability in stages before it becomes a default. Each flag has a stage that tells you how finished it is.

Listing and toggling

veyyon plugin features prints every known feature with its stage and whether it is currently enabled for your configuration. That list is broader than the product surface: many entries are internal switches used for migrations, protocol experiments, or staged rollout. Treat most of them as engineering cruft unless this page (or /experimental) presents them as user-facing.

$ veyyon plugin features

Persistent toggles write the features config map:

features:
  memories: true
  prevent_idle_sleep: true

For a single run, override the config value with -c features.<name>=true|false:

$ veyyon -c features.memories=true "summarize prior decisions in this repo"

Inside the cockpit, /experimental opens a view for experimental toggles on the running session. Persistent changes belong in the features config map.

Unknown feature keys are rejected rather than silently accepted.

User-facing toggles

Documented here: flags operators and end users actually turn for product behavior. Omit the long tail of internal keys (item_ids, deferred_executor, removed protocol shims, sandbox migration leftovers, and similar). If veyyon plugin features shows a name that is not below, assume it is internal unless a release note says otherwise.

Session intelligence

Automation and tools

Spec — not shipped: there is no guardian_approval flag and no guardian / auto-review approval path in the shipped flag registry or config schema. See Auto-review guardian (Spec — not shipped).

Apps, plugins, and collaboration

Browser, media, and realtime

Network and auth storage

Deprecated (still toggles, avoid new dependence)

What not to document as a product feature

veyyon plugin features also surfaces removed or under-development keys that are not product features: protocol experiments (responses_websockets*, item_ids), removed sandboxes (experimental_windows_sandbox, use_linux_sandbox_bwrap), dead tool search shims, and similar. Enabling them will not give you a supported workflow. Prefer this page, /experimental, and release notes over raw enum archaeology.

See also: Configuration for the features config map and Slash commands.

Tools, skills, and extension data

Veyyon does real work through tools, and you can extend what it knows and what it can reach. This page covers the built in tools, skills, extension data, and external tools through the Model Context Protocol.

Tools

Tools are the actions Veyyon can take: reading a file, searching the tree, editing code, running a command, fetching a page, and more. Every tool runs through the same approval and sandbox model, so a tool cannot exceed the boundary you set. Editing tools in particular all flow through one verified write path, so a change is checked and recorded the same way no matter which tool made it.

Skills

Skills are reusable capabilities Veyyon can draw on, defined as data rather than baked into the binary. Because a skill is data, you can add a skill by dropping in a file, and you can share a skill with others. Veyyon validates a skill when it loads and tells you clearly if a skill needs a tool that is not available, rather than failing in a way you cannot diagnose.

Plugin bundles

Plugin bundles are the package shape for larger extension sets. Treat plugin installation as available only when your veyyon build exposes the matching install, list, and remove commands. Until then, use skills and MCP servers for local extension, because those are the shipped operator paths documented on this page.

External tools through the Model Context Protocol

Veyyon speaks the Model Context Protocol, so it can use tools served by an external server and can serve its own tools to other clients. This lets you connect Veyyon to the wider ecosystem of context servers without custom integration work. An external server is added as data, and its tools appear to the model exactly where you intend.

The principle behind extension

Everything here follows one principle: capability grows through data and through a clear boundary, never through a hidden hardcoded list and never past the safety boundary you set. You can always see what Veyyon can do, and you can always extend it without editing code.

Where to go next

• Configuration covers approvals and the sandbox that bound every tool.
• What makes Veyyon different explains the one write path that every editing tool shares.

Migration guide

This guide walks through upgrading Veyyon and recovering when an upgrade does not go as planned. Veyyon stores all user data under VEYYON_HOME (by default ~/.veyyon on Unix and the Veyyon application directory on Windows), so most upgrades are safe if you back up that directory first.

Before you upgrade

1. Close all running Veyyon sessions and TUI instances. Writes may still happen while the binary is running, and a backup taken during activity can be inconsistent.

2. Back up VEYYON_HOME:

   cp -R ~/.veyyon ~/.veyyon-backup-$(date +%Y%m%d)
   

   Keep this backup until you have verified the new version with veyyon plugin doctor and completed one normal session.

3. Read the release notes for the version you are installing. They list required config changes, renamed fields, and any new dependencies.

Config schema updates

Veyyon reads your settings from VEYYON_HOME/config.yml and validates them against the versioned config schema. If a new release requires a new key or renames an existing one, the binary tells you exactly which file and line are affected.

Common schema changes

• New required keys are added when a new feature is on by default. The error message names the missing key and the section it belongs in. Add it to config.yml or disable the related feature if you do not need it.
• Renamed fields are reported as unknown keys. The old name is usually accepted during a short migration window, but you should rename it to the current spelling.
• Removed fields are ignored unless you run with --strict-config, in which case unknown keys are treated as errors. Use --strict-config in CI to keep your config clean; leave it off during normal use so upgrades do not immediately break.

Updating your config

1. Open VEYYON_HOME/config.yml in an editor.

2. Run the new binary once to see any validation errors:

   veyyon --version
   veyyon plugin doctor
   

3. Fix each reported line. If you are unsure what a key does, see the sample configuration that ships with Veyyon or read Configuration.

4. After editing, run veyyon plugin doctor again to confirm the file loads cleanly.

You do not need to rewrite the whole file. Most upgrades only add or rename a few keys, and the rest of your settings stay the same.

Session and state data

Veyyon keeps your session data in two places under VEYYON_HOME:

• sessions/ contains the append-only rollout files, one per session, in JSONL format. These are the source of truth for conversation history, branching, and undo.
• A local SQLite state database mirrors key events for fast lookups and diagnostics. It is rebuilt from the rollout files if it is missing or out of sync.

This means you usually do not need a manual database migration. When you start the new binary, it reads the rollout files and updates the state database as needed. If you see a warning about a stale state database, the binary repairs it automatically on startup.

If you need to force a state rebuild

1. Close Veyyon.
2. Remove the state database file (see File locations for the exact path on your platform).
3. Restart Veyyon. The state database is rebuilt from sessions/ and archived_sessions/.

Never delete sessions/ or archived_sessions/ to fix a state problem. Those are the durable history; the state database is only a cache.

Rolling back a binary

If the new binary does not work for you, you can go back to the previous version without losing data.

1. Close all Veyyon processes.
2. Restore the previous binary from your system package manager, the release archive, or your own backup.
3. Restore your VEYYON_HOME/config.yml from the backup you made before upgrading, if the new version modified it in ways the old version cannot read.
4. Leave sessions/, archived_sessions/, and the state database in place. Rollout files are forward-compatible for recent releases, and the old binary will rebuild the state database if needed.
5. Start Veyyon and run veyyon plugin doctor to confirm the environment is healthy.

If you used a new feature that wrote settings the old binary does not recognize, remove or rename those keys before starting the old binary. The error message will point you to the right lines.

Checking health after an upgrade

After every upgrade, confirm the install is healthy:

veyyon --version
veyyon plugin doctor

veyyon plugin doctor checks extension health and warns about missing optional binaries or provider keys; it exits non-zero when a check reports an error. Start a normal interactive session and run /debug and /memory diagnose to confirm the runtime and memory backend are working.

Treat every failed check as actionable. Fix the reported line, then re-run. If a check fails after a rollback, compare your VEYYON_HOME/config.yml against the backup from before the upgrade. See Troubleshooting for the common failure modes and Diagnostics and health for the full diagnostics surface.

Spec — not shipped: a top-level veyyon doctor install-health command with --summary / --json reports. Use veyyon plugin doctor and the TUI /debug today.

Where to go next

• Configuration explains the settings that change between releases.
• File locations lists every path under VEYYON_HOME.
• Troubleshooting walks through common upgrade failures.
• Diagnostics and health covers the diagnostics surface in detail.

Reference

This part is the lookup desk: command flags, environment variables, exit codes, and the files Veyyon creates on your system. Use it when you need the exact name of a flag, the location of a config file, or the meaning of a return code.

• CLI reference — the veyyon command and every subcommand, plus common flags and config overrides.
• Slash commands — every / command available inside an interactive session, grouped by task.
• Tools reference — model-facing tools (sleep, context, plugins, MCP resources, edit/exec) with params and safety.
• Environment variables — supported day-to-day variables grouped by purpose (location, auth, catalog, TLS, install, repair, terminal), plus descoped names.
• Exit codes — the return codes Veyyon uses and how child-process exit status passes through.
• File locations — where Veyyon stores config, sessions, logs, and credentials under ~/.veyyon.

Where to go next: if something is failing, see Troubleshooting; for definitions of terms used throughout the book, see the Glossary.

CLI reference

The command is veyyon. Run veyyon with no subcommand to start an interactive session; use a registered subcommand for everything else. veyyon --help and per-command --help are the generated source of truth.

Starting a session

$ veyyon
$ veyyon "fix the failing test in auth.rs"

Common launch options:

Config precedence: CLI flags → -c overrides → config.yml → defaults. See Configuration.

Registered subcommands

Unknown first tokens route to launch as a prompt:

Hidden worker selectors and --smoke-test are for CI/packaging, not daily use.

Spec — not shipped: veyyon app-server, exec-server, execpolicy, responses-api-proxy, and resume / fork / archive as top-level CLI verbs. Use /resume, /fork, and /session in the TUI, or the session picker on launch.

Exit codes

See Exit codes.

Slash commands

Slash commands run inside an interactive Veyyon session. Type / in the composer to open the picker. Commands below are the builtin set; extensions may add more.

Session and navigation

Model, modes, and behavior

Tools, context, and jobs

Auth and usage

Extensions

Side agents and misc

Extension packages (e.g. swarm) add commands such as /swarm run.

Spec — not shipped: /pets, /title, /personality, /permissions, /profile, /import, /archive, /delete, /diff, /init, /mention, /vim, /keymap, /apps, /ide, /whoami, /memories. Use /settings, /memory, /hotkeys, and status-line presets instead. /statusline (shipped) jumps into the Status Line settings group, not a standalone interactive segment picker — see Cockpit.

Tools reference

Model-facing tools are advertised to the model per turn. Availability depends on settings, sandbox, plan mode, memory backend, and feature flags.

For sandbox and approvals see Sandbox. For MCP tools see MCP. Per-tool engineering specs live under docs/tools/.

Core loop

1. Model emits a tool call (JSON arguments per schema).
2. Veyyon validates arguments; handlers run after approval/sandbox checks.
3. Text or structured output returns to the conversation.

General schema repair runs before dispatch on all schema-bearing tool calls; tool-specific leniency (e.g. hashline parsing) is layered on top. See Repair overview.

Edit and write (built)

Hashline flow: read/grep mint [path#TAG] anchors → model copies tags into edit → @veyyon/hashline applies ops. See Edit engine and docs/tools/edit.md.

Read and search (built)

Shell and execution (built)

Agent coordination (built)

Memory (when backend enabled)

Other builtins

Includes web_search, github, lsp, ast_edit, ast_grep, checkpoint, rewind, resolve, manage_skill, launch, inspect_image, generate_image, tts, report_finding, and MCP tools (mcp__*). Extension hooks may register more.