The Veyyon handbook

Veyyon is a coding agent that runs in a terminal. Give it credentials for a model provider and it works inside a project: it reads files, runs tools, and edits code in place. Every step that touches the tree goes through an approval tier.

Install

curl -fsSL https://get.veyyon.dev | sh

On Windows:

irm https://veyyon.dev/install.ps1 | iex

The installer downloads a release binary and verifies its checksum. To build from source, clone the repository and run bun run setup && bun dev in that checkout. See Install for platforms, pinned releases, updates, and uninstall.

The binary is veyyon, aliased to vey. Configuration lives under ~/.veyyon; the default profile keeps its state in ~/.veyyon/profiles/default/agent/.

Where things are

Implementation

The CLI, TUI, tools, providers, and session loop are TypeScript on Bun. Grep, glob, PTY, and tree-sitter parsing are Rust natives in @veyyon/natives. The hashline edit engine is TypeScript in @veyyon/hashline, with native helpers for block resolution.

• Hashline edits. edit and write apply content-addressed patches and verify them before anything reaches disk. A failed patch returns a structured error to the model instead of a half-written file.
• Model slots. The interactive model (/model), the subagent model, and the compaction model are separate settings. Named roles pin a model to a kind of work.
• Approvals. tools.approvalMode gates the read, write, and exec tiers. There is no operating-system sandbox: no Landlock, no seccomp, no Seatbelt, no bubblewrap. Approvals are the control point.
• Engine modes. Plan mode, goal mode, vibe mode, compaction, and task subagents live in the agent loop, not in prompt text.

Veyyon is a fork of oh-my-pi. See Acknowledgements for credits.

Design and mechanisms

• Overview: product capabilities and harness structure
• Mechanisms: subsystem contracts and runtime behavior
• Argot: per-project token shorthand codec
• Performance: execution bounds, native paths, and repair

Install: Install. Concepts: Core concepts.

Overview

Veyyon is a local terminal coding agent. The loop, tools, and credentials run locally on the host machine. Model selection uses the bundled provider catalog via subscription sign-in or API keys.

Subsystem summary

Lineage

Veyyon is built from oh-my-pi and Pi. See Acknowledgements for credits.

Related

• Mechanisms
• Getting started
• Editing and repair

Mechanisms

Hashline edits

The edit and write tools accept hashline patches, which are addressed by content rather than by line number. Before writing, the native layer checks the patch against the current file. If they do not match, the tool fails and returns recovery context to the model instead of writing a corrupted file.

See Editing and repair and The hashline edit engine.

Tool approval tiers

tools.approvalMode is one of plan, ask, ask-command, auto, or yolo. auto is the default. Older names map onto those: always-ask to ask, write and auto-edit to ask-command. The tiers are read, write, and exec.

Four guards sit above the mode and no mode lifts them:

• Per-tool overrides in tools.approval.
• The working-directory boundary.
• The secret-use boundary.
• bash-guard.ts, which forces a prompt on a destructive command such as a recursive delete of the home directory. yolo does not lift it.

bashInterceptor.enabled adds a user-configured layer on top, off by default, matching bashInterceptor.patterns.

See Approvals and /settings -> Interaction -> Approvals.

Model slots and roles

Model configuration separates model selection from subsystem roles:

• The interactive model is set with /model or --model and persists as modelRoles.default.
• Roles pin a model to specific workloads, such as smol for lightweight operations or advisor for review. Custom roles are defined in modelRoles. See Models, roles, and profiles.
• Overrides are explicit subsystem policies. compaction.model overrides the interactive model for compaction, otherwise compaction inherits it. Subagent models are configured via subagent policies in settings.
• Cycling rotates through cycleOrder (defaulting to smol then slow), bound to app.model.cycleForward.

Provider-neutral loop

The agent loop, TUI, session format, MCP, skills, hooks, and extensions operate independently of specific model providers. Providers are configured in the active profile agent directory through config.yml or /setup, with account management via /providers.

Engine modes

Compaction, goal continuation, plan mode, vibe mode, and task subagents live in the session and tool layer, not only in prompt text. Goal mode can keep an idle session moving toward a stored objective. Plan mode writes a plan file and holds back mutation until the resolve and approval paths complete.

Profiles

Every profile, including default, lives at ~/.veyyon/profiles/<name>/agent/, which holds its settings, sessions, MCP config, skills, and hooks. See Profiles and File locations.

Related

• Design goals
• Roles and profiles
• Repair

Argot

Argot is a per-project token shorthand codec for model interactions. A project dictionary maps short handles to recurring text strings such as paths, import roots, and build commands. The model outputs the handle, and the runtime expands the handle to the full string before passing arguments to tools, rendering UI, or appending to transcripts.

For configuration and flags, see Save tokens with project shorthand.

Shorthand format

A handle consists of a sigil prefix followed by an identifier:

• The default sigil is §.
• Identifiers use lowercase ASCII letters, digits, and underscores.
• Per-project sigils are configured in the dictionary’s sigil field.

When the model emits §build, the runtime replaces §build with the configured string before executing the command in the shell.

Dictionary structure

Handles are defined in an AGENTS.dict file:

sigil = "§"

[handles]
build = "node --experimental-vm-modules ./scripts/build.mjs --target release --profile ci"
dbconn = "src/server/db/connection.ts"

The dictionary format enforces length bounds on expansions and includes a schema version. Files with incompatible major versions fail load validation.

The dictionary is generated automatically from project contents. When a session starts or the argot_load tool runs on a target directory, the generator identifies recurring strings, ranks candidates by token reduction, and stores the compiled dictionary in the local cache directory. Nothing is written to the repository working tree.

Automatic startup loading is controlled by argot.autoload (enabled by default).

Codec boundaries

The codec operates under two distinct boundaries:

• Decoding: Turning handles back into full text is unconditional. Whenever a dictionary is active, all handles are expanded before text reaches tool execution, transcript storage, or terminal display.
• Encoding: Teaching shorthand syntax to the model is controlled by configuration:
  • Model allowlist (argot.encode.models): Shorthand instructions are provided only to explicitly allowed models.
  • Context cutoff (argot.encode.disableAboveTokens): Shorthand instructions are omitted once session context exceeds the specified token limit.

When encoding is disabled, the model writes full strings. Decoding remains active so existing handles in session history continue to expand.

Cache storage

Cache entries are content-keyed using the repository commit hash or a directory fingerprint:

• Cache files are immutable once written.
• Distinct commits produce separate cache entries.
• Stored transcripts contain expanded text rather than raw handles, allowing cache entries to be discarded and rebuilt without corrupting session history.

To rebuild a project cache, remove the cached dictionary directory under ~/.veyyon/cache/argot/.

Subagent boundary

Subagents evaluate shorthand independently:

• Each agent instance expands its output before invoking tools, writing transcripts, prompting subagents, or returning values to a parent agent.
• Raw handles do not cross agent boundaries.
• The argot.subagents setting controls whether child agents inherit the parent dictionary, generate a project-specific dictionary, or operate without shorthand. See Subagents configuration.

Related

• Save tokens with project shorthand
• Mechanisms

Harness design goals

Model quality depends on the agent harness: tool schemas, edit format, context handling, and control flow. The same weights can succeed or fail depending on those choices.

Primary mechanisms

1. Edit format. Formats that are hard to emit cause apply failures and retries. Hashline (and model-specific edit prompts) is the main write path in packages/coding-agent.
2. Control flow. Stop when verification passes; bound retries; budget context and subagent fan-out. Plan mode, goal mode, and tool-approval tiers encode parts of this in the engine.

Design consequences

• Hashline-aware edit / write with native verification (see The hashline edit engine).
• Explicit model slots and optional roles (modelRoles, catalog selectors, thinking levels).
• Engine-enforced modes: plan file + resolve path, goal continuation, approval tiers.
• Schema-based tool-call repair before argument validation (see Repair).

Related

• Mechanisms
• Repair
• The hashline edit engine

Architecture at a glance

Veyyon ships as the veyyon CLI (Bun + TypeScript, Rust helpers). Subsystems map each has a handbook page and matching engineering notes under docs/.

The request path

            ┌──────────────────────────────────────────────────────────────┐
prompt ──► │  veyyon (packages/coding-agent)                              │
            │    │                                                          │
            │    ▼                                                          │
            │  AgentSession turn loop                                      │
            │    │   model stream → tools (read, bash, edit, …)            │
            │    ▼                                                          │
            │  hashline / handlers ──► filesystem (approval-gated)         │
            └──────────────────────────────────────────────────────────────┘

Subsystems

Design rules

1. One primary edit path. Hashline is the default edit surface; alternate edit.mode values exist for compatibility.
2. Explicit failures. Invalid config, stale hashline tags, and denied actions return actionable errors to the operator or model. Denied tools do not auto-escalate permissions.

Tool-call argument repair (alias maps, strict unknown-key rejection, parse leniency) runs at the dispatch seam in packages/coding-agent/src/repair/schema-repair.ts. See Repair. Providers and models: Providers.

Performance

Agent execution latency is composed of model generation latency, tool execution I/O, validation failure retries, and harness runtime overhead.

Retry bounds

Tool calls or edits that fail schema validation or patch application require additional model turns. Schema repair on tool arguments and patch validation on edits catch structural issues before execution. Implementation: packages/coding-agent/src/repair/, @veyyon/hashline.

Edit path

Hashline edits reference surrounding anchor lines rather than full file rewrites, so a patch contains the changed lines and their anchors instead of a new copy of the file. Applying one costs O(file bytes + output bytes + patch). The applier splits the body into lines once, walks it once, and joins the result once, so cost tracks file length rather than patch length: about 1ns per input byte, or 3ms for a 100,000-line file on a Ryzen 9 9950X. A file with CRLF endings costs roughly twice that, because the body is normalized to LF before the edit and restored after it. Run bun bench/hot-paths.bench.ts in packages/hashline to reproduce the curve. It prints the cost per byte at 10,000, 100,000 and 1,000,000 lines for a single edit and for a range delete, and fails when that cost stops being flat. See Hashline engine.

Edit preview while arguments stream

A tool call’s edit preview recomputes as arguments arrive. The streaming pass reads its target through a cache keyed by modification time and size, so a stream of chunks against one file reads it once instead of once per chunk; the pass that runs when arguments are complete reads fresh, because that text is what the edit is applied to.

Off-window boundary rows in a diff or a read window (the enclosing header, the matching closing bracket) come from a scan of the whole source, and the parse cache retains nothing past 4MiB. A source over that size renders without boundary rows rather than paying a scan per redraw. Streaming a one-line replacement against an 11.7MiB, 100,000-line file costs 36ms per preview pass and one read, against 1.9s per pass and a read each pass, on a Ryzen 9 9950X.

Session persistence

Entries append to the session JSONL through an open writer. Compaction, elision, a title change and a recovered write fault republish the whole file instead. The body is produced in chunks of about a megabyte and written chunk by chunk, so the transient copy is bounded by the chunk rather than by the transcript. A republish reads the file back first only when what is at the path is no longer the file this session published, compared by inode and by length: a second window writing the same transcript changes both, and reading it back is what keeps its entries. Republishing a 253MiB transcript of 118,000 entries costs 509ms, 44MiB of peak resident memory above the session, and no single pause longer than 3ms, on a Ryzen 9 9950X.

Runtime architecture

The CLI, TUI, and session loop run as TypeScript on Bun. Native grep, PTY handling, shell support, and tree-sitter parsing execute via native addons. Rust crates provide glob matching, grep orchestration, key normalization, text indexing, diffing, and directory walking. Token streaming renders output incrementally as chunks arrive from provider streams.

Related

• Mechanisms
• Getting started

Install

Veyyon installs as a single self-contained binary. The release installer stages the download and proves it has the published checksum, the requested version, and working native support before it changes the active install or your shell. It then links a short vey launch command next to veyyon. Under the hood Veyyon is a TypeScript and Bun agent loop, with Rust natives handling the hot paths: grep, the file walker, the shell and PTY, and tree-sitter block resolution for hashline block edits. The prebuilt binary bundles all of that, so you do not need Bun, Node, or a package manager to run it.

Install on Linux or macOS

$ curl -fsSL https://get.veyyon.dev | sh

That installs the veyyon binary to ~/.local/bin, links vey beside it, and runs a doctor: self-check. Before it replaces an existing binary, creates the alias, edits a shell profile, or writes completions, it checks the staged download in this order:

1. Its SHA-256 digest matches the release sidecar.
2. veyyon --version reports the exact release tag you requested.
3. A real veyyon grep finds a known file, proving the native addon loads on this platform.

The checksum proves which bytes you received, but it cannot prove that the release uploaded the right version or a usable native build. If any preflight fails, the installer removes the staged file when it can and leaves the active binary and shell files unchanged. After the verified file moves into place, doctor: repeats the version and native checks from the final path. When ~/.local/bin is not on your PATH yet, the installer then adds it to your shell profile. A profile is read when a shell starts, and the shell you ran the installer from has already started, so the final message gives you the exact reload command before the normal next steps:

The installer records a small ownership receipt beside each binary and completion file it creates. A reinstall or uninstall changes only receipt-backed files. An older Veyyon install is adopted when its exact launcher or generated completion signature identifies it. If another executable or completion already occupies a target path, the installer leaves it byte-for-byte unchanged and reports to move it yourself before retrying, and states the receipt it consulted so you can see what it was comparing against.

A receipt is written before the binary it describes, so a reinstall repairs an install that was interrupted mid-swap instead of refusing it. Installing the same release over a byte-identical binary leaves the file untouched and only rewrites the receipt.

Pass --force (POSIX) or -Force (Windows) to install over a file the installer cannot account for. That file is moved to <name>.unowned.<pid> and its new path printed. Nothing is deleted, and no sweep or uninstall touches that name.

Next steps:
  1. Reload your shell:        exec $SHELL -l
     (or, without a new shell: source /home/you/.bashrc)
  2. Launch in any repository: veyyon
  3. Connect API providers:    veyyon setup
  4. See every command:        veyyon --help

When the directory was already on your PATH, there is nothing to reload and the list starts at the launch step.

The installer never calls the GitHub API. It finds the newest release from where https://github.com/santhreal/veyyon/releases/latest redirects to, and downloads the binary from that same host. The API is capped at 60 requests an hour per address, shared by everyone behind it, so a CI fleet or an office network that installs Veyyon repeatedly used to start getting a rate-limit failure on a machine where nothing was wrong. Nothing needs a token, and setting one changes nothing about the install.

Install on Windows

irm https://veyyon.dev/install.ps1 | iex

That works in both shells Windows ships: Windows PowerShell 5.1, which is what powershell.exe opens on a stock machine, and PowerShell 7. The installer enables TLS 1.2 before it fetches anything, because 5.1 still offers SSL 3.0 and TLS 1.0 by default and GitHub has required TLS 1.2 since 2018.

Like the Unix installer, it never calls the GitHub API, and it puts the install directory at the front of your user PATH. The one-liner above runs in the window you typed it in, so veyyon works there straight away, with no restart. A PATH entry reaches every other program when that program starts, so terminals you already have open elsewhere will not see it until they restart. The closing steps state which case you are in: run the installer as a file (pwsh -File install.ps1) and it is a separate process whose PATH change cannot reach your shell, so the first step is to open a new window.

Prebuilt release platforms

GitHub Releases publishes these application binaries:

There is no native Windows arm64 release. On Windows arm64, run the Windows x64 binary under emulation. Linux release binaries require glibc. On a musl system such as Alpine, the installer stops before downloading and reports to clone the repository and build it yourself.

After install

$ vey --version

The first interactive vey opens the first-run setup, which moves through a splash, providers, glyphs, theme, and an outro. To run it again later, use veyyon setup. To re-open just the providers panel inside a session, use /setup. To manage the accounts you already have, use /providers. See Getting started.

Your configuration home is ~/.veyyon, and the default profile keeps its agent directory at ~/.veyyon/profiles/default/agent/.

If an install is interrupted before the final replacement, run it again. The installer stages the binary beside its final path, so a partial download never overwrites an existing veyyon. On Linux and macOS, the verified file takes the live path with one same-filesystem rename. On Windows, the installer moves the old binary aside immediately before replacement and restores it if moving the staged file fails.

Ctrl-C removes the staged file on the way out. A kill the process cannot catch can leave that staged file behind, and the next install reclaims it and reports it:

  ok  removed /home/you/.local/bin/.veyyon.download.48213 left by an interrupted install (pid 48213)

A staged file belonging to an installer that is still running is left alone, so two installs at once cannot delete each other’s download.

Install a specific release

Linux or macOS

The POSIX installer takes long options. Pass them after -- when you pipe the script:

$ curl -fsSL https://get.veyyon.dev | sh -s -- --help
$ curl -fsSL https://get.veyyon.dev | sh -s -- --binary --ref v1.0.11   # a specific release binary
$ curl -fsSL https://get.veyyon.dev | sh -s -- --ref v1.0.11            # the same thing: --binary is the default
$ curl -fsSL https://get.veyyon.dev | sh -s -- --local                  # install a binary you built yourself

Windows

The PowerShell installer uses named PowerShell parameters. Create a script block from the downloaded installer so you can pass them:

& ([scriptblock]::Create((irm https://veyyon.dev/install.ps1))) -Help
& ([scriptblock]::Create((irm https://veyyon.dev/install.ps1))) -Binary -Ref v1.0.11  # a specific release binary
& ([scriptblock]::Create((irm https://veyyon.dev/install.ps1))) -Ref v1.0.11          # the same thing: -Binary is the default
& ([scriptblock]::Create((irm https://veyyon.dev/install.ps1))) -Local                # install a binary you built yourself

You cannot append parameters to irm ... | iex. Use the script-block form above whenever you need an option. If you downloaded install.ps1 as a file instead, use the same parameters with pwsh -File install.ps1.

Release tags carry a leading v, and --ref 1.0.11 on POSIX or -Ref 1.0.11 on Windows works as well as the leading-v form. The installer looks for the tag you named, then for the v form, and prints which one it resolved to before it downloads anything. It does that only for something that reads as a version. --ref states a published release tag and nothing else, so a branch or a commit is looked up once and then rejected.

Run an unreleased ref, or an unsupported platform

The installer only installs a published release binary. It never clones the repository, never runs bun install, and never builds anything. To run an unreleased branch or commit, or to get Veyyon onto a platform with no release, clone the repository yourself:

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

To pin a ref, check it out before you run setup:

$ git clone https://github.com/santhreal/veyyon.git
$ cd veyyon
$ git checkout v1.0.11
$ bun run setup
$ bun dev --version

Clone it into whatever directory you want it in. That tree is a developer checkout you own: you chose where it lives, you decide when it moves or goes away, and the installer never creates one and never writes into one. bun dev runs Veyyon straight from TypeScript in that tree, so there is no separate build step. Use it while you are evaluating Veyyon or contributing to it.

Building from a checkout needs Bun and Git, and you install those yourself. It also needs git-lfs if the ref you checked out tracks files through Git LFS, because without git-lfs those files arrive as small pointer text files that look present and then fail at runtime.

If you build a release binary in that checkout, you can put it on your PATH with the installer rather than copying it by hand. Pass --local on POSIX or -Local on Windows. That installs the binary you already built, with the same alias, PATH, and completion handling a download gets, and it still clones nothing.

Verify the install

$ vey --version
$ vey plugin doctor
$ vey plugin doctor --fix

vey plugin doctor checks plugin installation health (directories, manifests, entry paths, enabled features). Binary and provider-key checks live in vey setup status. For interactive diagnostics, use /debug in the TUI. See Diagnostics.

When the staged binary would not run

The preflight runs from the staging path inside the install directory. If the binary cannot start or its native search fails, the error includes the exit status and the system error text. A missing shared library means the machine needs that package. A permission error usually means the install directory is mounted noexec, so choose another with VEYYON_INSTALL_DIR. A native-addon load error usually means the release does not support that platform, so clone the repository and build it yourself instead.

This failure occurs before the active binary, alias, PATH, and completion files change. Fix the reported cause and run the installer again rather than trying to finish by hand.

To ask the same questions later, on the machine as it is now, run veyyon setup status. It repeats the install checks and adds the two the installer cannot make: whether a second copy of veyyon earlier on your PATH is shadowing this one, and whether the completion files are still there. It exits non-zero when something is actually broken, so a script can gate on it. See Diagnostics and health.

Relocate the config directory

On Unix, Veyyon uses ~/.veyyon by default. Two environment variables let you move it. VEYYON_CONFIG_DIR renames the home-relative config directory, and VEYYON_CODING_AGENT_DIR relocates the agent base, which holds config.yml, agent.db, your sessions, and more.

$ export VEYYON_CODING_AGENT_DIR=/path/to/veyyon-agent
$ vey plugin doctor

The File locations chapter shows the full layout.

First credentials

On the first interactive launch, the first-run setup (or veyyon setup) walks you through sign-in and API keys. Inside a session you have three ways to manage credentials: open the setup panel again with /setup, manage the accounts you already have with /providers, run /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.

Updating

Veyyon keeps itself current. On startup it checks GitHub Releases for a newer version, and if it finds one it downloads the new binary in the background:

veyyon 1.2.0 installed · restart to use it

The running process keeps the version it started with, so the update takes effect the next time you launch. On that launch the welcome card’s tip line states the new version and points at what you can do about it:

Tip: Updated to veyyon 1.2.0 · /changelog · roll back or turn auto-update off in /settings

You see it once per update, on the first launch after it. /changelog opens the release notes on the web rather than printing them into your terminal.

The check costs one request to github.com, and no request to the GitHub API. It reads the newest version out of where https://github.com/santhreal/veyyon/releases/latest redirects to, the same way the installer does, because the API is capped at 60 requests an hour per address and that cap is shared by everyone behind it. A laptop is nowhere near it; an office, a CI fleet or a container host running several agents spent it on startup checks alone, and then every machine behind that address reported that it could not check for updates. Nothing here needs a token, and setting one changes nothing.

The one thing that still queries the API is the version list behind veyyon rollback, because a list of every published version has no redirect to read it from. That runs when you open the picker, not on startup.

Two settings control this, both on by default:

Turn automatic updates off like this:

$ veyyon config set startup.autoUpdate false

You can always update on demand, whichever settings are in force:

$ veyyon update
Current version: 1.0.37
New version available: 1.0.38
  ok  Checksum verified
  ok  Updated to 1.0.38. Restart veyyon to run it.
Changelog for 1.0.38: https://veyyon.dev/changelog#v1-0-38

The last line is the same changelog link veyyon rollback prints, so however you change version you are told where to read what changed. If an update fails, Veyyon points you at veyyon rollback in the same breath, since a failed update is the moment you most want the way back.

A checkout install uses the same recoverable contract. That is a veyyon on your PATH that runs out of a git clone you made yourself. Before it fast-forwards, Veyyon requires a clean tracked tree and records the current Git revision. If dependency installation, generated artifacts, native provisioning, version verification, or the runtime search probe fails after the merge, it resets to that revision, restores the old dependencies and generated artifacts, and proves the restored launcher runs before it reports the failure.

Going back to an older version

If a release breaks something you depend on, you do not have to wait for the next one. veyyon rollback moves your install to any published version.

Run it with no arguments and you get a picker over every published version:

$ veyyon rollback

The list opens on the version you are running. Type to filter it, press c to open the highlighted version’s changelog in your browser, and press enter to choose one. Nothing installs until you choose, and the change takes effect the next time you launch.

If you already know the version you want, or you are writing a script, the same command works without the picker. Start by seeing what there is:

$ veyyon rollback --list
VERSION  PUBLISHED
1.3.0    2026-07-01  (newer)
1.2.0    2026-06-01  (current)
1.1.0    2026-05-01  (previously run)

The markers tell you where you stand: current is the version running now, newer is a version you would move forward to, and previously run is one this machine has been on before. Every version change is recorded, whether it came from an update, from a background automatic update, or from a rollback, so previously run marks the whole path this install has taken rather than only the times it went backwards. Then name the one you want:

$ veyyon rollback 1.1.0

That installs 1.1.0 the same way an update installs a new release, verifies the binary really is the version it claims, and prints the changelog link for it. Like an update, it takes effect the next time you launch.

Two things it will not guess at. Rolling back to the version you are already running does nothing useful, so it reports that instead of reinstalling and reporting success. And a source checkout cannot be rolled back: it updates by fast-forwarding its git branch, which only moves forward, so Veyyon reports that rather than quietly reinstalling the latest version. To run an older version from a checkout, check the tag out yourself, or install the binary build and roll back from there.

Add --json to --list when you want the same information for a script; each row contains the version, its publish date, the markers, and the changelog URL. Without a terminal on both ends, the bare veyyon rollback prints the list rather than opening a picker nothing can drive, so it is safe in a pipeline.

Building that list is the one thing Veyyon queries the GitHub API for, so it is also the one thing that can be rejected because of the API’s per-address limit. When it is, the error states what failed and what still works: updating forward does not touch the API, so veyyon update is unaffected. Wait a few minutes and the list comes back.

You can also reach the picker without leaving a session. Open /settings, go to the Interaction tab, and you will find Roll back version directly under Automatic Updates, showing the version you are running now. It opens the same picker, and choosing a version closes the settings panel first so you can watch the install and read anything it has to tell you. The row appears only on an install that can actually perform the move, so you will not see it on a source checkout.

Veyyon is distributed only two ways, and it updates the way it was installed. A binary install fetches its replacement from GitHub Releases. The updater stages the download beside the live executable, then performs the same ordered preflight as the installer: published SHA-256 checksum, exact release version, and a real native-backed search. The search is skipped only when rolling back to an old version that has no veyyon grep command, which the staged binary must confirm through its own --help. If any preflight fails, the staged file is removed and the binary you started with stays live.

After preflight, Veyyon preserves the current executable as a backup without removing its live path, using a hard link where the filesystem permits it and a completed copy otherwise. One atomic rename then switches the live path to the verified replacement. A hard kill can therefore leave the old binary or the new one at that path, but never no binary. If the final installed check fails, the backup is atomically restored. A backup that is still locked on Windows, or is left by a hard kill, is reclaimed by a later update.

A source checkout updates in its own terms: veyyon update fast-forwards the checkout, reinstalls dependencies, regenerates build artifacts, and refreshes the native addon, all in one command. It then reads the checkout’s own version back and will not report success unless the checkout really is at the new release. A fast-forward only advances the branch you are on, so a checkout on a feature branch, or on a fork whose upstream lags, can merge cleanly and stay behind; Veyyon reports that instead of claiming a version you do not have. The background updater leaves source checkouts alone and never runs git against your working tree. It reports that a version exists, and you run veyyon update when you want it. There is no npm, Homebrew, or other package-manager channel to go through. If an update fails, Veyyon reports the failure and the retry command veyyon update; it never fails quietly and leaves you on an old version without a word.

Veyyon works out which of the two you have by following the veyyon on your PATH to what it really runs. A symlink is followed, and so is a small wrapper script that hands off to something else: if what it hands off to is a checkout’s launcher, the install runs from that checkout and gets the checkout update. That matters if you keep your own wrapper in front of a checkout, to set an environment variable or pick a different interpreter, because without following it Veyyon would treat the wrapper as a binary and overwrite it with a downloaded release, leaving your checkout orphaned. A wrapper is recognized on either platform: a .cmd or .bat file, or any file starting with #!. The release binary itself is never read looking for one.

If the same version fails to install twice, the cause is usually the machine rather than the release: a binary owned by another user, a read-only image, or a directory that needs elevated permissions to write. Veyyon reports that failure and then leaves it alone for six hours instead of repeating it on every launch. A newer release is never held back by an older one’s failure, and veyyon update ignores the pause entirely, so you can always ask to see the error again:

$ veyyon update

An update also rewrites the shell completion files you already have, so tab completion covers the new version’s subcommands and flags. It rewrites only files that are already there because the installer chooses which shells are wired. If a file cannot be rewritten, a manual update states the path and that it still describes the previous version. A background automatic update adds a visible warning to the TUI update notice, counts the stale completion files, and tells you to re-run the installer to rewrite them. The binary update remains installed. A binary update generates completions from the new binary; a source update generates them from the checkout’s launcher.

The native addon is cached per version under ~/.veyyon/natives/<version>/, around 150MB each. When a new version stages its own cache, the previous version’s copy is removed: it can never be loaded again, because Veyyon looks only under its own version. Only directories named like a version are touched, and a copy that cannot be removed is reported and retried on the next update.

Running several sessions at once is safe. Only the first one to start installs; the others see that an install is under way and skip it rather than writing over the same binary at the same time.

Tab completion

The installer sets up tab completion for you. On macOS and Linux it writes one file per shell into the directory bash, zsh, and fish each autoload from. If a shell will not load that directory (zsh’s $fpath often does not include it, and bash needs the bash-completion package), the installer reports it and prints the exact line to add, rather than leaving you a file nothing reads.

Completion covers more than the command names. It offers the models in the catalog for --model, your saved sessions for --resume, and for veyyon config it offers the settings that exist and the values each one accepts:

$ veyyon config set startup.<Tab>
startup.autoUpdate  startup.checkUpdate  startup.quiet  startup.setupWizard
$ veyyon config set startup.autoUpdate <Tab>
true  false

Those candidates come from the installed binary itself, so they describe the version you are running rather than the version the script was written for. A value only you know, an API key or a search term, is left alone: completion offers nothing rather than a list of your files.

Attachments complete as paths. A word starting with @ specifies a file to send along with your message, so the shell completes it the way it completes any path:

$ vey @src/ma<Tab>
@src/main.ts

Windows works differently, because PowerShell has no directory it autoloads completions from. The installer writes veyyon-completions.ps1 next to your profile and adds one line to the profile that loads it:

# added by the veyyon installer
. "C:\Users\you\Documents\PowerShell\veyyon-completions.ps1"

Uninstall removes that line and the script, and leaves the rest of your profile exactly as it was.

If you already have your own vey command, the installer never creates that alias, and the completions it writes do not bind the name either. Every generated script normally completes both veyyon and vey, so binding it anyway would give your tool Veyyon’s subcommands. You can ask for that form yourself:

$ veyyon completions zsh --no-alias

Updates keep that decision. When Veyyon rewrites your completion files it reads the ones already there to see whether they bind vey, and regenerates them the same way, so an update never starts completing a command that is not ours.

Uninstall

The installer removes everything it added, and only what it added: the binary, the vey alias, the shell completions it wrote, the cached native addon, and a source checkout if you made one.

The PATH line goes too. When the install directory was not already on your PATH, the installer appended two lines to your shell profile: a comment naming itself, and the line that adds the directory. On bash and zsh the pair looks like this, with the directory in single quotes so a name containing $, a backtick or a space is used literally rather than expanded when the profile is sourced:

# added by the veyyon installer
export PATH='/home/you/.local/bin':"$PATH"

On fish it is fish_add_path '/home/you/.local/bin' instead. Uninstall removes that exact line, and the comment directly above it when the comment is still there, and nothing else: a line you wrote yourself that happens to name the same directory stays. Installs made before the quoting was added wrote export PATH="/home/you/.local/bin:$PATH", and uninstall recognizes that older form too, so upgrading and then uninstalling does not strand a line in your profile.

Because a profile is read when a shell starts, the shell you ran the uninstall in still has the old entry on its PATH, and bash and zsh also remember where they last found a command. The uninstall reports it:

veyyon uninstalled.
  your shell keeps the old PATH entry until it reloads: exec $SHELL -l

Without that, typing veyyon straight after uninstalling answers “No such file or directory” for a path you can see is gone, which reads as a half-finished uninstall.

It also reclaims what an UPDATE may have left. An update stages the new binary beside the old one and keeps the one it replaces as a backup until the new one has proved itself, and on Windows that backup cannot be deleted while the process holding it is still running, so a veyyon.<id>.new or a veyyon.<id>.bak can outlive the update that made it. Uninstall removes those too, so the install directory is left empty rather than holding a few hundred megabytes you have no name for. A backup you saved yourself under a name of your own is left alone.

Two things it deliberately leaves behind. If you already had your own vey command, the installer never created that alias in the first place (it reports that at install time and prints the veyyon command instead), so uninstall does not touch it or its completion file. And if a checkout at ~/.veyyon/src has uncommitted edits or commits on a local branch that is on no remote, it is moved to ~/.veyyon/src.bak-<timestamp> instead of being deleted, so nothing you wrote is lost. Older installers created that tree. The current installer never does, so uninstall only ever cleans up one an older version left behind.

$ curl -fsSL https://get.veyyon.dev | sh -s -- --uninstall

On Windows:

& ([scriptblock]::Create((irm https://veyyon.dev/install.ps1))) -Uninstall

Then remove your 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 "$VEYYON_CODING_AGENT_DIR"

Signing in

Veyyon authenticates to whichever provider you point it at and calls provider APIs directly with keys you supply. Optional OpenTelemetry export runs only when OTEL_EXPORTER_OTLP_* is configured. Logins are provider-scoped: authenticating anthropic does not authenticate openai, and each provider tracks its own credentials. Those credentials are shared across profiles by default (see Credentials are shared across profiles).

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 github-copilot.
• /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 first-run setup (veyyon setup, or /setup later) walks the same flow.

Using several accounts for one provider

You can sign in to the same provider more than once. Run /login anthropic twice with two different logins and Veyyon stores both, each with its own quota. To see them, open the account manager:

/providers

The sidebar lists your providers and the body lists that provider’s accounts, one row each, with the email, the plan, how the credential was supplied, and how much of its quota is spent. A row marked this session is the one serving your current session.

From that card you press enter to use the selected account, n to name it, r to re-check its health, u to open its usage, x twice to log it out, and a to add another account for the same provider. /account manager opens the same card.

The last row of the list is + add another … account. It is a position in the list like any other: arrow down past your last account to land on it, and press enter there to start a login. The mouse works on the card as well. Click an account to select it, click that last row to start the login, and click any key chip in the footer to run what it names.

The provider list filters. Press ctrl+s, type part of a provider’s name or id, and the sidebar keeps the providers that match; the arrows move within them and enter still switches to the selected account. Press esc to leave the filter and get the full list back, and esc again to close the card.

Switching is per provider. Choosing another Anthropic account changes Anthropic and nothing else, because several providers serve one session at the same time: your main model, your subagent roles, and web search can each be a different provider. Moving between providers is a model choice, so it lives in /models.

Naming an account

An email is not always the thing you recognise, especially when two subscriptions share one login. Give an account a name and every surface uses it:

/account name work

The name belongs to the account, not to the stored token, so it survives a token refresh and a later re-login to the same account. An account you never named shows its email instead, and Veyyon tells you how to set one.

Which account am I using?

/account

This reports one line per provider your session has actually routed to, with the account it is using and that account’s remaining quota. A provider you hold credentials for but have not used this session is not listed.

If your chosen account hits its rate limit, Veyyon moves to another one so your work continues, and reports it:

Anthropic          personal                    main model  (opus-5)
                   pinned to work, rotated off it (usage limit)
                   /account switch anthropic to re-pin work · 2h 14m until it unblocks

Your choice is kept, not discarded. Once the limit resets, traffic returns to the account you picked with no further action.

When a login is signed out for you

A stored login can stop working without you doing anything: the provider revokes the grant, or a token refresh fails and the credential is set aside. Veyyon does not hide that. The account manager marks the provider and prints the provider’s own reason, so you can tell a revoked grant from a temporary outage:

Kimi Code · 1 account
  a previous login was signed out: oauth refresh failed:
  invalid_grant: The provided authorization grant is invalid
  press a to sign in again

If that provider had only one login, it now has none, and the card states that rather than showing the provider as one you never signed into. /account shows it too, so you do not have to open the card to find out:

1 provider has a signed-out login (Kimi Code) · /providers to sign in again

A logout you performed yourself is not reported this way. You already know about it.

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/handbook/src/architecture/secrets.md for the broker model.

Using an environment variable instead

Every API-key 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. OAuth-only providers (for example google-antigravity, google-gemini-cli, kimi-code) take no key variable: sign in with /login.

The full provider → variable map lives in Providers. .env files are loaded from <cwd>/.env, ~/.veyyon/profiles/default/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 OAuth credential (refreshed as needed).
4. A stored API key in the auth store (persisted by /login).
5. The provider’s environment variable (including .env).
6. Any other stored API-key credential, then a custom-provider resolver fallback.

Stored credentials live in a machine-wide auth store at ~/.veyyon/shared-auth/agent.db (or the configured auth-broker snapshot in broker mode). VEYYON_CODING_AGENT_DIR relocates the agent base for a profile’s own files, but the shared auth store stays at the global config root so every profile reads the same logins.

Credentials are shared across profiles

By default every profile reads one machine-wide set of provider logins, so signing in once works everywhere. The first time a profile opens the shared store, any login already saved in that profile is promoted into it, so turning sharing on never signs you out.

To give a profile its own private credentials instead, turn sharing off in the global config ~/.veyyon/config.yml:

profileSharing: false

or toggle Share Credentials Across Profiles on the Global tab of /settings. With sharing off, each profile keeps its logins in its own ~/.veyyon/profiles/<name>/agent/agent.db and never reads another profile’s credentials. The auth broker (above) is a separate cross-host mechanism and is unaffected by this setting.

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/profiles/default/agent/models.yml. A new BYOK provider becomes selectable by adding a providers: entry, not by changing code. See Configuring providers and docs/handbook/src/reference/providers.md.

See also: Models and providers and the CLI reference.

Quickstart

This is the short path: install Veyyon, start a session, and make one small edit. For the full walkthrough, see Getting started.

Before you start

Check whether Veyyon is already on your machine:

which vey
vey --version

If it is missing, the one-command installer wires up your PATH, shell completions, and the vey alias:

curl -fsSL https://get.veyyon.dev | sh

You can also pin a release binary with curl -fsSL https://get.veyyon.dev | sh -s -- --ref v1.0.11. The installer only ever downloads a published release binary. To run an unreleased ref instead, clone the repository yourself and run bun run setup && bun dev in that checkout. See Install.

Check the environment

veyyon plugin doctor

Inside the TUI, /debug opens interactive diagnostics. See Diagnostics and health.

By default, your config and sessions live under ~/.veyyon/profiles/default/agent/. Two environment variables move them: VEYYON_CONFIG_DIR renames the home-relative config directory, and VEYYON_CODING_AGENT_DIR relocates the agent base. Named profiles use ~/.veyyon/profiles/<name>/agent/.

Start your first session

cd my-project
vey

The first interactive launch shows the first-run setup (splash, providers, glyphs, theme, outro), then the welcome screen and composer. Resuming a session, or setting VEYYON_SKIP_SETUP=1, skips it. You can re-open provider setup later with /setup, or run veyyon setup from the shell. To manage the accounts you already have, use /providers.

After setup, you should see the TUI composer, the model indicator, and your 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. Choose Approve (or Deny) and press Enter when it prompts you.

Composer conveniences

A few keys do a lot in the composer:

• @ completes file paths (fuzzy file references).
• / opens the slash commands, such as /help, /tree, and /settings.
• Esc interrupts a running turn.
• /hotkeys lists the active keyboard shortcuts.

Next steps

• Editing and repair
• Safety
• Configuration
• CLI reference

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

Getting started

Four steps take a fresh machine to a first change in a project: install, run the first-time setup, sign in to a provider, hand Veyyon a task.

1. Install

The quickest path is the one-line installer, which downloads a self-contained binary and links a short vey command.

$ curl -fsSL https://get.veyyon.dev | sh    # Linux or macOS
$ vey --version

On Windows, run irm https://veyyon.dev/install.ps1 | iex instead.

The installer only downloads a published release binary. If you would rather build from a checkout, clone the repository yourself, into any directory you like, and run the setup script there.

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

bun run setup installs the workspace dependencies and builds @veyyon/natives, the Rust addon. That checkout is yours: you chose where it lives, and the installer neither creates it nor writes into it. Your configuration lives under ~/.veyyon, and the default profile keeps its agent state in ~/.veyyon/profiles/default/agent/.

The installer sets up shell completions for you when your shell supports them. The Install chapter has the full details.

2. First launch

The first time you run veyyon (or any time you run veyyon setup), the setup UI walks you through five steps:

1. The splash screen.
2. Providers, where you sign in or paste an API key, and optionally enable web search.
3. Glyphs, where you choose a Nerd Font, plain Unicode, or ASCII.
4. Theme.
5. The session welcome.

You can return to provider setup later with /setup inside the TUI, and manage the accounts you already have with /providers. To skip setup entirely, set VEYYON_SKIP_SETUP=1, or resume an existing session.

3. Sign in to a provider

Veyyon needs at least one model provider. You have three common options.

Use an API key. Set the provider’s key in your environment, then pick one of its models in /model. For example, export DEEPSEEK_API_KEY and choose a DeepSeek model.

Sign in with OAuth. Run /login, or name a provider directly with /login anthropic. These are the same flows the Providers setup scene uses.

Add a custom gateway. Declare a provider in ~/.veyyon/profiles/default/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

Run a local model. With the Ollama daemon running, Veyyon discovers local models and needs no key:

$ ollama serve
$ veyyon

Open /model and choose an ollama/... entry from the discovered list.

For the full picture, see Models and providers and Configuring providers.

4. Run your first task

Change into a project you know, and start Veyyon.

$ cd ~/code/my-project
$ veyyon

Describe a small, checkable task:

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

A typical run looks like this:

1. Veyyon reads the files it needs with read and search.
2. It proposes an edit through the hashline edit and write tools.
3. When your policy requires it, you approve the tool call. The tools.approvalMode setting sets when this happens; see Safety.
4. The change lands, and the diff appears in the TUI.
5. If you asked for tests, Veyyon runs them with bash; under the default auto mode that call runs without a prompt, and a stricter mode prompts you first.

Approval mode

Every tool call falls into one of three tiers: read, write, or exec. The tools.approvalMode setting sets which tiers run without asking and which ones prompt you first.

The older names still work: always-ask maps to ask, and write and auto-edit both map to ask-command. The schema default is auto. You can change it in /settings or in your config. See Approvals and Safety.

Where to go next

A few surfaces are worth trying early:

• A multi-file change. Ask for a refactor across modules. Hashline edits batch the paths together.
• The session tree. /tree jumps back to an earlier message and branches from it inside the same session file.
• Model slots. /model sets the interactive model. You set the subagent and compaction models in settings; see Models, roles, and profiles.

From here, the Quickstart is a shorter walkthrough, Configuration covers settings, Sessions explains resuming and branching, Memory covers the mnemopi backend, and Diagnostics covers the doctor and debug tools.

Configuring providers

Copy-paste setups for bring-your-own-key (BYOK) and local providers. Once a provider works, see Models and providers to choose and switch models. For what the harness owns versus what the provider owns, see Model contract.

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

Anatomy of a provider entry

# ~/.veyyon/profiles/default/agent/models.yml
providers:
  acme:
    baseUrl: https://api.acme.example/v1
    api: openai-completions
    apiKey: ACME_API_KEY        # env-var name; `literal:text` for verbatim 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 with an error message: validate with veyyon models.

After editing, restart the session.

OpenAI (API key)

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

OpenAI is API-key only: export OPENAI_API_KEY or pin apiKey in models.yml. 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 the interactive model and optional roles in the profile config.yml (modelRoles.default is the interactive model):

# ~/.veyyon/profiles/default/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 models refresh <provider>
$ veyyon --model <provider>/<id> "reply with the model name you are"

The provider form bypasses the cache and contacts only the named provider. Omit it when you need to refresh every configured catalog.

If discovery or auth fails, the error states 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

The vocabulary for how Veyyon runs: sessions, permissions, and the boundary between the harness and the model provider. For operator commands see Using Veyyon; for feature guides see Features.

Pages

The CLI is veyyon. It calls a configured model endpoint with your credentials and runs a tool loop: read, edit, verify, stop. The pages below define the units and contracts of that loop, so that later chapters can assume you know them.

Foundations that pair with these pages

The foundations pages give the design spine without repeating the operator workflow.

• Architecture at a glance maps the subsystems to their responsibilities.
• For provider and model configuration, see Providers and docs/handbook/src/reference/providers.md.

How the pieces fit

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

Changing providers changes the endpoint, the credentials, and the model id. Tool repair, edit verification, approvals, and context compaction stay the same, because they are harness behavior. See Configuring providers and Models and providers.

Related reading

• Permission model and Approvals cover the approval modes.
• Approvals usually need no tuning: the default auto runs every tier while the per-tool policies, the working-directory boundary, credential use, and a tool’s own critical commands all still prompt. Pick a rung explicitly only when you want a different trade-off, and note that a headless run has nobody to answer a prompt, so a rung that prompts turns a tool call into a failure rather than a pause.
• Non-interactive mode covers 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, …)
        ├─ approval-mode 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-oriented rollout JSONL files. Each history entry has an id and a parentId, which makes the rollout a tree rather than a linear chat log. New history is appended. Header or representation maintenance may atomically rewrite the file, but it preserves every history entry.

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 ctrl+q or ctrl+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 so a resumed session does not require the full raw transcript.

Prefer /compact when you need a summary to retain state. Prefer the /new command when prior transcript is no longer useful and you want a clean session without summarization. See Slash commands.

The rollout

Session history lives in one layer: the JSONL rollout. Every event is one line: a user message, an agent response, a tool call, a compaction, a goal update, or a branch summary. The rollout is the only source of truth. Listing and resume read it through the active storage backend, including indexed Redis and SQL storage. A non-empty rollout without a valid header is rejected without changing its bytes; malformed later records are skipped with an operator-visible path, line, byte, and shape warning. Goal cards persist as rollout entries. There is no separate session-state database.

How the pieces relate

• A session contains 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 holds every turn, branch, and system event.
• The goal card is a separate context slot that contains the current objective across turns and compactions. See Goal state and long sessions.

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

Every tool the model attempts to run passes through one gate: the approval mode. The approval mode sets whether a tool runs on its own or waits for you to say yes. You set it once in config, and you can change it for a single run from the command line.

One setting controls this: tools.approvalMode. Nothing else confines what a command can do once it runs. Veyyon does not wrap commands in an operating-system sandbox (Landlock, seccomp, Seatbelt, or bubblewrap), so the approval mode is the boundary. Treat it as the boundary.

Tool tiers

Every tool belongs to one of three tiers, ordered by how much it can change:

• read looks but does not touch: read, search, and directory listing.
• write changes files: edit and write.
• exec runs commands: bash and anything else that executes a program.

A mode approves whole tiers, not individual tools. That is why the tiers come first: once you know which tier a tool is in, the mode determines whether it runs.

Modes

A mode is a named choice of which tiers run without asking. There are five:

The schema default is auto. Three older names still work: always-ask maps to ask, and write and auto-edit both map to ask-command.

Set the mode in config, or override it for one run:

$ veyyon --approval-mode ask-command "run the tests and fix failures"

The launch flags --yolo and --plan-yolo set yolo and a plan-mode variant of it.

The working-directory boundary

A tier describes what kind of thing a tool does. It does not identify which file the tool is about to touch. In ask-command and auto, the write tier is approved, so write runs without asking whether the target is src/main.ts or a file in your home directory.

The working-directory boundary is the second question, asked after the tier:

Does this call touch a path outside the session working directory?

If it does, the call requires approval even though its tier would have allowed it. This holds in plan, ask, ask-command and auto, so the shipped default is inside it. It does not hold in yolo, which turns off permission entirely.

Say you launched in ~/projects/api and the model runs this:

$ veyyon --approval-mode ask-command "update the config"

Writing ~/projects/api/config.yml runs without asking, because it is inside the working directory and write is an approved tier. Writing ~/.ssh/config prompts, because it is outside, even though the tier is the same.

The check looks at where a path really leads, not at how it is spelled. A path written entirely inside the working directory that reaches outside it through a symlink counts as outside. A path that cannot be resolved at all also counts as outside, because treating an unreadable path as safe is the assumption you least want to be wrong about.

These tools take part: read, write, edit, ast_edit, search, inspect_image, and set_cwd.

set_cwd is on that list because it changes the working directory itself. If it were not bound, you could move the boundary instead of obeying it: re-root to the parent directory, and every later write counts as inside. So re-rooting outward prompts, the same as writing outward. Re-rooting into a subdirectory does not prompt, because that narrows what the session can reach rather than widening it.

When no interactive prompt is available, such as a headless or ACP run, a call that needs approval fails instead of proceeding. The error states the path that crossed the boundary, so you can see why the run stopped.

Secrets in arguments

A tier does not tell you whether a call is about to spend a credential either. The secret-use boundary is the third question, asked the same way and in the same modes:

Do this call’s arguments carry a stored secret?

Your secrets reach a tool as real values. The model works with placeholders such as #GITHUB_TOKEN#, and Veyyon substitutes the credential just before the tool runs, so the model can use a secret it never reads. That substitution used to be recorded and never asked about: secrets.auditLog could report afterwards which credential an agent had spent, and nothing prompted you first.

Now a call whose arguments carry a real credential requires approval in plan, ask, ask-command and auto, even when its tier would have allowed it. The prompt states the secret and never shows its value:

Allow tool: bash
Reason: This call uses stored secret: GITHUB_TOKEN. Approving it runs the call with the
real credential.

As with the working-directory boundary, yolo turns permission off entirely and turns this off with it. Every other rung keeps it, the shipped auto included. A call that mentions a placeholder without expanding it, such as one made while secrets.enabled is false, is not a credential reference and does not prompt.

Per-tool overrides

When you want one tool to behave differently from its tier, name it under tools.approval. Each entry maps a tool to allow, deny, or prompt, and that choice wins for that tool whatever the mode is, with one exception: while a plan-mode session is active, a per-tool allow does not let an exec-tier tool run. Plan mode is a cap rather than a default, so it outranks both the configured mode and the per-tool setting. A deny is a hard block in every direction.

# ~/.veyyon/profiles/default/agent/config.yml
tools:
  approvalMode: ask-command
  approval:
    bash: prompt
    read: allow

Here the mode is ask-command, so writes run without a prompt. The override then pulls bash back to prompt, so commands still stop for your approval.

Critical bash commands

Within the exec tier, a guard (packages/coding-agent/src/tools/bash-guard.ts) forces a prompt in plan, ask, ask-command and auto, even over a per-tool allow. It has two halves.

The first half judges what a command would DELETE, and it judges the paths after expansion rather than the command as text. A tilde and $HOME are resolved, so rm -rf ~/ and rm -rf "$HOME"/ are recognized as the home directory. Every target is judged, not just the first, so rm -rf tests/ / is caught. Recursive deletes of the home directory, of any directory containing it, of the system directories, and of the directories that hold your credentials all stop for approval. So does a recursive delete whose target the guard cannot resolve, such as rm -rf "$dir"/*: if $dir is empty that command starts at the root, and nothing in the command text states whether it is.

The same half stops a truncating redirect into a directory that holds credentials, because echo x > ~/.ssh/id_ed25519 destroys a private key as thoroughly as a delete does. Appending with >> is left alone, since that is how you add a key to authorized_keys.

Deletes inside your workspace are not affected. rm -rf node_modules, rm -rf dist, and rm -rf /tmp/build-1234 run without a prompt, and so does a delete inside a protected directory that does not hold credentials, such as rm -rf ~/.config/some-app. Ordinary redirects, such as bun test > /tmp/results.txt, are not affected either.

The second half is a pattern list (FLAGGED_BASH_PATTERNS, in the same file) for the shapes that are about text rather than paths, and each entry is recorded as one of two strengths. Destructive covers fork bombs, disk destruction, and writes to system credential files. Dangerous covers a remote fetch piped to a shell, host control commands such as reboot, and a shell wired to a network socket: they run code nobody read, or take the machine down, without destroying data.

Both halves ship with Veyyon and cannot be narrowed. You can widen the first half with tools.protectedPaths, a list of absolute paths (a leading ~ is expanded) that a recursive delete must also stop for:

tools:
  protectedPaths:
    - /mnt/photos
    - ~/Documents

That setting only adds. Nothing in the built-in judgement reads configuration, so no value you write there can stop the guard refusing your home directory, the system roots, or your credentials. An entry that is not an absolute or ~-relative path is ignored, because resolving it against a guessed working directory would protect somewhere other than what you wrote.

The first half and the destructive patterns stop for approval in yolo too, and the /yolo session bypass does not lift them. That is the one place yolo is not absolute, and it is deliberate: without it, the commands the guard considers most destructive would be the ones most likely to run in the mode that skips the check. The dangerous patterns are an ordinary prompt instead: every rung below yolo stops on them, and yolo does not, because a rung whose whole promise is that it stops asking cannot be asking about an install command the operator typed. To turn the floor off, set tools.approval.bash to allow, which is read as a decision you made on purpose. Setting it to deny remains a hard block.

The guard reasons about what a command will do, and that reasoning can be wrong: a shell function, an eval, or a script invoked by name defeats any parser. Treat it as a seatbelt, not as containment.

On deny

When a tool is denied, or a policy check fails, Veyyon returns an error to the model. It does not retry with more permission. An error never escalates what the model is allowed to do.

Related

• Approvals
• Safety
• CLI

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.

The contract between the harness and the model. For copy-paste provider setup, see Configuring providers. For model switching, see Models and providers.

The three things you bring

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

For BYOK providers, Veyyon calls the configured endpoint with your credentials (no hosted proxy required). Optional OpenTelemetry export is separate and only when OTEL_EXPORTER_OTLP_* is set.

Example shape

# ~/.veyyon/profiles/default/agent/models.yml
providers:
  deepseek:
    baseUrl: https://api.deepseek.com
    api: openai-completions
    apiKey: DEEPSEEK_API_KEY   # env-var name; unset means no key, not a 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).
• Approval modes (tools.approvalMode) that gate which tool tiers run without asking.
• 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.

Provider is configuration (endpoint, credentials, model id). Keep the same commands.

What the provider owns

The provider defines 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 returns an error; it does not invent an empty catalog on failure.

Everything beyond the built-in catalog is data in models.yml, see Providers and docs/handbook/src/reference/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 from global, active-profile, and project AGENTS.md layers, sticky rules, and session steers. A caller may replace the base for one invocation with --system-prompt.
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 feature flags, harness-profile allowlists, and plan-mode narrowing. A per-tool deny policy does not filter this list; it rejects the call at dispatch.
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.

Default edit mode is hashline (edit.mode: hashline). When edit.mode is apply_patch, the provider wire form is derived from the API kind by default; an optional catalog override can pin the tool shape to function or freeform. The Function form keeps structured edits available on chat-wire endpoints (Ollama, LM Studio, DeepSeek, and similar). 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, 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 is responsible:

• 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.
• Approval or critical-pattern 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 with an error message; 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.tiny (or smol): lightweight background work (titles, memory, auto-thinking).

Subagent models are not roles. They live in the Subagents settings area, on two exclusive scopes. With Same Model for All Subagents off, the first of these names the model: that agent’s row in subagent.agents, then the agent definition’s own model:, otherwise the default model role. With it on, subagent.model names it for every agent and the rows above are not read. There is no silent blend, and a configured value that matches no available model rejects the spawn instead of quietly handing the decision to the next layer. /agents shows the resolved model and which setting decided. See Settings: Subagents and Models, roles, and profiles.

Automation note

For non-interactive runs, pass the prompt and pick an approval mode that matches your trust boundary. A headless run has no terminal to answer a prompt on, so a rung that prompts turns the gated tool call into an error rather than a pause: the default auto runs every tier while the working-directory, credential and critical-command guards still stop the calls they cover.

$ veyyon --print "run the unit tests and fix failures"

Use --yolo (auto-approve everything) only in trusted automation, ideally in an externally isolated environment (Docker, a VM, a CI jail), since Veyyon does not sandbox the commands it runs.

What stays constant

• Workflow shape: read, edit, verify, stop when done.
• Edit verification, approvals, and context handling are harness behavior.
• Provider is configuration: endpoint, credentials, and model id.

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: the approval modes.
• Signing in: interactive and env-var auth paths.

Features

Features, in two groups: the surfaces of an everyday session, then what extends and customizes the agent. Worked examples are at the end.

Interactive surfaces

These are the parts of the TUI you touch every session:

• Status line and multi-agent UI covers the status segments, the subagent dashboard (/agents), jobs, and the swarm view.
• Keybindings covers the chords.
• The composer gives you prompt history, @ and / completion, and Esc to interrupt. See Quickstart and Keybindings.
• Web search covers searching from inside a session.

Extend and customize

These add capabilities or change how the agent runs:

Recipes

For worked examples, see the Task guides. For the full command and setting reference, see Reference.

Editing and repair

Editing reliably is the core of a coding agent, so it is worth understanding how Veyyon does it. The default edit surface is hashline. In practice that means three things work together: numbered lines that come back from read and search, snapshot tags that identify a known state of a file, and the edit tool with its SWAP, DEL, and INS operations.

For the design behind the edit and repair path, see The hashline edit engine.

Failure modes

Models often emit slightly wrong tool JSON, or line anchors that have gone stale. Hashline catches a stale [path#TAG] tag and returns recovery hints instead of writing the wrong bytes. On top of that, general schema repair runs on every tool call before validation. See Repair overview.

Write path versus edit path

Veyyon keeps surgical edits and whole-file writes separate on purpose.

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

Tools

You set edit.mode to hashline, apply_patch, patch, or replace in config.yml, or use VEYYON_EDIT_VARIANT for a one-shot override.

Hashline workflow

The loop is short:

1. read (or search) returns [relative/path#TAG] and LINE:text rows.
2. The model calls edit, anchoring each section on the same TAG.
3. On success, the output includes a fresh [path#NEW_TAG] and a compact diff.

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

Verification after a mutation

After edit, write, or ast_edit changes a path, Veyyon records the mutation. If the model tries to finish without a later successful bash, eval, debug, or browser result, Veyyon gives it one targeted continuation turn. The model must run the check and report what the result established.

A successful command is execution evidence. It does not prove that the command tested the right behavior. You should still read the final verification claim and confirm that it matches the command or browser scenario that ran.

Safety

Edits honor the approval mode, just as bash does. A tools.approval.<tool>: deny policy keeps the tool in the model’s list but rejects every call at dispatch with an error stating the policy. Tools leave the model’s list via <tool>.enabled: false, harness-profile allowlists, tools.discoveryMode (BM25 hiding), extension or agent tool-set overrides, or agent definitions. Plan mode keeps the list and blocks mutations at approval time.

Hashline is the primary write path, and apply_patch is a compatibility mode. There is no single V4A applier that routes every mutation through a make_update_patch envelope.

Approvals

Approvals are how you decide which tools run without asking. One setting drives them: tools.approvalMode. There is no operating-system sandbox behind it (no Landlock, seccomp, Seatbelt, or bubblewrap). Shell commands and file writes run as your user, bounded only by this policy, per-tool tools.approval overrides, and the hard-coded flagged bash patterns below.

Operator reference. For the model behind it, see Permission model. For the wider boundary, see Safety.

Tool tiers

Modes

Schema default: auto. Legacy aliases: always-ask → ask, write and auto-edit → ask-command.

$ veyyon --approval-mode ask-command
$ veyyon --yolo                    # same as --auto-approve → yolo
$ veyyon --plan-yolo               # plan now; yolo after leaving plan mode

tools:
  approvalMode: ask

The approval prompt

When the active mode requires approval for a tool call, the TUI shows a Permission required card. The card shows the tool, states that the decision applies to this call only, separates the reason from the requested command or file operation, and waits on four options:

• Approve: run this call once. Nothing is remembered.
• Approve for session: run this and every later call to this tool, until you exit.
• Deny: reject this call and return Tool call denied by user: <name> to the model.
• Deny for session: reject this and every later call to this tool, until you exit.

The two “for session” rows are session memory, not policy: nothing is written to tools.approval, and the next launch prompts again. A remembered decision also covers only the ordinary tier prompt. The three prompts that are about a call’s ARGUMENTS rather than its tool name still prompt every time: a flagged bash command, a path outside the working directory, and a call that spends a stored credential.

The selected option uses a radio marker and includes a short description. Navigate with the usual list keys (up/down, enter to confirm, esc to cancel; cancelling counts as a denial). Denied actions return an error to the model, and permissions are never widened.

Headless

veyyon --print has no terminal to prompt in. If the mode would require approval, the tool call fails with an error that explains the required setting or override (set tools.approvalMode: yolo, add tools.approval.<name>: allow, or use an interactive UI), and the model receives that error. To run unattended, pass --yolo or pick a mode that does not prompt for the tiers you need. The process exit status follows the run.

Critical bash commands

Some shell commands always prompt in plan, ask, ask-command and auto, even over a per-tool allow override. The guard lives in packages/coding-agent/src/tools/bash-guard.ts and has two halves.

The first half judges what a command would delete, after expansion rather than as text. It resolves a leading tilde and $HOME, judges every target rather than only the first, and stops a recursive delete of the home directory, of anything containing it, of a system directory, or of a directory holding your credentials. It also stops a recursive delete whose target it cannot resolve, such as rm -rf "$dir"/*, because an empty $dir makes that command start at the root. It also stops a truncating redirect into a credentials directory, such as echo x > ~/.ssh/id_ed25519; appending with >> is left alone. Deletes inside your workspace, such as rm -rf node_modules or rm -rf dist, run without a prompt, and so do ordinary redirects such as bun test > /tmp/results.txt.

The second half is a pattern list (FLAGGED_BASH_PATTERNS, same file) for shapes with no path to expand, and each entry records what it would do. The destructive ones are sudo rm, recursive chmod/chown on /, fork bombs, disk and filesystem destruction (mkfs, dd to a device, writes to /dev/sd*), and writes to /etc/passwd/shadow/sudoers. The dangerous ones are a remote fetch piped to a shell (curl … | sh and its process-substitution and eval variants), host control (shutdown, reboot, kill -9 1), and network shells (nc -e): these run code nobody read or restart the machine, without destroying anything.

Neither half can be narrowed; the guard exists because a false negative costs data loss or a compromised host. You can widen the first half with tools.protectedPaths, a list of absolute paths (a leading ~ is expanded) that a recursive delete must also stop for. It only adds: nothing in the built-in judgement reads configuration, so no value there can stop the guard refusing your home directory. See the permission model for an example.

The destructive half, and the whole of the first half, stop for approval in yolo as well, and the /yolo session bypass does not lift them. That floor is the one place yolo is not absolute. The dangerous half stops on every rung below yolo and not on yolo itself, because a rung whose entire promise is that it does not prompt cannot be stopping an install the operator typed. To turn the floor off on yolo, set tools.approval.bash to allow; below yolo an allow is outranked by the guard, and deny is a hard block on every rung.

Separately, the bash interceptor (bashInterceptor.enabled, default off) blocks shell commands that duplicate dedicated tools, so the model reaches for read/search instead of cat/rg/find. Its rules live in bashInterceptor.patterns.

Related

• Permission model
• Non-interactive mode
• Safety

Safety

Commands and file writes go through approval mode (tools.approvalMode). There is no OS command sandbox (Landlock, seccomp, Seatbelt, bubblewrap). Policy details: Approvals. Concepts: Permission model.

Task subagents can use filesystem isolation (CoW worktree backends via subagent.isolation.*) so their edits land in a private tree until merged. That is change-control for subagents, not an OS process sandbox. See the task tool docs, or the Isolation group in the Subagents settings tab.

Operator-visible cases

Headless

veyyon --print has no TTY for prompts. Set --approval-mode / --yolo explicitly for the job. Reserve full auto-approve for disposable runners. See Non-interactive mode.

Related

• Approvals
• Configuration
• Repair

Resource limits

Veyyon caps what the processes it runs may consume: CPU, memory, disk writes and process count. Every limit is off by default, and each has two scopes:

machine:
  cpuLimitCores: 8      # 0 (the default) is off, at both scopes
  memoryLimitGb: 0
  writeBudgetGb: 0
  maxProcesses: 0
session:
  cpuLimitCores: 2      # this session's commands get at most two cores
  cpuLimitKill: false   # what to do past the budget; see below
  memoryLimitGb: 0
  writeBudgetGb: 0
  maxProcesses: 0

Set both in /settings under Resources, where the two rows for a resource sit side by side. Machine values are written to the global configuration file, so they hold across every project, profile and concurrently running veyyon.

A session limit alone is per session: two sessions capped at 2 cores each may use 4 between them. A machine limit is what bounds the pair.

How the two scopes combine

The machine scope is not a second limiter running beside the first. Session groups are created inside the machine group, so the kernel bounds the whole subtree:

<delegated parent>/
└── veyyon.machine/          ← machine.* limits are written here
    ├── veyyon-<session-a>/  ← session.* limits
    └── veyyon-<session-b>/

One set of kernel files enforces both tiers, so they cannot disagree. A machine limit binds a session that sets no limit of its own, and binds a session whose own limit is looser, because the parent bounds its children. The machine group is left in place when a session ends, since another veyyon’s sessions live inside it.

Writes are counted from two places because they arrive from two places: a spawned command writes through the kernel and appears in io.stat, while the file tools write in-process and are tallied to a file inside the machine group, so concurrent veyyon processes see each other’s totals.

What is capped

Every process a session spawns to do its work joins the budget. That covers bash commands (plain and PTY), MCP stdio servers, the exec calls that custom tools, custom commands, extensions, and hooks make, background processes from the launch tool, the eval kernels (Python, Ruby, Julia), language servers, debug adapters, the managed browser, git and jj, ssh, and the installs that plugins run. A capped process passes the budget to its own children, by cgroup and Job Object inheritance on Linux and Windows and by a process-tree walk on macOS, so a build that spawns a compiler fleet is still one budget.

A spawn is refused while the budget is saturated or the group could not be created. That applies to a bash command, a new MCP stdio server, an exec call from a custom tool, custom command, extension, or hook, and a new eval cell. An extension module the CLI loads before a session exists resolves the root session’s gate when it spawns.

Some processes belong to no single session and join the root session’s budget instead. Those are the shared harness workers, such as the tiny title model and embeddings, and the speech capture and playback helpers.

Five kinds of process stay outside the budget. Each is outside for a reason rather than by oversight:

• Anything that starts before a session exists. Host capability probes, the shell environment snapshot, model provider probes, and the ssh bootstrap for a remote auth broker all run when there is no budget to join.
• The harness itself. Agent turns, the TUI, and the relaunch that replaces the veyyon process.
• Programs that are yours rather than the agent’s. The editor veyyon opens a file in, the clipboard helper, veyyon shell, and the self-updater. Capping the updater could leave a half-written install, and killing your editor on a budget breach would discard unsaved text.
• Threads rather than processes. The browser tab supervisor and the JavaScript eval context run as Bun Workers inside the harness process, and a cgroup holds processes, not threads of one.
• Processes the session did not start. Attaching to a browser that is already running adopts nothing, because the session does not own that process.

If you cap a session at 1 core, veyyon stays responsive while the build under it crawls.

How it is enforced

Each control file below is written on the group for the scope that declares it, so the machine and session tiers use the same mechanism one directory apart:

Where the operating system offers a per-group CPU quota, the kernel does the capping:

• Linux uses a cgroup v2 directory per session with cpu.max set to the core count. A positive budget smaller than one microsecond of the 100ms period writes 1 100000, not a freeze quota of 0. If the harness’s own cgroup is not writable, veyyon starts a delegated transient service in the systemd user manager (Delegate=yes, CPUQuota) and adopts children into that cgroup. It is not a --scope unit: a scope would block on the placeholder and leave setup failed. A positive CPUQuota too small for systemd to express floors at 0.001% rather than 0%.
• Windows uses an unnamed Job Object with a hard CPU rate cap. CpuRate is a fraction of host logical processors (4 cores on a 16-processor machine is 2500, not 40000), counted with GetActiveProcessorCount rather than this process’s affinity mask, so a 2-core budget inside a 2-of-16 slice is 12.5% of the machine rather than 100%. Setting the limit to 0, or /cpu-limit lift, turns rate control off rather than flooring to 0.01% of the machine.

A once-per-second watcher reads the group’s usage on top of the kernel cap. When usage stays pinned at the budget for about three seconds, new commands are rejected with an error that names the budget, the measured usage, and the fix (raise session.cpuLimitCores or wait), until usage drops. The kernel cap is the enforcement of last resort: if the watcher lags, commands throttle, they never run free.

With session.cpuLimitKill: true, a sustained breach sends SIGTERM to the group’s processes, then SIGKILL on the next watcher tick if they are still over budget. The kill is reported as a budget action: the notice and the killed command’s result both state the command was stopped by the CPU budget, not that it crashed.

macOS has no per-group CPU quota. There the budget is policy only: new commands are rejected while the group is saturated, running members (including descendants of the adopted child, so a make -j compiler fleet is in the same set) are reniced, and session.cpuLimitKill still kills. Nothing throttles. The settings row and the startup warning state this, and the same warning appears on any platform where no backend works. A configured limit never fails silently: if the group cannot be created, new commands are refused rather than run uncapped.

Changing session.cpuLimitCores mid-session takes effect on the next command: the live quota is rewritten, and setting it back to 0 lifts it.

Example

Cap a session to 2 cores and run a parallel build:

# ~/.veyyon/profiles/<profile>/agent/config.yml
session:
  cpuLimitCores: 2

$ veyyon
> run make -j16 and watch the load

make spawns sixteen compilers, but the whole tree shares two cores: the build takes roughly eight times longer than uncapped wall time would suggest, and the rest of the machine stays idle. While the build runs flat out, another command is rejected:

Refused to start a bash command: this session's CPU budget of 2 core(s) is saturated
(spawned commands used ~2.00 cores for the last 3s). New commands run again once usage
drops below the budget. Fix: wait for the running command to finish, or raise
session.cpuLimitCores.

With session.cpuLimitKill: true, the same breach ends the build instead:

Session CPU budget exceeded: limit 2 core(s), spawned commands used ~2.00 cores for 3s.
Sent SIGTERM to 9 process(es) because session.cpuLimitKill is on. A command that just
stopped was killed by the CPU budget, not a crash.

Reading and lifting limits

/cpu-limit reports; it does not configure. Limits are set in /settings under Resources.

lift writes nothing to disk: the configured value returns on the next session. It does not reach a machine limit, which belongs to every session at once.

Related

• Approvals
• Non-interactive mode
• Settings reference

Secrets

You often need the agent to run a command that requires a credential. A deploy needs a token. A database query needs a password. If you paste the value into chat without protection, it can reach the model provider and any session export you create.

Veyyon can keep the value away from the provider while the command still works. Some local surfaces can still contain it; those are named below.

Turning it on

Secret protection is off by default. The quickest way to turn it on is to store a credential: storing one switches protection on and reports that it did, because a stored credential is only useful once the protection that substitutes it is running.

To turn it on without storing anything, use /settings, or write it into config.yml:

secrets:
  enabled: true

The setting takes effect in the current session. Veyyon reloads environment variables, secrets.yml, and the vault when you toggle protection or run a /secret command. Moving to another working directory loads that project’s scope and drops the source project’s mappings.

Your first secret

If the credential is already an environment variable, you have nothing to declare to keep its value out of provider requests. Veyyon treats an environment variable as secret when its value is 8 characters or longer and its name ends with, or has an underscore after, one of KEY, SECRET, TOKEN, PASSWORD, PASS, PASSPHRASE, AUTH, CREDENTIAL, PRIVATE, or OAUTH.

That boundary matters, so read each keyword as a whole word rather than a substring:

The exclusions are the point of the rule, not a gap in it. Obfuscation replaces every occurrence of a value, so detecting AUTHORIZED_USER would blank out that username wherever it appeared in your transcript. PWD is excluded for the same reason and more sharply: it is your current working directory, it exists in every shell, and detecting it would replace your paths with a placeholder in every message that mentions one.

APIKEY and PRIVKEY need no keyword of their own, because KEY at the end of a name already matches them.

Adding your own keywords

The keyword list is data, not code. Drop a file at either location and its keywords are added to the built-in ones:

keywords:
  - VAULTPASS
  - SCANSEED

Your keywords follow the same boundary rule, so VAULTPASS matches VAULTPASS and MY_VAULTPASS and not VAULTPASSWORDLESS.

A user file can only add. It cannot remove a built-in keyword, so a repository you clone cannot turn off detection of TOKEN for you. A file that exists but cannot be read or parsed stops startup, because carrying on would cover fewer variables than you wrote down.

If a variable of yours is still not detected, do not assume it is covered: declare it in secrets.yml as shown below, or store it with /secret.

So a shell that already has this:

export DEPLOY_TOKEN=ghp_R2d2c3poIHRva2VuIGV4YW1wbGU

needs no configuration for defensive protection. Start Veyyon and that value is replaced whenever it appears in provider-bound text. Environment detection does not give the agent a readable inventory name. When the agent must choose and spend the credential deliberately, store the same value in the vault:

/secret from-env DEPLOY_TOKEN

That is the form you type in a terminal. Veyyon prompts for a name afterwards and generates one if you skip it. A client with no terminal, such as --print mode or an ACP editor, writes the name on the line as /secret from-env DEPLOY_TOKEN DEPLOY_KEY, because nothing there can prompt; see On a client with no terminal.

What the model sees

Every occurrence of a known value is replaced before provider dispatch. This boundary covers messages, dynamic system prompts, tool descriptions and schemas, resumed assistant text, replay payloads, and nested model calls such as title generation, image analysis, memory summaries, and speech rewriting.

The replacement happens from raw text before trimming, truncation, JSON serialization, or other lossy preparation. Veyyon resolves the live profile, project, environment, and vault runtime again for each physical provider attempt. This includes authentication retries, fallback models, delayed queues, compaction, commit analysis, evaluation, benchmarks, memory services, TTS, and image tools. A refresh cannot leave a retry using an old set of secret values.

Provider fields that are authenticated or signed cannot be rewritten safely. If a live value appears in a signature, provider item id, encrypted reasoning block, or other opaque replay payload, the request is rejected with a value-free error. Structured fields are rewritten recursively, including JSON object keys. A rewrite that would collapse two keys into one is also rejected.

Suppose a file you read contains this token:

DEPLOY_TOKEN=ghp_R2d2c3poIHRva2VuIGV4YW1wbGU

The provider receives a machine-keyed placeholder:

DEPLOY_TOKEN=#0A1B2C3D4E5F678901234567#

The placeholder is stable across restarts on the same machine. It contains a keyed HMAC rather than a load-order index, so seeing it does not give the provider an offline dictionary test for the value. A named vault entry instead uses its readable name, such as #GITHUB_TOKEN#, so the model can choose the right credential.

The model is told two things about a placeholder: that putting one where a credential belongs is expected and works, and that it is opaque otherwise. It does not have the value and cannot request it. For named vault entries it is told one more thing, which credentials it currently has, covered under What the agent knows, and when.

Using a secret in a command

This is the part that makes the feature useful rather than merely defensive. The model can put a placeholder into a command, and veyyon substitutes the real value before the command runs.

The model writes:

curl -H "Authorization: Bearer #0A1B2C3D4E5F678901234567#" https://api.example.com/deploy

The command that actually executes contains the real token. The substitution happens locally, after the model has produced the command and before the shell sees it. The model never learns the value, and the request still authenticates.

The substituted command is not written down. Veyyon records one diagnostic entry per tool call so that a session interrupted mid-call can tell you on resume what was running, and that entry stores the placeholder form, not the substituted one. This matters because /share uploads the session file and backups copy it. What the command prints is a separate question, covered under What this does not protect.

What the agent knows, and when

Store GITHUB_TOKEN today, quit, and start a new session tomorrow. Ask for your open pull requests, and the agent writes #GITHUB_TOKEN# into the curl command without you mentioning the credential again.

It can do that because the system prompt contains an inventory: the placeholders the agent is able to spend at that moment, listed by name and sorted. The inventory is built from the live secret runtime rather than from the conversation, and that is the whole reason it survives a restart. The vault is stored on disk; a conversation is not. Knowledge kept only in the transcript went away with the transcript, while the credential it described stayed exactly where it was.

The inventory holds names, and nothing else. No value appears in it in any state, and the agent has no way to request one. Around the list the agent is told what the list is for: write the placeholder where the credential belongs, the real value is substituted locally just before the tool runs, and a name that is not listed is not available.

Only vault entries are listed, because only they have readable names. A value detected in your environment, or declared in secrets.yml, becomes a machine-keyed placeholder instead, which the agent meets where the value would have appeared rather than in a list.

When protection is off, or when nothing is stored, the section is absent rather than empty. An empty heading reads as “you have no credentials”, and that is a different statement from “this session cannot spend any”. Removing the last credential takes the whole section away again, heading included.

Four moments, and what the agent learns at each:

At session start, or on resume. The inventory, rebuilt from whatever the vault holds right then. Nothing else is needed. A credential you stored last week does not have to be introduced again.

When you add one. The inventory is rebuilt so the new name is in it, and the agent is told directly, in that turn, that the credential now exists and where its placeholder goes.

When you remove or extend one. Both again: the inventory is rebuilt, and the agent is told what changed. A revocation states the placeholder is revoked and must not be used. A fresh lifetime states the credential is still available under the same placeholder. Neither notice quotes a lifetime, because a duration written into the history is wrong a minute later, and your terminal already shows you the exact time left.

When a lifetime runs out on its own. Substitution stops at the deadline itself, not a moment after, and the name leaves the inventory on the next rebuild. There is no notice on this path, because no command ran and so there is no turn to put one in. You are warned twice before it happens, which is covered under Lifetimes.

In none of these does the agent learn a value.

Why a removal is stated rather than left to the list

Dropping the name from the inventory would be the quieter design, and on paper it conveys the same thing. It does not work. Noticing that something has stopped being present in a long prompt is the kind of thing a model reliably fails at, so it goes on writing a placeholder that worked ten minutes ago.

A revoked placeholder cannot reach a tool during the running process. Veyyon remembers the exact name it retired and rejects the call before execution:

Stored secret #STRIPE_TEST_KEY# is no longer available. Store the credential again and update the command.

Text that was never a live credential, such as #TODO#, remains ordinary input. The revocation notice gives the agent the same fact before it tries the call; the refusal is the backstop when the agent keeps using stale history.

For the same reason, the removal notice is delivered even when secret protection is off. The add and extend notices are not: with protection off there is no working placeholder to advertise. A revoked one is different, because it is already sitting in the agent’s history, and the agent needs to hear that it stopped working whatever the setting is.

Turning secret protection off also marks every name advertised in the running process as retired for tool execution. Redaction keeps using the same readable placeholders in provider-bound text, but a stale tool call cannot spend or send them after expansion has been disabled.

The vault: storing a credential with /secret

Environment detection covers credentials that are already in your shell. For anything else, hand it to the vault. A vault entry is encrypted on disk, has a name, and expires.

Storing a credential

In a terminal, everything you type after /secret add is the credential. There is no name to invent first:

/secret add ghp_R2d2c3poIHRva2VuIGV4YW1wbGU

Veyyon takes the value off the line and prompts for what to call it, in a field that shows what you type, because a label is not a secret:

Name this secret (optional). The model spends it by writing #NAME#. Leave empty to have one generated.
>
  enter submit  esc cancel

Press Enter on the empty field and veyyon generates a name, SECRET_1 and upwards. Type one and it is cleaned up and uppercased for you, so github token becomes GITHUB_TOKEN. Press escape and nothing is stored at all:

Cancelled. Nothing was stored.

That order is deliberate. The credential is what you came to store, so nothing stands between you and storing it, and the name is prompted afterwards where you are free to skip it.

Pasting into a hidden field

/secret add with nothing after it opens a field that shows nothing as you type:

/secret add

Paste the secret value here. You can name it afterwards.
> ••••••••••••••••••••
  the value, not a name · hidden as you type, stored encrypted  ·  enter submit  esc cancel

Your composer is cleared before the field opens, so the value never enters the input buffer and never reaches your scrollback. Press escape and nothing is stored. Submit an empty field and nothing is stored either, and veyyon reports it rather than storing an empty credential. The name field follows, the same one as above.

Reading it out of the environment

If the credential is already an environment variable, read it from there and type nothing:

/secret from-env GITHUB_PAT

This is the recommended form, because the value never enters the input buffer and never reaches your scrollback. from-env is a command of its own, alongside add, and its first word is the name of the variable. The name field follows here too, so a bare from-env GITHUB_PAT is the whole line you need.

You may write the name on the line instead, and a lifetime and a vault after it:

/secret from-env GITHUB_PAT DEPLOY_KEY 7d project

The variable comes first and the name second, both by position, which is what lets a secret be called PROFILE or NEVER. The lifetime and the vault come after in either order, because no word is both: a vault is one of profile, project and global, and a lifetime is 30m, 12h, 7d, 2w, never, or anything else beginning with a digit. env is the second spelling of from-env.

A value on the command line stays in your scrollback

The one-paste form is on screen until you clear the terminal. Veyyon reports it rather than leaving you to work it out:

The value was typed on screen, so it is in your scrollback. Use /secret from-env next time to avoid that.

Every exact /secret command shape, including malformed input, is excluded from persistent editor history. This prevents the command from being recovered with the Up key or written to history.db. It cannot erase terminal scrollback that was already rendered.

The line is kept byte for byte from its first non-space character to its last, so a passphrase may contain spaces and no part of the value is trimmed away. Use the hidden field or from-env when you would rather the value were never on screen at all.

A command comes first

The first word of a /secret line is a command or it is nothing. The commands are add, from-env, list, rm, clear, rename, value, scope, copy, extend, log, discard and help, plus the second spellings env, remove, delete, wipe, purge, empty, reset, name, replace, move, renew and audit.

A line that begins with anything else is rejected, and nothing is stored:

Unknown /secret command. Nothing was stored. If what followed /secret was a credential, it is now in
your scrollback and was never protected, so rotate it and store the new one with /secret add.

The refusal never repeats the word it rejected, because that word is often the credential itself.

Earlier versions read an unrecognised first word as the credential, so /secret ghp_... stored it. That saved one word and cost three mechanisms: every command had to be reserved in advance so it could not be mistaken for a value, a credential beginning with a reserved word collided with the command, and the collision needed an escape spelling of its own. With the value living behind add there is one place a value is read and none of that is needed. /secret add list of words that is really a passphrase stores that line byte for byte, first word included.

A command stays a command however much follows it, so a malformed one is rejected rather than quietly stored: /secret log 50 is a log with an unreadable argument, not a new secret called SECRET_1.

Every argument is a plain word

There are no options anywhere in /secret. Nothing is spelled with a dash, so there is nothing to look up and nothing to get in the wrong order. A word means something because of where it sits, or because it belongs to a set that cannot be anything else:

Position wins wherever the two could disagree, so a secret really called PROFILE is removed by /secret rm PROFILE and one called NEVER has its lifetime extended by /secret extend NEVER 7d. Where meaning is taken from a word’s shape instead, the sets provably cannot overlap: a secret name may not begin with a digit, so /secret log 50 is fifty records and /secret log GITHUB_TOKEN is one credential’s uses; and a name may not contain a hyphen, so the from-env in /secret value <name> from-env <VAR> is never a name.

The spellings --, --from-env, --ttl, --scope, --limit and --name were the earlier grammar and are rejected, stating the plain word that replaced each one. They are rejected only as the first word after add, so a credential that merely begins with dashes is still stored byte for byte:

/secret add -----BEGIN OPENSSH PRIVATE KEY-----

-- was the worst of them. A slash command has no options to end, so it meant nothing here and had to be looked up, and storing it on the front of a credential produces a secret that expands into requests failing somewhere else entirely.

What you are told when it is stored

Whichever form you used, veyyon confirms with the name it filed the credential under and the placeholder the model will write:

Stored GITHUB_TOKEN in the profile vault, 1d left.
The model sees #GITHUB_TOKEN# and never the value. Write that placeholder where the credential goes.

Storing over a name that already exists is called a replacement rather than a store. That write is how you rotate a credential, and it is also what a fumbled name does, so it is never reported as if nothing had been overwritten:

Replaced GITHUB_TOKEN in the profile vault, 1d left.
The previous value is gone. #GITHUB_TOKEN# now spends the credential you just stored.

The agent is told at once that a credential exists and that it should write #GITHUB_TOKEN# where the value belongs. It is never given the value and cannot request it. It also keeps knowing after this session ends, because the inventory in the system prompt is rebuilt from the vault rather than remembered from the conversation. See What the agent knows, and when.

Managing what you stored

Every verb below works in a terminal and on a client that has none. The value forms above are the only part of /secret that depends on where you are typing.

value is how you correct a credential. It keeps the name, the scope, the creation time and the expiry, so a token pasted with one character missing does not have to be revoked and stored again: storing it again mints a new name while every prompt in the session still spends the old placeholder, and it re-dates the entry, so a secret with two days left would come back with the default lifetime. The field it opens is hidden as you type, and /secret value <name> from-env <VAR> reads the replacement out of the environment instead.

copy copies the placeholder and only the placeholder. #GITHUB_TOKEN# is the thing you paste into a prompt; copying the value would be the disclosure you stored the credential to avoid.

clear empties one vault. It requires the scope because there is no default: the vault is three files, project overriding profile overriding global, and the copy you can reach is the one that gets spent, so a guess would empty whichever happened to be in front and leave the other two full. It reports the placeholders it dropped. A name that a wider vault still holds is reported as removed but not as revoked, because #NAME# goes on expanding to that copy. wipe, purge, empty and reset are the same command.

clear everywhere empties all three. It reports every scope in one report, including a scope that held nothing, because the question it answers is whether anything is still stored. all, everything and every are the same word. No other verb takes it: “all of them” is not a place to store a secret, not a destination to move one to, and not a vault file to set aside.

scope rejects a move onto a name the destination vault already holds, rather than overwriting it. It moves the time REMAINING rather than the original lifetime, so moving a secret cannot lengthen its life. The copy is written to the destination before the source is removed, so an interrupted move leaves two copies you can see rather than none.

No verb prints a value: not on a row, not truncated onto one, not behind a key. A value put into the vault has stopped being visible, and the surface most likely to end up in a screenshot is the one that must not break that.

Every change reloads the live secret runtime, so a credential you revoke stops being spendable in the session you are sitting in rather than at the next restart. A reload that fails is reported rather than swallowed, because the vault write is already durable and you are the only one who can decide what to do about the gap.

Names are never completed. The dropdown after /secret offers verbs and nothing else. Completing a stored name would put part of your vault on screen on a keystroke, and accepting one would type a name onto a line whose first word decides between a command and a credential. /secret list is where names are read.

Finding what is masked and not stored

/secret list ends with what the session is masking that no name can reach. This is the counterpart to the composer’s N masked chip: both read one counter, so the number below the table and the number above the prompt are the same number.

  2 values masked in what is sent, detected rather than declared.
  The agent cannot spend them: only a stored secret has a placeholder.
  From: /home/dev/project/.veyyon/secrets.yml, DEPLOY_TOKEN.
  To stop masking one, unset the variable or narrow the keywords in env-keywords.yml.

Each of these values reached the session through the environment or through secrets.yml, so it has no name and no placeholder the agent can write. What it has is a place it came from: the variable name, or the path of the file that declared it. That label is not a name. It makes the value findable and grants no #NAME# expansion.

One credential exported into the environment and also declared in a file is one masked value with two places to look, and both are named. A value handed in by an SDK caller with no label at all is counted, and the count of those is stated rather than left as the difference between two numbers.

On a client with no terminal

--print mode and an ACP editor have no field that can hide what you type, so they cannot accept a credential you type at all. Every command is the same there, and from-env is the way in:

/secret from-env GITHUB_PAT GITHUB_TOKEN

The name is required on the line here, because nothing on that surface can prompt for it afterwards. add is still listed, with the reason it does not work and the command that does, rather than being hidden and answering only with an error:

/secret from-env <VAR> <name>         store the value of an environment variable
/secret add                           not here: a client cannot hide typing, so use from-env

An inline value is rejected, because that surface keeps its requests in a history you cannot clear:

This client rejects an inline credential, because the line containing it is retained in the client's own
request history. Nothing was stored. Read the value out of the environment instead:
/secret from-env MY_TOKEN <name>.

The refusal repeats neither word after add. Nothing distinguishes a name followed by a credential from a credential whose first word looks like a name, so a message that quoted the part it took for the name would sooner or later quote the credential.

list prints a table:

2 active secrets. The agent spends one by writing its placeholder; the value is never shown.
  PLACEHOLDER         SCOPE    EXPIRES  STATUS
  #GITHUB_TOKEN#      profile  6d left
  #PROD_DB_PASSWORD#  project  1d left  expires soon
Extend one before it lapses: /secret extend <name> 7d.

No part of any value appears there. A prefix of a credential is still a disclosure, and one on screen is one in a screenshot.

The STATUS column and the closing line appear only when at least one entry has crossed a warning threshold, so a table of healthy entries is one column narrower. A cell reads past halfway or expires soon, and those are the same two thresholds that raise the warnings described under Lifetimes. The table and the warnings cannot disagree about which entry is in trouble.

With nothing stored, list reports it and shows the one entry form that surface has, rather than printing an empty table.

Removing and extending each notify the agent of what changed, whichever surface you did it from, so a placeholder you revoked stops being used instead of arriving at a command as literal text. See What the agent knows, and when.

When a vault file cannot be read

Sometimes a vault file survives on disk and stops being readable: a disk filled up mid-write, a backup tool restored half of it, a sync client merged two copies. Veyyon reports which scope, what it means, and what to run:

Your profile vault at /home/you/.veyyon/profiles/work/agent/vault.json exists but could not be
read, so it was skipped and the secrets stored in it are unavailable for the rest of this session:
their placeholders will NOT expand. Every OTHER scope loaded normally, and masking of known secret
values is unaffected. The vault is encrypted, so a hand edit cannot repair it: run /secret discard
profile to move the unreadable file aside. Then store the secrets it held again. The reason it
could not be read was <what the parser complained about>

A vault can also fail in a way Veyyon cannot step around, where nothing in it can be read: the key is gone, the key is not the one the vault was sealed with, or the file is truncated. The session still starts, and reports it:

Your vault could not be read, so this session started WITHOUT it: nothing you have stored is
available, and every #NAME# placeholder it held will be rejected rather than sent as literal text.
Masking of secrets from your environment and secrets.yml is unaffected and still running.
Affected: project (/home/you/work/repo/.veyyon/vault.json). Run /secret discard project to move
the unreadable file aside. Then store the secrets it held again. The reason it could not be read
was <what the parser complained about>

Both notices name one command, because a notice raised by the vault loader cannot determine which client is about to print it, and discard runs on all of them. It moves the file aside rather than deleting it: the bytes still hold a real credential under a live key, and a repair that destroyed them would be worse than the fault it was fixing.

Read the second sentence of the second notice carefully, because it is the part that keeps a broken vault from becoming a leak. A scope Veyyon could not read is treated as unreadable, never as empty. #NAME# in a prompt is rejected rather than passed through as the literal text #NAME#, and Veyyon will not act as though you had stored nothing.

The session starts because the repair is a command inside it. If a vault that would not open also stopped Veyyon from launching, the only way out would be deleting the file by hand, which is the one thing an encrypted store exists to stop you doing casually.

Either route runs the same repair, and prints the same result:

Moved the unreadable profile vault to
/home/you/.veyyon/profiles/work/agent/vault.json.unreadable-1753660800000-8e3a8d58, so that scope
works again. The file still holds your sealed entries, so re-add the secrets it held rather than
assuming they are gone.

The scope keeps working from there. You can store secrets in it again immediately, and the other two scopes were never affected: only the file you named moved.

Your file is moved, not deleted. The name it moved to is in the message because that file is the only route back to what it held. It is still encrypted with a key that is still on disk, so if the damage is a truncated tail, the entries before the damage are still in there. Veyyon will not destroy a credential store to make itself usable again, so the cleanup is yours to do once you are sure you no longer need it.

You have to name the vault. Every other command that takes one defaults to profile, because there it chooses where to put something and /secret list shows you the result. Here it chooses a file to move aside, so a default would let a bare /secret discard move a working vault out from under the session you are sitting in. A bare invocation is rejected and states the word to add.

Two things the repair refuses, both on purpose:

• A scope that reads normally. This is not a second way to delete secrets. Revoke the entry instead with /secret rm <name>, which reports what it removed. The check happens at the moment you run the repair rather than from the earlier warning, so a file that was fixed in between is left alone.
• A scope that shares its file with another scope. If your profile directory is your config root, the profile and global vaults are one file, and moving it aside as one would take the other with it. The refusal states the other scope so you can decide which you meant.

The repair is reachable from every client, not only the terminal, because a broken vault is most likely to turn up in a headless run.

Lifetimes

Every entry expires. The default is one day, which you can change in /settings under Secret Lifetime.

That setting is the whole answer for /secret add, because the line after add is the credential and there is no room on it for anything else. To give such an entry a different lifetime, store it, then run /secret extend <name> 30m. The lifetime you name there is measured from now, not from when the credential was stored.

from-env takes one on the line, after the variable and the name:

/secret from-env DEPLOY_KEY DEPLOY_TOKEN 30m
/secret from-env SIGNING_KEY SIGNING_TOKEN never project

Lifetimes are written the same way everywhere: 30m, 12h, 7d, 2w, or never. Weeks are accepted and reported back in days. A lifetime and a vault may be given in either order, because no word is both.

You are warned before a lifetime runs out, once at the halfway point and again near the end:

Warning: secrets: #DEPLOY_KEY# expires soon, 2h left. Extend it with
/secret extend DEPLOY_KEY 7d, or it will be deleted.

The remedy is one command, and it runs wherever the warning is read: a notice raised while the vault is loading cannot determine which client is about to print it.

The thresholds are fractions of the lifetime rather than fixed times, so one rule fits every entry. A one-day secret is mentioned after twelve hours; a ninety-day secret is mentioned on day forty-five, not on day eighty-nine. Each warning states the command that prevents expansion from being revoked.

Expiry revokes substitution immediately. If an expired secret merely stopped being obfuscated, its value could flow to the model provider when protection lapsed. Veyyon instead removes the in-memory expansion mapping and keeps a forward-only redaction tombstone.

The deadline is enforced when the credential is used, not only when a session starts. A session left open over a weekend stops substituting a one-day secret on the day it expires and reports both the runtime and persisted state:

Warning: secrets: #GITHUB_TOKEN# has expired and its in-memory expansion has been
revoked. Its encrypted value has not yet been deleted from the vault; a successful
vault refresh will prune it. Store it again with /secret from-env <VAR> if you still
need it, or /secret from-env <VAR> GITHUB_TOKEN in a client with no terminal.

In a terminal the name field that follows is where you type GITHUB_TOKEN to get the same placeholder back.

The hot-path expiry check does not write to the vault. The encrypted entry remains on disk until the next successful vault refresh prunes it. It remains encrypted and cannot be expanded after the deadline.

If a command still refers to an expired secret, Veyyon rejects it before the tool starts and reports only the retired placeholder. It does not send an empty header or the literal placeholder to a remote service. Old transcript text containing the raw value remains covered by the forward-only redaction tombstone for the life of the same working-directory runtime.

Scope

An entry belongs to one scope and is invisible from the others:

A credential you store in a terminal goes to the profile vault. Scope is an option, the argument line there is the credential, so there is no place on it to put one. Profile is the default because that is usually the boundary you want: a credential you use for one kind of work should not be reachable from a session you opened in another profile.

A credential already stored can be moved with /secret scope <name> project. To file one somewhere else as you store it, name the scope on a client that takes a verb and a value on one line:

/secret from-env SCAN_TOKEN SCAN_TOKEN project

When the same name exists in more than one scope, /secret list reports it. The table stays one row per name, because one row per name is what the agent can spend, and a sentence underneath states the copies it is not spending:

2 active secrets. The agent spends one by writing its placeholder; the value is never shown.
  PLACEHOLDER     SCOPE    EXPIRES
  #SHARED_TOKEN#  project  24h left
  #SOLO_TOKEN#    profile  24h left
  #SHARED_TOKEN# is also stored in the global vault, shadowed by the project one. Only the project
  copy is spent. Remove it with /secret rm SHARED_TOKEN global.

That copy is inert, not gone. It is still on disk, still decryptable, and it becomes the live one the moment the copy in front of it is removed. Before the list mentioned it, the only way to find out was to remove the copy in effect and read what the removal told you, which is late: you learn about a credential at the moment it starts being spent.

The narrowest copy is the one that wins, and a removal that specifies no vault takes it. Removing that copy uncovers the next one out, and the command reports that too:

/secret rm shared-token

Removed SHARED_TOKEN from the project vault. A profile secret of the same name was underneath it,
so #SHARED_TOKEN# still spends a credential, now that one. Run /secret rm SHARED_TOKEN profile to
remove that one too.

That second sentence is the part that matters, because the placeholder keeps working. Without it you would read a removal, assume the name was dead, and leave a live credential reachable under a name you believe you revoked. The agent is told the same thing, so it does not treat the name as revoked either.

To take a particular copy rather than the one in effect, name its scope:

/secret rm SHARED_TOKEN profile

Naming the scope of a copy that is already shadowed removes it without changing what the placeholder spends, and the command reports that rather than implying something changed.

A vault word belongs to from-env, rm, clear, scope and discard. On a command that does not read one it is a word that fits no slot, and it is rejected rather than ignored:

/secret extend GITHUB_TOKEN global

/secret extend cannot read the word in position 2, and a word that would be ignored is rejected
rather than dropped silently.

That refusal exists because the alternative is worse than an error. An accepted-and-ignored vault word on extend reads as “the global copy was given a fresh lifetime” when what actually happened is that the copy in effect was re-dated and the others were left alone. The same rule covers a lifetime handed to rm and a number handed to list: a word veyyon would drop is a word you meant something by.

The refusal states the position and never repeats the word, because the realistic slip is muscle memory for add under a different command, which puts the credential itself in that position.

Encryption, and what it does not do

Vault files use AES-256-GCM. Each write uses a fresh 12 byte nonce and the full 16 byte authentication tag. The key is a 32 byte file at ~/.veyyon/vault.key, created on first use. It never lives inside a project directory.

On POSIX, the key is mode 0600. Its directory must be owned by you and not writable by another user. On Windows, Veyyon applies and verifies a protected owner-only ACL. Existing vault files receive the same platform permission checks before they are read.

A project-scoped vault lives inside the repository you are working in, so Veyyon keeps it out of your commits. The first time it stores a project secret, it writes .veyyon/.gitignore covering vault.json and the vault.json.unreadable-* file that a discarded vault is renamed to. If that file already exists, Veyyon adds the two rules and leaves your own lines alone. Only the vault is ignored, so anything else you keep in .veyyon/, such as prompt templates, stays trackable. Commit the generated .veyyon/.gitignore along with the rest of your project.

Committing a vault would not expose the credentials directly, because the ciphertext is unusable without the machine key. It would still put a credential store in your history, and nobody who clones the repository can open it, including you on another machine. A vault is not a portable backup. The authenticated location includes the semantic scope, canonical path, and physical scope-directory identity. If you move or recreate that directory, store those entries again.

Updates use a synchronized owner-only temporary file. Kernel no-replace and exchange operations publish the synced inode without overwriting a destination that appeared after the last check. Veyyon holds the scope directory open during the transaction, so replacing the lexical parent cannot redirect the read or write.

Veyyon rejects symlinks, hard-linked files, directories, devices, insecure permissions, and paths whose resolved parent crosses the requested scope. It also rejects ciphertext copied to a different scope or physical directory.

The sealed descriptor is limited to 8 MiB before it is read into memory. Writes enforce a separate 6,291,402-byte encoded plaintext limit before serialization, encryption, or Base64 expansion. A legacy version 1 envelope is rejected because it is not bound to its scope and path. Store those entries again so they use the current authenticated format.

These failures are deliberately loud:

• A vault file present with no readable key stops the session. It is never treated as empty.
• A vault whose nonce, ciphertext, authentication tag, or bound location changed is rejected.
• An unsafe directory, symlink, non-regular path, hard link, or insecure permission is rejected with the path and fix.

What this encryption does not protect against is someone who is already running as you. The key is readable by your own account by design. If you need to defend against a compromised account, use a hardware token or an external secret manager.

Seeing which credential was used where

Hiding a value from the provider bounds what the agent could see. It does not show what the agent did with what it could. The expansion log answers that, and /secret log prints it:

3 most recent use(s), oldest first:
  12m ago  bash  #GITHUB_TOKEN#
    {"command":"curl -H 'Authorization: Bearer #GITHUB_TOKEN#' https://api.github.com/user"}
  4m ago  bash  #DEPLOY_KEY#
    {"command":"scp -i #DEPLOY_KEY# build.tar deploy@host:/srv"}
  just now  bash  #GITHUB_TOKEN# #DEPLOY_KEY#
    {"command":"./release.sh --token #GITHUB_TOKEN# --key #DEPLOY_KEY#"}

One use is when it happened, which tool received it, which placeholders were substituted, and the command as the model wrote it. The last twenty are shown; /secret log 50 requests more.

Narrowing it to one credential

A name answers the question worth asking just before a revoke, which is what stops working:

/secret log GITHUB_TOKEN

Uses of #GITHUB_TOKEN#:
2 most recent use(s), oldest first:
  12m ago  bash  #GITHUB_TOKEN#
    {"command":"curl -H 'Authorization: Bearer #GITHUB_TOKEN#' https://api.github.com/user"}
  just now  bash  #GITHUB_TOKEN# #DEPLOY_KEY#
    {"command":"./release.sh --token #GITHUB_TOKEN# --key #DEPLOY_KEY#"}

The whole log is read, then narrowed to that credential, and only then cut to the limit. So /secret log GITHUB_TOKEN 20 means the last twenty uses OF that credential, not the last twenty records of which some happened to be it. The two words are told apart by shape rather than by position, and may be given in either order: a limit is a whole number and a secret name may never begin with a digit, so no word is both. The heading states the credential even when nothing follows it, because an empty log for one secret and an empty log altogether support opposite conclusions: the first states this credential has never been spent, the second that nothing has.

An empty log, and a log that is off

An empty log prints the file it is empty at, so it reads as “nothing has happened here” rather than “something failed to load”:

No secret has been used yet. The log is ~/.veyyon/profiles/work/secret-audit.jsonl.

A log that is switched off prints the setting instead:

Secret use is not being recorded, so there is no log to show. Turn on "Record Secret Use" in
/settings (secrets.auditLog) to start recording.

Nothing recorded and nothing being recorded support opposite conclusions about whether a credential was spent, and as an empty list they are the same picture.

The log belongs to the profile rather than to one session, so two veyyon windows in the same profile append to the same file. When the records you are shown come from more than one, the output reports it:

These records come from 2 sessions sharing this profile's log.

Without that line the rows read as one session’s history, and you would count uses another window made.

The recorded command holds the placeholder, not the value, and that is a property of how the record is built rather than a promise about care taken. Veyyon writes the arguments as they were before substitution, which is the form in which every secret is still a placeholder, so there is no redaction step that could be got wrong and no way for a value to reach the file.

Placeholder discovery follows the same recursive string and object-key walk as command expansion. The reader escapes terminal control characters in records, paths, and notices before display. Hard-linked log files are rejected, and generation reads check the 2 MiB bound before allocating a buffer.

Recording is on by default and writes to secret-audit.jsonl in your active profile’s directory. Turn it off under Record Secret Use in /settings:

secrets:
  auditLog: false

The file is mode 0600 and lives in the profile rather than the project. If veyyon cannot append to it, it reports it and the command still runs. The value is still protected either way.

At two megabytes, roughly ten thousand uses, the log is atomically moved to secret-audit.jsonl.1 and a fresh one is started. A cross-process lock covers the size check, rotation, append, and read snapshot, so two sessions cannot overwrite a generation or exceed the record cap at the boundary. Oversized rows bound every field and report how many placeholder references were omitted. Both generations are read, so a report requested right after a rotation still fills up.

Declaring secrets yourself

Environment variable detection covers the common case. For anything else, list entries in a secrets.yml file. Two locations are read:

Both levels are read and merged. A project entry with the same content as a profile entry replaces it, so a repository can override a declaration without duplicating the rest of the file.

A minimal file protects one literal value:

- type: plain
  content: sk-proj-abc123def456

A regex entry protects anything matching a pattern, which is how you cover credentials you have not seen yet:

- type: regex
  content: "AKIA[0-9A-Z]{16}"

Patterns always scan globally. You do not need the g flag.

Veyyon rejects regexes that can make no progress, use sticky matching, or contain conservatively detected catastrophic-backtracking forms. Replacement changes only the exact matched span. Equal text outside the regex context is left alone.

The two modes

Each entry chooses what happens to the value.

obfuscate, the default, is reversible. The value becomes a placeholder on the way out and the placeholder becomes the value again on the way back in. Use it when the agent needs to work with the credential.

replace is one way. The value is swapped for a fixed or generated string and nothing restores it. Use it when the agent has no business using the credential at all and you only want it out of the context:

- type: plain
  content: hunter2
  mode: replace
  replacement: "********"

A generated replacement is derived with the machine placeholder key, so it does not expose a cross-machine dictionary oracle. A custom replacement cannot look like a named or machine-keyed placeholder. That restriction prevents one-way text from becoming a request to expand a live credential.

The 8-character minimum

obfuscate mode replaces every occurrence of the value. A three-character secret would blank out fragments of unrelated words, so short values are not obfuscated.

Veyyon rejects them rather than ignoring them. A plain obfuscate entry under 8 characters stops startup with an error stating the entry and the fix. This is deliberate: a session that starts cleanly while sending your declared secret to the provider in plain text is worse than a session that will not start.

The fix is mode: replace, which is one way and has no minimum.

The same floor applies to a credential you store in the vault, and the field that takes the value applies it there. Type something shorter than 8 characters into the hidden field and it is rejected as you leave it, while the value is still in front of you, rather than after you have also named the secret.

A regex match under the floor behaves differently. A short match usually means the pattern reached into ordinary prose, so the match is skipped and the over-matching pattern is reported once. If short matches really are secret, declare it on the entry:

- type: regex
  content: "\\b[0-9]{6}\\b"
  minLength: 6

A malformed or unreadable secrets.yml also stops startup, and so does a single entry inside it that is not a valid declaration. A mistyped type:, a missing content:, or minLength on a plain entry each name the entry number and the fix:

Refusing to start: 2 entries in /home/you/.veyyon/secrets.yml are not valid secret
declarations, and skipping them would leave the values they declare unprotected.
  - entry 0 has type "plaintext", which must be "plain" (an exact value) or "regex" (a pattern).
  - entry 3 sets minLength, which applies to regex entries only. A short plain secret needs
    "mode: replace", which is one-way and has no minimum.

Every problem in the file is listed at once, so you fix them in one pass rather than finding the next one on each restart. A missing file does not stop startup, because nothing was declared.

Unknown fields are errors too. A misspelled replacement, a plain-only field on a regex entry, duplicate flags, or an option that conflicts with the entry type cannot be silently ignored.

When something cannot be protected

Two kinds of problem can arise, and veyyon treats them differently on purpose.

A problem that would mean a credential reaches the provider stops the session. A declared obfuscate entry under the minimum, a vault file whose key is missing, a secrets.yml that cannot be parsed: each of these is a refusal with the entry and the fix named. A session that starts cleanly while sending your secret out in plain text is worse than one that will not start.

A problem that leaves protection intact but degrades something appears in your session as a warning, prefixed with the subsystem that raised it:

Warning: secrets: pattern matched a 3-character value, under this entry's 8-character floor.
Set "minLength" on the entry if short matches are real secrets, or tighten the pattern.

An over-matching pattern is the usual example. It is discovered while obfuscating a message rather than at startup, so it cannot be a refusal, and it is worth seeing because you cannot otherwise tell a working pattern from one that is quietly reaching into prose.

In --print mode and other non-interactive clients the same warnings go to stderr, so a scripted run does not lose them.

Nothing important goes only to the log file. That was the previous behaviour and it amounted to silence: the log has no console output by default, and nobody opens it.

Where the value goes

The provider boundary is applied again whenever a local transcript is sent. Resuming a session can restore placeholders for display without giving the resumed raw text a path back to the provider.

Changing the working directory is transactional. Veyyon loads the destination runtime before committing the move, and restores both the old directory and old runtime if loading fails. A resumed session or persisted subagent starts from its recorded directory before loading project-scoped secrets.

What this does not protect

Be clear about the boundary.

The two stores differ on disk. Vault entries added with /secret are encrypted. secrets.yml is a plain file: it holds declarations you wrote, in the clear, and anyone who can read it has those credentials. If a value needs to be encrypted at rest, put it in the vault rather than in secrets.yml.

A command the agent runs receives the real value. So a command that prints the credential prints it for real. Its output is obfuscated again before it goes back to the model, but it reached the process, and anything that process wrote elsewhere is outside veyyon’s reach. That output is also saved to the session file as it was printed, so a command that echoes a credential puts it there. The arguments veyyon itself records are redacted, but it cannot redact what a command chose to print.

Protection begins when the value is known. Once you enable protection or store a value, old local transcript text containing that value is sanitized on subsequent provider requests. The local transcript is not rewritten in place.

A value you type on the command line is visible on screen. /secret add <value> puts the credential in your scrollback, and the confirmation reports it. It is excluded from persistent editor history, but the obfuscator cannot scrub a terminal after the fact. Use /secret add on its own, which opens a field that hides what you type, or /secret from-env <VAR>, which types nothing at all.

The secret-use log records use, not intent. It records which credential went into which command. It cannot show what the command did with it once the process had it.

Reference

The field-by-field schema, the merge rules between the two files, and the interaction with environment detection are in docs/handbook/src/architecture/secrets.md.

For provider credentials specifically, veyyon keeps OAuth tokens and API keys in its own credential store rather than in your context. See Signing in.

Models and providers

You choose an endpoint and a model id. Veyyon then calls that provider’s API directly with your credentials. The endpoint can be a local server, a hosted API, or any OpenAI-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

API keys (BYOK)

BYOK means bring your own key. For a provider you configure yourself, Veyyon sends your key straight to that provider’s endpoint. There is no hosted proxy in between.

Set the key one of three ways:

• 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 (an env-var name, or literal:<text>).

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

Minimal BYOK shape

# ~/.veyyon/profiles/default/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 a bundled static catalog, merged with live discovery for providers that expose a /models endpoint. Failed discovery returns an error; it does not invent an empty catalog.

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. /model shows the current interactive model; /session info shows session stats. veyyon plugin doctor checks plugin installation health.

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

Model selection

# ~/.veyyon/profiles/default/agent/config.yml
modelRoles:
  default: openai/gpt-5          # interactive (persisted default)
  smol: openai/gpt-4.1-mini
  slow: anthropic/claude-opus-4-5:high
  plan: anthropic/claude-sonnet-5
subagent:
  model: deepseek/deepseek-chat:high
  agents:
    reviewer:
      enabled: true
      thinkingLevel: auto
compaction:
  model: openai/gpt-5-mini

Ctrl+P (default binding) cycles roles listed in cycleOrder (schema default smol, slow, not default). Full role list and aliases: Models, roles, and profiles.

Per-model harness settings

Prompt order, repair enablement, and tool exposure can be set per model id through harness profiles and model roles. See Execution-order prompts and Model contract.

Harness profiles

Optional overrides in config.yml or ~/.veyyon/profiles/default/agent/harness-profiles.yml. The two files take different shapes: config.yml nests under harness: (the harness.profiles setting), while harness-profiles.yml reads a top-level profiles: map (a top-level harness: key there is silently dropped).

# config.yml
harness:
  profiles:
    "openai/gpt-4.1":
      repair: true
      tools: ["read", "edit", "search", "bash", "write"]
      promptSectionOrder: ["tool-policy", "delivery-contract"]

# harness-profiles.yml
profiles:
  "openai/gpt-4.1":
    repair: true
    tools: ["read", "edit", "search", "bash", "write"]
    promptSectionOrder: ["tool-policy", "delivery-contract"]

Keys: exact provider/model-id or provider/*. See Per-model repair posture.

Switching providers

Set credentials for the new provider and select a model id from that catalog. Tool surface and tools.approvalMode are independent of provider id.

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

Model selection notes

Pin models in CI and shared profiles (--model, modelRoles). Floating “latest” aliases change under you.

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 "…".

Veyyon resumes from the launch picker or /resume, and branches with /branch / /fork.

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/profiles/default/agent/sessions/**/<timestamp>_<id>.jsonl) is an append-oriented log whose entries form a tree. Recorded session entries carry an id and a parentId. Branching appends a new entry whose parentId states an earlier entry, so it starts a sibling branch from that point.

The active leaf advances to each appended entry. On load it falls back to the last entry in the file. Not every line carries parentId: the first-line session header does not, and in-place refresh records are full replacements of the original logical record rather than tree entries. Storage maintenance may atomically rewrite the file to update the header or representation, but it preserves the history entries. Branches you navigate away from remain addressable.

Four properties are guaranteed by the storage layer:

• No history deletion during navigation. Branching appends new entries; abandoned entries remain addressable.
• A corrupt header never initializes over existing bytes. A non-empty file without a valid first session record is rejected. Veyyon leaves it byte-for-byte unchanged so you can inspect or repair it.
• Recoverable record loss is operator-visible. A malformed later record is skipped so one damaged line does not make the entire session unopenable. The session shows one bounded warning with the file, one-based line and byte offset, and shape problem. It never quotes the dropped record’s content. Duplicate ids are last-write-win, and broken parent chains appear as extra roots.
• Moves are transactional. Moving a session changes the transcript, its artifacts, and its recorded working directory as one operation through the active storage backend. If relocation or the final header write fails, Veyyon restores the old paths and in-memory working directory.

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 recalls the original prompt into the composer so you can edit and resubmit it. 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. 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. The launch session picker instead copies only the picked session’s ancestor path (the active lineage) into the new file.
• /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 renders the current session as a self-contained HTML file you keep, for backup, inspection, or sharing.

• /export: write to the session’s working directory under a generated file name.
• /export <path>: write to <path>.

The command prints the destination and opens the result in your browser. It never modifies the live session.

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

Cleaning up old sessions

veyyon gc reclaims disk: it sweeps blobs no session references any more, archives cold sessions, and checkpoints the database write-ahead logs. It is a dry run unless you pass --apply, and it prints what it would do either way.

GC never touches a file that was written recently, because a running veyyon may still be appending to it. That window is five minutes by default, and you can change it:

# ~/.veyyon/profiles/default/agent/config.yml
gc:
   writeGraceMinutes: 15

Pass --write-grace-minutes to override it for one run. The minimum is one minute: a shorter window would let GC delete a blob a live session wrote a moment ago, so a smaller value is raised to the minimum and the run reports it.

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 (Ctrl+Q, or Ctrl+Enter where the terminal delivers it). The message is queued in the running process and starts a new turn once the current one finishes. The queue lives in memory for the lifetime of the process; it is not written to the session file, so it does not survive a restart. Slash commands and ! shell escapes queue client-side instead; they are local actions, not model input.

Queued messages render under the composer grouped as Steering·N and After yield·N, with the dequeue key shown as a hint. 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 dequeue chord (Alt+Up by default, remappable): 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/profiles/default/agent/config.yml
steeringMode: all
followUpMode: all

Programmatic clients use the follow_up RPC command to queue a follow-up on an active session. Recalling a queued follow-up is a TUI-local action (Esc or the dequeue chord); the RPC protocol has no recall command. An empty follow-up is a no-op in the TUI, and /queue with no text shows a usage warning.

Next

Read Examples for concrete prompts and workflows.

Subagents

A subagent is a second veyyon session that your session starts, hands one piece of work to, and collects a report from. The parent spawns it with the task tool; the subagent has its own context window, so bulk reading and long grinding work stay out of the conversation you are having.

Everything about them is configured in one place: the Subagents tab in /settings, backed by the subagent.* settings. /agents is the live picture of a run in progress: which agents are working right now and what they are saying to each other. It does not configure anything.

What you get out of the box

One agent type, the general-purpose worker, and delegation that the prompt requests:

subagent:
  delegation: preferred   # the default; the prompt requests that substantial work be delegated

Each subagent runs the model and effort set on its own page in the roster. An agent that names neither runs the profile’s default model at medium effort. Changing the model you are talking to moves that session and nothing else.

Veyyon also ships five specialists (scout, reviewer, designer, librarian, sonic), and they are disabled by default. During first-run setup, the Choose subagents step shows every available role with only task checked. Enable the specialists you want the model to start on its own. Each enabled type adds its description to future requests, so leave roles off when you do not use them.

How hard to push

subagent.delegation sets how hard this session is pushed to delegate:

The strength applies only when an enabled role matches the work. If task is enabled, it acts as the general-purpose fallback. If only specialists are enabled, work that matches none of their descriptions stays in the main session. With no enabled agent, the delegation preamble is omitted.

The separate subagent.enabled boolean (default on) is the kill switch: off removes the task tool and every delegation instruction from the prompt, so nothing can be spawned. A legacy delegation: off migrates to subagent.enabled: false.

The instructions follow the exact roles you enable. With only task offered, the prompt uses it as the general-purpose route. Enabling designer or reviewer adds those separate roles without changing what task means.

What counts as delegable work

subagent.delegation sets how strongly the model is pushed to delegate. The description of each enabled agent scopes the work that role covers. These are separate settings.

Veyyon preserves concrete roles. It does not infer a second role category from the tools an agent can call. For example, designer remains a designer and reviewer remains a reviewer. The model chooses the closest matching specialist for each independent slice:

# ~/.veyyon/subagents/accessibility-reviewer.md frontmatter
name: accessibility-reviewer
description: Reviews terminal interfaces for accessibility problems and reports findings
tools: read, search

Enable that role when you want it available:

$ veyyon config set subagent.agents.accessibility-reviewer.enabled true

When task is enabled, the model can use it for substantial work that does not fit a specialist. When task is disabled, the model keeps unmatched work inline. This prevents a specialist name from becoming a generic worker merely because no closer role is available.

An agent role is routing guidance, not a security boundary. Use the sandbox when you need to restrict filesystem or process access.

Choosing agents

subagent.agents holds one row per agent name. You choose initial permissions in the first-run Choose subagents step, then edit them through /settings → Subagents → Roster. The roster lists every discovered agent with its state, resolved model, and deciding setting. Enter opens one agent to set its state, model, and effort, or reset it to defaults.

To add an agent, put a markdown definition in ~/.veyyon/subagents/, or start from the shipped definitions by running veyyon agents unpack. The definition makes the role available. Enable its row before the model may start it. Writing a subagent covers the frontmatter fields, the system prompt and enabling the result.

That directory is read by every profile, and the file is the whole definition. Which profile may spawn the agent is a separate, per-profile answer: subagent.agents.<name>.enabled. Write the agent once, enable it where you want it.

A definition that lists a tool veyyon does not recognize is reported at startup rather than ignored. The tool grants nothing, and the guidance for it is left out of the agent’s system prompt, so a typo used to read as an agent that simply chose to do nothing.

A row has two states:

The built-in flows still work with the specialists disabled because a command can grant its agent for the turn: /review requests agent: "reviewer" through a per-turn grant, and so can you (“use the scout agent to map the parser”).

Writing an agent file makes the role available but does not grant spawn permission. Enable the role during setup or in the Agents settings table.

Choosing models

Two scopes choose a subagent’s model and effort, and Subagents → Same Model for All Agents selects which one is in force. They are exclusive, not layered: the rows of the scope that is off are not drawn.

Off, the default, each agent decides. Open Subagents → Roster, press Enter on an agent, and set the model and the effort on that agent’s own page. The first of these that names a model wins:

1. that agent’s lane, subagent.agents.<name>.model, and for a nested spawn the subagents level under it that governs that depth
2. the agent definition’s own model: frontmatter, for an agent you wrote
3. the profile’s default model role

subagent:
  agents:
    reviewer:
      enabled: true
      model: anthropic/claude-opus-4-5
      thinkingLevel: high

Effort resolves on the same three layers, ending at medium. An explicit :effort suffix on the resolved model pattern outranks all of them.

On, one pair decides for the whole roster, and the per-agent Model and Effort rows are hidden. Shared Model (subagent.model) and Shared Effort (subagent.thinkingLevel) sit under the switch; an unset chain runs every agent on the default model role:

subagent:
  sharedModel: true
  model: openai/gpt-5
  thinkingLevel: high

A lane keeps whatever it holds while the switch is on, and decides again the moment the switch goes off.

The default model role is the model the main assistant starts on, and it is the one keystroke path for the common case: /model writes it, and every agent with no model of its own follows it. A temporary pick, role cycling and plan mode move the live session model only, so an agent never changes model because of a keystroke aimed at the main assistant.

subagent.modelByDepth bound a chain to a spawn depth rather than to an agent and no longer applies. A config still holding it is reported once, naming the roster page that replaces it.

Fallback models

Every one of those places takes a list, not just one model:

subagent:
  agents:
    reviewer:
      model: anthropic/claude-opus-4-5,openai/gpt-5

The first entry is what that agent runs on. The rest are held in reserve: when a run errors on the model in use, that agent retries on the next entry rather than failing. The settings picker writes the value for you: open the model row, add a fallback, and press Enter on any entry to move it up the list.

A longer chain reads better as a list, and both spellings mean the same thing:

subagent:
  agents:
    reviewer:
      model:
        - anthropic/claude-opus-4-5
        - openai/gpt-5

Write it whichever way suits the file. compaction.model takes a chain the same two ways.

A chain only covers errors at run time. A model pattern that matches nothing is still a configuration mistake, so veyyon will not spawn the agent and states the setting, rather than quietly running it on the next entry: a typo must not silently downgrade the agent you spawn.

In the Subagents block above the composer, an agent that fell back is marked with ↓ before its model badge, so you can tell a deliberate model from a retried one at a glance.

Effort is chosen from a list: off, minimal through max, auto, or Inherit. Inherit on an agent’s own page means the default effort; on a nested page it means the page above it. auto requests that the provider choose. The same list appears in both places, so you cannot set a level that does not exist. If a hand-written config holds one that does not, veyyon reports the levels that work, rather than treating it as Inherit and leaving you with a setting that reads as configured and changes nothing.

A configured model that matches nothing available does not quietly fall through to the next layer. The spawn is rejected and the message states the setting to fix, because falling through is indistinguishable from your setting having no effect. Both agent surfaces show, for the selected agent, the pattern, the model it resolves to, and which of the three layers decided.

Watching a run

While a spawn is in flight, the Subagents block sits above the composer with one lane per agent. A lane reads left to right: a rail, the agent’s id, what it is doing, and the model it resolved to.

Subagents
 ▏ DockerSecretHarness    bash cargo test --workspace --all-targets         claude-opus-5 high
 ▏ SecretModeFlowUX       read modes/interactive-mode.ts                    claude-opus-5 high
 ▏ SecretModularityAudit  Audit secrets subsystem modularity, wiring, and…  claude-opus-5 med
 ▏ RateLimitedWorker      Retrying (2/5) in 38s · 429 rate limit exceeded   claude-opus-5 high

The id is painted in that agent’s own accent, the same hue the status line gives its name and the same one a delegated todo row uses to point back at it.

The middle column holds the most urgent fact the agent has. An agent asleep between provider attempts shows the recovery, its attempt count and the reason, counting down. An agent running a tool shows the tool and its argument. An agent waiting on the model has nothing to report, so it shows the work it was given instead, dimmed. Every lower rank is still true when a higher one is, and a lane that printed the description while the agent was asleep on a rate limit was byte-identical to one thinking.

Light travels down the rail while agents are working, and a lane is lit only while it has a tool in flight. The head crosses the whole block, so the cycle belongs to the block rather than the row, and arrives cold on a lane that is waiting or recovering. Where display.transitions is off, the block is still.

There is no elapsed clock and no context gauge. Total age ranks agents by seniority, which nothing acts on, and a parent decides nothing with a subagent’s remaining window. Whether a lane is stuck is answered by the recovery column. /agents carries the roster with the numbers.

A lane keeps its badge on its own row. Narrow the terminal and the model badge comes off first, then the columns shrink to what is left. Nothing wraps: the block draws no row it cannot fit, and draws nothing at all rather than overflow.

Eight lanes are drawn. Past that the block states how many more are running and points at /agents, which is the full roster. That row is the only place a count appears; the header is bare.

Limits and isolation

The remaining groups in the tab are operational: how many subagents run at once (subagent.maxConcurrency), how deeply they may nest (subagent.maxNestedSpawnDepth), per-run wall clock and request budgets, how long a finished subagent stays live before parking (subagent.idleTtlMs) and how long it stays listed after that (subagent.prune.*), and whether its edits land in an isolated copy of the tree first (subagent.isolation.*, see Safety).

Park and prune are two stages, and they do different things.

Park releases the live session, the process, its MCP clients and its memory. The roster row and the transcript stay, and messaging or opening the agent revives it. subagent.idleTtlMs (“Park After”) is the budget, five minutes by default for every model and provider. Set a positive millisecond value to override it, or 0 to keep idle agents live until exit.

Prune drops the roster row and with it the ability to wake the agent, so a long session does not accumulate every agent it ever spawned. It deletes nothing: the transcript stays readable at history://<name>.

Three settings in the Prune group control stage two. subagent.prune.enabled is on by default; turn it off to keep every parked subagent listed and revivable until you exit. subagent.prune.afterMs (“Prune After”) is how long a parked subagent keeps its row, counted from the moment it parked, and defaults to one hour. subagent.prune.waitingAfterMs (“Prune After While Waiting”) is the same budget for a subagent whose last message reported waiting on another agent, and defaults to two hours: it stopped on purpose to let a peer finish, so it is the agent you are most likely to message next. Set the two equal to treat both the same.

Turning pruning off does not turn parking off. Parking is what releases the session, and it happens either way; the prune switch only sets whether the parked row is eventually dropped. “Park After” sits in its own Park group for that reason, and the prune switch never hides it.

A subagent read back from a previous run is judged on the same budgets. Its age comes from when its transcript was last written, not from when this session found it, so resuming a session does not reset every old agent’s clock to zero.

When each budget starts counting

Both budgets count from the agent’s last transition, not from when it was spawned. An idle agent’s park budget starts when it went idle. A parked agent’s prune budget starts at the moment it parked. A revived agent starts its park budget again from the revival, so messaging a parked agent gives it a fresh five minutes rather than resuming a clock that was already half spent.

That is why a long-lived session does not prune everything at once: each agent’s deadline moves with its own activity.

Only idle and parked agents have a deadline

A running agent has no deadline at all, and neither does an aborted one. Nothing parks or prunes an agent that is mid-turn.

This matters when an agent looks stuck. A subagent waiting for you to answer an approval prompt is still mid-turn, so it stays running and no park or prune timer applies to it. If a finished agent is not being cleaned up, check its status first: the lifecycle only acts on idle and parked, so an agent stuck in running is a different problem and the prune settings will not affect it.

Turning it off

Set subagent.prune.afterMs to 0 and no parked agent is ever pruned. That also forces the waiting budget to 0, whatever subagent.prune.waitingAfterMs is.

That coupling is deliberate. If a zero parked budget still honoured a separate waiting budget, the only agents that were ever pruned would be the ones that stopped to wait on a peer, which are the agents you are most likely to message next. Zero means never prune, for both kinds.

If the session cannot be saved

Parking flushes the agent’s session to disk before releasing it. If that flush fails, the park is cancelled and the agent stays live with its timer re-armed. You keep a live agent rather than losing unsaved state, and the attempt repeats on the next expiry.

Nesting depth

subagent.maxNestedSpawnDepth is inclusive. The default is 0: the top-level session, at depth 0, may spawn direct subagents, but those children are leaves and cannot spawn more subagents. A value of 1 also lets direct children spawn, producing children at depth 2. Higher values extend the same rule, and -1 allows nesting without a depth limit.

An agent-specific value takes precedence over the blanket value:

subagent:
  maxNestedSpawnDepth: 0
  agents:
    reviewer:
      maxNestedSpawnDepth: 1

Here ordinary direct subagents remain leaves. A direct reviewer may spawn its own children because its effective limit is 1.

A subagent’s working directory is its own. If a subagent calls set_cwd, only that subagent moves: its tool paths resolve against the new directory and its system prompt is rebuilt for it, while your session and every other subagent stay where they were.

That matters because subagents run inside the same process you do. The main session also moves the process working directory when it re-roots, so that a command you run and a relative path you write agree with the project you have open. A subagent doing the same would move the ground under everyone else, and the symptom would be a command running in the wrong repository with nothing on screen to explain it.

The trade is that a subagent working elsewhere does not pick up that project’s settings, capabilities or plugins, because those are read once for the process. Give a subagent a task in another project only when the work is self-contained, and re-root your own session instead when you want that project’s configuration to apply.

The full key list is in the settings reference.

Writing a subagent

A subagent is one markdown file: YAML frontmatter that states its name, what it is for and what it may use, and a body that is its system prompt. Veyyon reads the file at startup, the roster lists it beside the bundled agents, and the task tool can spawn it once its row is enabled.

Where the file goes

$ mkdir -p ~/.veyyon/subagents
$ $EDITOR ~/.veyyon/subagents/accessibility-reviewer.md

~/.veyyon/subagents/*.md is the only place veyyon reads user-authored agents from. Every profile reads that directory, so an agent is written once. Whether a profile may spawn it is a separate answer, subagent.agents.<name>.enabled, stored per profile.

There is no project-level directory. A definition supplied by a repository could shadow a bundled agent by name, and first-run setup would then offer that role as an ordinary row.

Extensions ship agents in their own agents/ directory, which veyyon discovers from the extension roots. That spelling is the plugin-author contract and is not a path to type by hand.

The shape of the file

---
name: accessibility-reviewer
description: Reviews terminal interfaces for accessibility problems and reports findings.
tools: read, search, bash
model: anthropic/claude-opus-4-5
thinkingLevel: high
---

You review terminal interfaces for accessibility problems.

Report each finding with the file, the line and the input that reproduces it.
Report nothing you have not reproduced.

name and description are required; a file missing either is skipped. Everything else is optional.

A two-word key is read in either spelling: thinkingLevel and thinking-level reach the same field, and so do autoloadSkills and readSummarize. An underscore does not, so thinking_level is ignored. The bundled definitions use the dashed form, so an unpacked agent reads thinking-level: medium where the table above says thinkingLevel.

A name in tools that matches no built-in tool and carries no mcp__ or extension namespace is reported at startup. The tool grants nothing and its guidance is left out of the system prompt, so a typo reads as an agent that chose to do nothing.

The body is the system prompt

Everything after the frontmatter is the agent’s system prompt, rendered with Handlebars. Write it as instructions to the worker: what it owns, what it must not touch, what it returns. The worker sees this instead of the main assistant’s prompt, not in addition to it, so state the constraints that matter for the lane.

Enable it

Discovery makes the role available. Spawning it needs the row enabled in the profile you want it in:

$ veyyon config set subagent.agents.accessibility-reviewer.enabled true

Or open /settings → Subagents → Roster, select the agent, and set its state there. The same page sets that agent’s model and effort, which outrank the model: and thinkingLevel: in the file.

Start from a bundled agent

veyyon agents unpack writes the shipped definitions to ~/.veyyon/subagents/ as ordinary markdown files, frontmatter and all. Copy one under a new name and edit it.

$ veyyon agents unpack --dir ./unpacked-agents

--dir writes them somewhere else, which keeps the unedited copies out of the directory discovery reads.

A definition that keeps a bundled agent’s name replaces that agent: a file in ~/.veyyon/subagents/ outranks the bundled definition of the same name, so writing reviewer.md there means your reviewer is the reviewer.

Check the result

Open /settings → Subagents → Roster. The agent is listed there with its state, the model it resolves to, and which setting decided. An agent that is discovered but not enabled is listed and refused when named, with the setting to change.

A file that is skipped says why on startup: a missing name or description, a file that cannot be read, or a tool name that matches nothing.

Multi-agent monitoring

The interactive TUI is the main surface for one session. Status line, session tree, background jobs, the subagent dashboard, and optional swarm orchestration cover multi-agent work.

Status line

Configure under Settings → Appearance → Status Line (/statusline jumps to this group), or in config.yml:

Built-in segment IDs include: pi (legacy product mark segment), profile, model, account, mode, 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, collab.

The model segment shows the model you are working with, then two things that are easy to confuse, so they are drawn differently:

• The thinking effort joins the model label as one unit (Sonnet 4.5 @high in the quiet footline, Sonnet 4.5 · high elsewhere), in the model’s own color. It is how much reasoning the model does per turn. Change it with /effort (its alias is /thinking), or set a per-model default under Settings → Model → Default Effort. The effort picker has a Default row followed by only the active model’s valid variants. Choose Default to clear the session override and return to the saved per-model effort or the model default.
• The priority tier follows the effort as its own chip, named and in the warning color (⚡ priority, or just priority when your symbol preset has no icon). It is how your requests are queued and served, not how deeply the model thinks. Toggle it with /fast, or set it per provider family under Settings → Model → Service Tier.

The git segment shows the current branch, and appends the multi-step operation you are part-way through when there is one:

main                 on a branch, nothing in progress
detached             detached HEAD
topic|REBASE         rebasing topic
main|MERGE           a merge that stopped on a conflict
main|CHERRY-PICK     a cherry-pick that stopped on a conflict
main|REVERT          a revert that stopped on a conflict
main|AM              applying a patch series with git am
detached|BISECT      bisecting

A rebase detaches HEAD, so without the suffix the segment could only say detached, which shows neither the branch being rebased nor that a rebase is running. Veyyon reads the branch back from the rebase’s own record, so you see topic|REBASE. A merge is the opposite case: it leaves HEAD on its branch, so the segment would look like an ordinary checkout while your working tree holds conflict markers. The suffix is what distinguishes them.

The pr segment is skipped while any of these operations is in progress. A branch being rebased does not yet point where it is going to end up, so a pull request looked up against it would describe a state that is about to be replaced.

The profile segment shows the active profile name (work, rec, a client sandbox), so you always know which profile’s config, sessions, and keys are live. It hides itself on the built-in default profile, so an unconfigured status line stays clean. Every built-in preset places it, so switching profiles is visible without any configuration.

The path segment shows the working directory, shortened in three steps: a workspace root is stripped off the front, the home directory collapses to ~, and what is left is clipped to a column budget from its front, so the directory you are in stays readable. Each step is a statusLine.segmentOptions.path key:

statusLine:
  preset: custom
  segmentOptions:
    path:
      displayRoots: ["~/code", "/srv/workspaces"]  # workspace roots, most specific first
      maxLength: 40                                 # columns the path may spend
      abbreviate: true                              # collapse the home directory to ~
      stripWorkPrefix: true                         # strip a workspace root at all

displayRoots lists the directories your projects live under, and ~ stands for the home directory. A working directory under one of them is shown relative to it, so /srv/workspaces/platform-services/normalizer reads platform-services/normalizer. The first entry that matches wins, which is how a nested root is named ahead of the one above it. The list replaces the defaults rather than adding to them; without it the defaults are ~/Projects and /work/. An entry that is not an absolute path cannot contain a directory, so it is dropped and named in the log once. stripWorkPrefix: false turns the whole step off.

A project inside a temporary directory is shown relative to that temporary directory instead, with its own icon, whatever displayRoots says.

The launch card draws the whole row before the session mounts. The working directory comes from the process, the branch from .git/HEAD and its ref files, and the mode from config. The model name, the effort beside it, the dirty marker (*) and the context gauge are what a previous launch recorded, in cache/launch-facts.json.

That file records three kinds of fact. The model’s display name, its provider, the effort and the at-rest context reading belong to the model, so they are stated in every project you use it in, including one you open for the first time. The dirty marker belongs to the project, because it describes that working tree. The gauge is recorded under both, as two different numbers: the project keeps the whole reading measured in that directory, and the model keeps the same reading with that project’s context files subtracted. A project that has never been measured states the model’s number, so it starts from a cost every project shares rather than from the last directory’s AGENTS.md. Those two maps are keyed by the release as well.

The third fact is the terminal’s background color, keyed by the terminal and by nothing else. A new release does not change what an emulator draws, and it is the same window whichever directory is open in it. Veyyon queries the background at startup and the reply arrives after the card is on screen, so the card mixes the composer hairline, the composer outline and the transcript rules out of the background this terminal reported last time. A reply that contradicts the record takes effect on the next frame. Each of the three maps holds its 24 most recently written entries.

Each recorded fact is replaced by a measured one as the session mounts. A tree committed from another terminal since the last launch keeps the recorded marker until git status answers, about 130ms in. A project you open for the first time has no dirty marker. The gauge reads ? only until this model has idled somewhere once; after that a new project starts at the model’s subtracted reading and the session adds what this project’s own context costs, so the bar fills rather than empties when the session lands. Configuring a different model resets it to ? again, because a reading is a fraction of the window it was taken against. A model you have never run states its configured id’s last path segment until the catalog supplies a display name.

A repository whose refs are in a reftable has no ref files to read, so its branch appears with the session rather than with the card, as does a detached HEAD with no operation to name.

/secret list states what is live where you are working: the credentials the vault holds here, and a count of the values being masked that nothing can name, with the environment variable or secrets.yml path each came from. The status row does not carry a count. It reported one that nothing else in the product agreed with, and a number a reader cannot reconcile with /secret list is worse than no number.

The context_pct segment answers one question: how much room is left before the context runs out. “Runs out” means whichever comes first, auto-compaction firing or the model’s window filling, so with auto-compaction on the segment measures against the compaction trigger, not the window. The window itself is what context_total prints.

In the composer’s quiet footline the segment renders as an 8-cell bar with a labelled percentage: ▰▰▰▰▰▰▱▱ 76% left ∞. The bar drains, one cell per eighth of the room remaining, so the bar and the number always agree. Filled cells take the usage hue (silver, then gold, ember, and red as room runs out). While the model is running, the last remaining cell pulses between filled and empty, faster once you are past 90 percent used; at rest the bar never moves, so an idle screen is still. A session-accent ∞ after the bar means auto-compaction is on, so the session continues past the trigger.

Classic status-line presets render the same measurement as text, in tokens on both sides of the slash: 47K/170K. For a full picture of what is in the window, and how it is divided between the system prompt, tools, skills, and messages, run /context.

Two run clocks tick alongside the segments, both measuring model runtime, never idle wall time. While the agent runs, the location line (path and git branch) ends with the current run’s elapsed, in M:SS form and widening to H:MM:SS past the hour: …keyhog · main * 12:34. When the run finishes the clock freezes as ✓ 12:34 (checkmark plus the final M:SS/H:MM:SS readout); before the model has ever started it shows nothing. The working line shows how long the current step has been running, between the step label and the esc hint: Running tests · 0:42 ⟦esc⟧; that clock restarts whenever the step changes. The time_spent segment is related but cumulative: it sums every run in the session (a fresh session with /new starts it at zero) and appears in the full and nerd presets.

Session tree and agents

/cockpit and /hub are aliases of /agents, as is the app.agents.hub keybinding and a double-tap of the left arrow on an empty composer. They used to open a separate screen with its own roster and its own drill-in, which meant “which agents are running” had two answers that could disagree with each other. They all open the one card now.

One conversation at a time

A process runs more than one conversation at a time. /new stops the previous one unless session.newKeepsBackground is on, and an ACP client keeps every open session in the same process. Changing session.newKeepsBackground takes effect on the next launch; the running session keeps the value it started with (#928).

The card is scoped to the conversation on screen: the roster, the Comms stream and the transcripts it opens are that conversation’s. A conversation this process is still running off-screen is counted by the status line’s background chip and has no card of its own.

The Live roster

Each row is one agent that exists right now: a status glyph, its call sign, the TYPE of agent it was spawned from (reviewer, scout), its status, how long since it last did anything, and what it is doing. Rows sit in spawn order, oldest first, with your own session at the top. The row you are on is marked two ways, a cursor glyph in the first column and a band across the whole row, so it stays readable on a terminal that renders no colour. Agents from earlier runs of the same session appear too, marked parked, because their transcripts are still on disk even though this process never started them.

Press Enter on a row and the main view becomes that agent’s session: the transcript, the composer, and the status line all point at it, so you read what it is doing and then answer it. Press Esc there to come back to your own session. While you are focused on an agent, the composer footline contains a persistent <agent-id> · esc to go back badge at the left, and the inline Subagents block above the composer lists that session’s own spawns, so inside a leaf agent with no spawns of its own the block disappears. Opening a parked agent revives it on the way in.

To terminate a subagent, select its row and press x, or hover the row and click the [x] at its right edge. Both gestures open the same confirmation card. Choose Dismiss to return without changing the agent, or choose Yes, terminate to abort any turn in flight and release the session. The transcript stays on disk. Your main session and read-only advisor transcripts do not show the termination action.

Clicking elsewhere on a row does the same thing as Enter, and clicking a name in the view strip switches to that view. Opening an agent is reversible with Esc, so a row click opens rather than only moving the cursor. The scroll wheel moves whatever the arrow keys move: the roster cursor on Live, the stream on Comms. Page up and page down move by a screenful, on either view.

The roster is a table, so you can scan a column instead of reading every row: the status, the age, the model and the activity each start at the same place on every line. A name long enough to crowd the row out is truncated rather than paid for by every other row, and the model badge is dropped when the card is too narrow to show enough of it to recognise.

Two agents open a read-only transcript instead of handing the main view over. An advisor is observability-only and is not an addressable peer, so there is nothing on the other end to receive a reply. A collab guest’s agents live on the host, so there is no local session to point at.

The inline task widget also shows the model each subagent runs on, right in its status line, so you can see which model every launched subagent used without opening the Control Center. The Subagents block above the composer in your main session shows the same badge on every running row, so the answer to “what is that one running on” is on screen without opening anything. To show the badge, keep subagent.showResolvedModelBadge on (Subagents settings); turning it off hides it on all three surfaces.

Session files are append-only JSONL under the active profile’s agent sessions/ directory. See Sessions.

Inter-agent messaging

Subagents and the main agent use the irc tool (send, wait, inbox, list) over a process-global mailbox. The Comms view of /agents streams that traffic as it happens, oldest first, including the messages that failed to reach their recipient and the reason they did not land. Long messages are folded to their first few lines with a count of what was hidden; ctrl+o unfolds every message in the view, and pressing it again folds them back. Both ends of a message are labelled with the call sign the Live roster shows for that agent, so you follow a conversation by who is speaking rather than by an id you have to look up on the other view. An agent that has since been released has no call sign left to show, so its messages print its id instead.

The view reads the message bus, not the session files. A subagent’s transcript records what THAT agent received, so a view built from transcripts would show each half of a conversation in a different file and would never show a message that failed to arrive at all. /btw is an ephemeral side question; /tan spawns a background agent for tangential work. (/omfg is unrelated: it forges a TTSR rule from a complaint to stop a recurring behavior.)

Swarm extension

@veyyon/swarm-extension runs multi-agent DAG workflows from YAML (pipeline, parallel, or sequential). Standalone: veyyon-swarm path/to/swarm.yaml. In the TUI, add the package to extensions, then:

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

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

Keybindings

Remap TUI shortcuts from ~/.veyyon/profiles/default/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.

Action IDs from older releases (interrupt, fork, cursorUp) are renamed to their current IDs (app.interrupt, app.session.fork, tui.editor.cursorUp) the first time veyyon loads the file, and the file is written back. The rename happens where the binding already sits, so your comments, blank lines, and key order come back unchanged:

# hold this one, muscle memory
interrupt: ctrl+x

becomes

# hold this one, muscle memory
app.interrupt: ctrl+x

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/handbook/src/reference/keybindings-config.md.

Slash commands

Remap keys by editing keybindings.yml; /hotkeys shows the current bindings.

There is no Vim or modal editing mode; the composer uses the bindings above.

Web search

The web_search tool runs a multi-provider search and returns ranked results (and, for some providers, answer-plus-citations). Use it for current docs, package versions, and online references.

Configuration

Two settings control the tool:

Both are in settings → Tools / Providers, or in config.yml:

web_search:
  enabled: true
providers:
  webSearch: auto

You can also scope this to a profile, so one profile searches the web 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:
  enabled: false

Provider support

The tool queries a configurable search backend, API-backed providers (using keys you have configured) or credential-free engines (Startpage, Google, DuckDuckGo, Mojeek, or public, which fans out to every credential-free engine and consolidates deduplicated results). auto resolves the first available provider in the built-in priority order; providers.webSearchExclude removes providers from that chain entirely.

Exa research and webset tools

Beyond ranked search, Exa hosts two MCP servers that Veyyon can turn into agent tools. Both are off by default, because each one adds tools to every session and costs a discovery request at startup.

exa:
  enableResearcher: true
  enableWebsets: true

exa.enableResearcher adds exa_deep_researcher_start and exa_deep_researcher_check. The model starts a research run and then polls it, so a single question can take minutes and returns a written report rather than a result list.

exa.enableWebsets adds one tool per webset operation the server offers, named exa_<operation>. The list comes from the server, so new operations appear without a Veyyon release. Websets require EXA_API_KEY in your environment; if it is missing, Veyyon logs the reason at startup and registers no webset tools rather than failing later inside a tool call.

exa.enabled: false turns off all of it, including search.

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. If you want the model to never reach the web, set web_search.enabled: false. See Sandbox and approvals.

Code review

Review surfaces:

1. /review: bundled interactive review command (branch, commits, or uncommitted work).
2. Advisor: optional second model that comments on main-agent turns.
3. Plan review: /plan-review while plan mode is active.
4. Non-interactive: free-form review prompts under veyyon -p.

/review

Bundled custom command (packages/coding-agent/src/extensibility/custom-commands/bundled/review). Launches a review flow over a chosen target and uses the review tool surface (report_finding, …). See the command help in-session and docs/handbook task guides for example prompts.

Advisor

The advisor is a second model role that reads each main-agent turn and can inject notes (nit, concern, or blocker). Enable with --advisor or the advisor.enabled setting; assign its model via the advisor role. Uses its own context and model assignment when configured.

Plan review

Inside plan mode, /plan-review reopens review of the current plan file. See Plan mode.

Non-interactive

$ veyyon -p "review the uncommitted diff for correctness and missing tests"
$ veyyon -p --yolo "review this branch against main; list P0/P1 findings only"

Typical targets: uncommitted work, a branch delta, or paths named in the prompt. Exit status follows the print-mode run (veyyon --help).

Approvals

Tool approvals use tools.approvalMode and per-tool policy. See Approvals and Safety.

Related

• Approvals
• Non-interactive mode
• Roles and profiles

Non-interactive mode (veyyon --print)

--print (short -p) runs Veyyon without the interactive TUI: one prompt, tools run under the active approval mode, then exit. Use this from scripts, CI, 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 may be a CLI argument or stdin. If both are present, the piped stdin content is prepended to the argument prompt (stdin first, then the argument, separated by a newline).

Run veyyon --help for the generated flag set. Common options:

Session and config

Output and models

Headless runs have no TTY for approval prompts: choose a mode that does not block (--yolo only on disposable runners) or expect the turn to stop when a prompt would be required. See Approvals.

Related

• Approvals
• Safety
• CLI

Themes and identity

Veyyon’s interface is built around near-black, near-white, silver structure (#C6CBD4), and a single ember accent (#F0862E) — the same tokens the website ships.

Bundled themes

A larger bundled catalog ships under modes/theme/defaults/ and is selectable from the theme picker.

Changing theme

• Settings UI: /settings → Appearance → theme (or the theme picker on first run).
• Config: theme in ~/.veyyon/profiles/default/agent/config.yml (profile-specific when using --profile).
• Custom themes: drop JSON under ~/.veyyon/profiles/default/agent/themes/; schema in docs/handbook/src/reference/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.

Backgrounds

Veyyon paints no backgrounds by default. The transcript (user messages, tool output, extension messages), the composer, and the status line all inherit your terminal’s own background, so the UI looks native on any terminal color. Two opt-ins bring painted surfaces back:

• Turn off statusLine.transparent (/settings → Appearance → Status Line) to paint the theme’s statusLineBg bar, including powerline end caps.
• A custom theme can declare a composerBg color to paint the composer card; when omitted, the composer stays unpainted.

Painted ground

tui.paintGround (/settings → Appearance → Display) controls whether Veyyon sets the terminal’s own background color (OSC 11) to the theme’s ground while it runs, so the UI fills the window edge-to-edge instead of floating on the terminal’s configured background. The original background is restored on exit, including crash exits.

The ground is the theme’s page background, the same export.pageBg color the HTML export uses (see docs/handbook/src/reference/theme.md). Every built-in theme declares one.

On auto, the decision is taken before the launch card paints, from the background this terminal reported on the previous launch (cache/launch-facts.json). The first launch in a terminal has no record and inherits; the report that follows paints the ground if it is close enough. A report that contradicts the record takes effect on the next frame.

A custom theme that declares no page background has no ground to paint, so Veyyon inherits the terminal’s own background regardless of this setting. With always, it also logs once that the active theme declares no ground, since that is the one case you asked to paint and it could not. Add an export.pageBg to the theme to give it a ground.

Terminals that don’t support OSC 11 ignore the sequence; nothing breaks.

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 (VEYYON_CONFIG_DIR; XDG paths after veyyon config init-xdg)
• npm packages: @veyyon/*

Collab: Live Session Sharing

/collab shares a running session with other Veyyon instances over a relay. Guests open the session in their own TUI (assistant text, tool cards, footer state, /dump); the host process runs the agent and tools. This is not terminal multiplexing.

Quick start

Host:

/collab

prints

Collab session started!
 • Join from another terminal: veyyon join "mgAYTZwEnpRQtca0CTgn-Q.gdJUbTovD94ofDaa8YvhY0-ty16w4fn8PgB6PLnoA30"
 • or any web browser: share.veyyon.dev/#mgAYTZwEnpRQtca0CTgn-Q.gdJUbTovD94ofDaa8YvhY0-ty16w4fn8PgB6PLnoA30

The browser line is click-to-join (an OSC 8 hyperlink to the full https:// deep link): the relay serves the web guest client at /, and the room id + key ride in the URL fragment. From another veyyon (any directory, any machine), either form works:

Running /collab or /collab view starts or displays the active hosting session, rendering both the terminal/browser join links and their corresponding QR codes.

/join share.veyyon.dev/#mgAYTZwEnpRQtca0CTgn-Q.gdJU…

The guest’s previous session is restored on /leave (or when the host stops).

Commands

Link format

Accepted by /join <link> and veyyon join "<link>":

<roomId>.<key>                                                    → default relay (wss://share.veyyon.dev)
<roomId>#<key>                                                    → legacy bare form
host[:port]/r/<roomId>.<key>                                     → custom relay, wss:// inferred
host[:port]/r/<roomId>#<key>                                     → legacy direct relay form
https://host[:port]/r/<roomId>.<key>                             → direct relay URL, normalized to wss://
wss://host[:port]/r/<roomId>.<key>                               → direct websocket relay URL
ws://localhost:7475/r/<roomId>.<key>                             → direct plain ws, localhost only
https://host[:port]/#<link>                                      → browser deep link when web UI and relay share a host
https://web-host[:port][/<path>]/#<relay-link>                   → browser UI wrapper with relay link in the fragment
https://web.example/collab/#relay.example.com/r/<roomId>.<key>   → web UI and relay on different hosts

<link> / <relay-link> are parsed recursively as any accepted link above. For http(s) browser wrappers with a parseable fragment, the fragment wins before the HTTP host/path are treated as a relay. This lets https://web.example/collab/#relay.example.com/r/<roomId>.<key> open the web UI at web.example while joining wss://relay.example.com/r/<roomId>. If the fragment is not a complete collab link, parsing falls back to the legacy direct relay form, so https://relay.example.com/r/<roomId>#<key> still means relay relay.example.com.

The trailing .<key> or #<key> part is the room secret, base64url-encoded, in one of two strengths:

• Full link: 48 bytes: the 32-byte AES-256-GCM room key followed by a 16-byte write token. Grants prompting, interrupting, and subagent control.
• View-only link: the bare 32-byte key, no write token. Grants live read access only. Pre-token links parse as view-only.

The room secret is dot-joined in newly generated links because RFC 3986 forbids a raw # inside a URL fragment; parsers still accept legacy # forms and %23-mangled legacy deep links.

End-to-end encryption

Every session payload (entries, events, state, prompts) is sealed with AES-256-GCM before it touches the socket. The relay sees only:

• room ids and connection counts,
• opaque ciphertext frames and their sizes,
• a 4-byte routing prefix (which guest a frame targets).

Possession of the link is the trust boundary: a full link reads and steers the session, a view-only link reads it. Share both like secrets.

Guest permission model

Two trust levels, enforced by the link itself, the host verifies the 16-byte write token at join and rejects writes from peers without it (they appear as read-only in the participants list, and the join notice reports it).

Guests with a full link can:

• read the entire session (including the back-transcript at join time),
• prompt the agent (rendered with their name badge on every participant’s transcript; the LLM sees the prompt text verbatim: names are display-only),
• interrupt the agent (Esc),
• use the subagent dashboard against the host’s subagents: live roster and progress, chat (steers the host’s subagent), kill, and transcript viewing (fetched from the host on demand). A guest reads a transcript rather than taking over a session, because the sessions live on the host.

Guests with a view-only link can read everything live, back-transcript, streaming text, tool cards, subagent transcripts, but the host rejects prompting, interrupting, and agent control from them.

Everything that mutates the host session or machine is host-only: /model, /compact, /resume, /branch, bash (!), python ($), skills, etc. Guests keep a small local allowlist (/dump, /export, /copy, /welcome (aliased /help), /hotkeys, /settings, /leave, /collab, /exit, /quit).

Known v1 limit for guests: a turn already streaming when you join becomes visible from its next message boundary.

Web client

packages/collab-web is a standalone browser client for the same links, no veyyon install needed on the guest side. The relay serves it at /, which is what makes the /collab deep link click-to-join: https://<relay>/#<link> loads the client and auto-connects from the fragment. It renders the live transcript (streaming text, thinking, tool cards), a subagent panel with on-demand transcripts, and a composer with the same guest powers (prompt, interrupt, hub actions). Run bun run dev in the package for a local instance, bun run mock-host for an offline scripted host to develop against, and bun run build to emit a static dist/ deployable anywhere (HTTPS required for WebCrypto). The client never talks to anything but the relay, and the key stays in the URL fragment.

Set collab.webUrl when the browser UI is hosted separately from the websocket relay. When empty, /collab derives http(s)://host[:port] from collab.relayUrl; explicit web UI URLs must use https:// except for http://localhost development origins. The generated browser URL still contains the relay-specific collab link in the fragment.

Settings

Self-hosting the relay

The relay is a small content-blind Go service. It keeps no state beyond live connections and exposes:

• GET /: the static collab-web guest client (target of the /collab deep link),
• GET /r/<roomId>?role=host|guest: WebSocket upgrade,
• POST /s / GET /s/<id> / GET /s/<id>/raw: /share blob upload, viewer page, and blob fetch,
• GET /healthz: liveness.

Close codes

A relay closes a socket with one of four codes when reconnecting would be pointless:

Any other close code is transient, and a client reconnects with exponential backoff up to thirty seconds. That default is why the table matters: a client that does not recognise a fatal code retries against a condition that will never clear, quietly, so the codes are declared once in packages/wire/src/relay.ts and both the CLI and browser clients read them from there. If you write your own relay, close with these codes and these reasons; a code outside the table tells a client to come back.

Architecture notes

Hub topology, the host is authoritative, guests never peer:

1. entry frames: durable session entries, broadcast pre-blob-externalization so images stay inline (guests cannot resolve host blob refs). Guests append them verbatim (ids preserved) to a replica session file under ~/.veyyon/profiles/<profile>/collab/<roomId>.jsonl and into the agent’s message array, which is why /dump and context estimates work.
2. event frames: live agent events, fed straight into the guest’s normal event controller; rendering is events-only to prevent double-render.
3. state frames: debounced footer snapshots: streaming flag, the host’s full model object and thinking level (applied to the guest’s replica agent state, so model display and context-window math are native), host context numbers, and participants.
4. bus frames: mirrored task-subagent lifecycle/progress EventBus traffic, republished on the guest’s local bus so the subagent HUD and status-line count work natively.
5. agents frames: agent-registry snapshots feeding a guest-local registry, so the subagent dashboard roster renders host subagents.

Guest→host: hello, prompt, abort, agent-cmd (hub chat/kill/revive), and fetch-transcript (incremental subagent-transcript reads answered by targeted transcript frames). The replica loads through the regular /resume machinery, so theming, ctrl+o, and transcript behavior are native by construction; the guest process never chdirs to host paths.

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, 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/profiles/<name>/agent/hooks/ (the active profile). Hooks are user-level only: a .veyyon/hooks/ directory inside a repository is not read. The module exports a factory that registers handlers with pi.on(...).

// ~/.veyyon/profiles/default/agent/hooks/post-edit-check.ts
export default (pi) => {
  pi.on("tool_result", async (event) => {
    if (!/^(edit|write)$/.test(event.toolName)) return;
    // run your check (spawn a test/linter); return { block, reason } from tool_call to deny
  });
};

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

Run a bounded task from a script or CI

Use veyyon --print (-p) when the trigger lives outside the agent (pre-commit, CI, entr, watchexec):

$ veyyon -p \
    "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. Leave the rung alone unless you have a reason to move it: the default auto auto-approves every tier, while a target outside the working directory, a call that spends a stored credential, a per-tool prompt/deny policy, and a critical command such as a recursive delete of your home directory all still ask, and a headless run has no terminal to ask on, so each of those becomes a failed tool call rather than a silent pass. Do NOT pass --approval-mode ask-command here: it prompts for every exec-tier call, which in -p means every command fails. --yolo auto-approves all tiers and drops the two boundaries (use only on disposable runners). JSON event streams: --mode json. For review, pass a review prompt to -p, or use the passive advisor (--advisor) in the TUI. See Non-interactive mode.

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/profiles/default/agent/mcp.json directly (the active profile’s file; there is no project scope):

{
  "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 under the active profile, for example ~/.veyyon/profiles/default/agent/skills/audit-config/SKILL.md:

---
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.
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/profiles/default/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, /branch to try an alternate approach, continue on the branch that works. Full behavior: Branching and Sessions.

Memory vs branching

• Memory stores durable facts across sessions when a backend is enabled.
• Branching forks live transcript context for the current problem.
• Branch to explore; use memory for decisions that should outlive one session.

Track long work without repeated reminder walls

Use the todo tool for work that has several independent steps. The session stores every phase, task, and status. Compaction and handoff keep that complete structured state, including plans with dozens of items.

When the model tries to finish with open work, Veyyon injects one continuation instruction for that exact todo state. The instruction states to continue, puts the active task first, shows at most five open items, and reports how many more remain hidden. It does not replay an unchanged state after a user says continue or after an unrelated tool call. A real todo change makes the new state eligible for one reminder, up to the configured limit.

Model-facing todo output and the collapsed TUI use the same sanitized, width-bounded, active-first projection of at most five items. The complete phases, tasks, and statuses remain in machine state. To clear that state intentionally, run /todo rm without a task or phase; completing or dropping items keeps their closed history until it is explicitly removed.

The anchored Todos block above the composer is a railed list. Every phase gets one row with its tally, so a stage that just closed three tasks does not look like one that has done nothing, and task rows are drawn for the phase being worked and the few after it. The block is bounded by the viewport: it never grows past a third of the terminal’s height, it drops finished phases from the top before it drops work in flight, and it states how many rows it withheld. Expanding it shows every task of the phases it draws, not an unbounded list — an anchored region that outgrows the screen cannot be scrolled away from.

Each row’s glyph is its state, before any colour: □ waiting, a breathing cell in flight, ▪ done, ∎ abandoned. A task a detached subagent picked up breathes in that agent’s own accent and names the agent at the right, which is the same hue its lane carries in the Subagents block. Light travels down the rail while anything on the board is in flight and the rail is flat while nothing is, so a board waiting on you is distinguishable from a board being worked. A task closing sweeps a strike across its text, exhales its glyph and cools from green to grey; when the last task closes, the whole block makes one pass down its rail and clears. Where display.transitions is off, all of that is still and the glyphs are static. Configure the behavior under Settings → Tools → Todos:

• Todo Reminders enables continuation instructions for unfinished plans.
• Todo Reminder Limit caps distinct todo-state reminders before reminders stay silent.

See also

• Configuration for the keys these guides touch
• Examples for prompt-shaped tasks

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 states 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. Enable the advisor watchdog (advisor.enabled) 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 the call returns an error tool result with hints 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 Rust + TypeScript CI matrix documented in CONTRIBUTING.md when touching Rust natives.

Use the model/provider contract

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

See Model contract and Providers.

Recorded end-to-end workflow

The landing-page recording is one operator task carried to a signed artifact, in a single unbroken session. The task audits the numeric environment defaults of a small service. Before submission, /secret from-env stores a synthetic release key as the placeholder #RELEASE_SIGNATURE#.

The model writes a three-phase, six-task plan and holds it until told to start. It fans three directory-scoped refactors out to parallel workers, one per directory, applies the edits itself where the change is one guard, and verifies that all nine documented defaults resolve in an environment stripped of every one of those variables. It then signs its work in one bash call: the sha256 of #RELEASE_SIGNATURE# appended to SIGNED.md as a single line. Veyyon resolves the placeholder only at the outbound tool boundary and requires approval before the call runs, so the credential itself is never printed and never reaches the transcript. The board closes 6/6.

The recorded clip runs the whole task. Untouched screens are shortened rather than accelerated.

See Testing and verification for the recording environment and the regeneration command.

Plan mode and goals

Plan mode and goal mode are separate engine modes with different tools and continuation behavior. They cannot be active together (and each conflicts with vibe mode).

Plan mode

Read-focused exploration that drafts a plan file before implementation.

Enabling

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

Behavior

1. Session selects a plan file path and records plan-mode state.
2. Tool surface adjusts: resolve is available for plan approval; plan-file write/edit may be enabled for drafting.
3. The agent explores and writes the plan (read-oriented work plus plan-file edits).
4. Finalization uses the resolve tool with plan-approval semantics (plan_approval).
5. Exit: /plan again (confirmation if a draft exists). Session records mode entries in the session file.

When configured, plan mode uses the plan model role.

Goal mode

A persistent objective on a saved session, with optional auto-continuation when idle.

Enabling

• Setting: goal.enabled (default true)
• /goal set <objective>: create or replace
• /goal show: status and token usage
• /goal pause / /goal resume
• /goal drop: remove
• Setting: goal.modelBudgetsEnabled (default false), controlled only from the interactive Settings UI
• /guided-goal: interview flow before enabling

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. The tool never accepts a budget argument. The interactive Settings UI owns goal.modelBudgetsEnabled, which controls whether persisted budgets are exposed and enforced. Continuation prompts inject on idle turns per goal.continuationModes.

Example

$ veyyon

/goal set Add a --max-time flag to the print-mode runner and document it

Use /goal show for progress. Pause with /goal pause. Complete via the goal tool or /goal drop.

Architecture notes: Goal state. Sessions: Sessions.

Vibe mode

/vibe toggles vibe mode. The main agent becomes a director with a reduced tool set (read, vibe_spawn, vibe_send, vibe_wait, vibe_kill, vibe_list) and drives worker CLIs (fast / good model lanes) instead of editing files itself.

Mutual exclusion: plan mode, goal mode, and vibe mode cannot run together; the TUI warns if you try to enter one while another is active.

Permissions: vibe_spawn and vibe_send are exec-level tool calls, so starting a worker or handing it a new instruction is gated by the session approval mode exactly like running a command (vibe_wait, vibe_kill, and vibe_list are read-level). Each worker then runs headless with the full tool set (edit, write, bash, …) and executes autonomously, a detached subagent has no UI to confirm prompts against, so approving the spawn is the authorization boundary. Your tools.approval allow/deny policies still apply inside every worker, so path and command denials you have configured are enforced there too. Workers are killed when you leave vibe mode, so none outlive the director that drives them.

Skills

A skill is a folder of instructions you drop into your profile, and the agent picks it up on its own. Use one to teach Veyyon a repeated task: how your project runs its tests, the steps of a release, the shape of a code review. Skills live on disk, not in the binary, so you add or change one by editing a file, with no rebuild.

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

Skill locations

Skills load only from the active profile. Veyyon reads these three locations, all under $HOME/.veyyon/profiles/<profile>/agent (profiles/default/ when you have not selected a profile):

Nothing else contributes skills. There is no autodiscovery from across your computer: another tool’s skill directory ($HOME/.claude/skills, $HOME/.codex/skills, $HOME/.agents/skills, .github/skills, and the rest) is never scanned, and a project-local .veyyon/skills directory next to your code is not read either. Skills belong to your profile, so switching profiles switches the whole skill set, and no repository you open can inject a skill into a session.

Full provider list and dedup rules: docs/handbook/src/reference/skills.md.

Importing another tool’s skills

Because foreign skills never load on their own, you bring one into Veyyon by importing it. The onboarding import scan finds user-level skills and instruction files that other AI tools (Claude, Codex, Gemini, Cursor, and similar) left on disk, and copies the ones you pick into the active profile’s skills directory. The copy is profile-owned from then on, so it loads like any other profile skill and is not affected by the original tool.

A separate setting, discovery.importForeignConfig, governs whether Veyyon ambiently reads other tools’ context files (CLAUDE.md, standalone AGENTS.md), rules, and MCP servers. It ships off, so by default Veyyon reads no foreign tool’s config directory and no GEMINI.md. It does still read a project’s own AGENTS.md or CLAUDE.md on the walk from the repository root down to your working directory: those are the project’s instructions to any agent, not another tool’s private config. Turn the setting on to load the rest as a machine-wide base layer:

discovery:
  importForeignConfig: true

The setting does not change skill loading: foreign skills are never loaded ambiently whether it is on or off. It also does not gate the import scan. The onboarding scan always finds and offers foreign files for import, because importing copies a file into your profile, which is how foreign config comes in by default now that ambient loading is off.

Veyyon’s own instructions load in four layers, and only these four:

1. The compiled system prompt.
2. The global ~/.veyyon/AGENTS.md, which applies to every profile.
3. The project’s own context files: one file per directory on the walk from the repository root down to your working directory. Each directory offers .veyyon/AGENTS.md (only from the nearest non-empty .veyyon/), then AGENTS.md, then CLAUDE.md, and the first one with content wins. The rest of that directory’s candidates are not read, so a CLAUDE.md sitting beside an AGENTS.md is deliberately not loaded and the same rules are never inlined twice. The choice is made per directory, so a repository root using AGENTS.md and a package using CLAUDE.md both load.
4. The active profile’s AGENTS.md (~/.veyyon/profiles/<name>/agent/AGENTS.md).

That list is the order they are RESOLVED in, not the order of authority. They are rendered least authoritative first, so the strongest file has the last word: the project files come first, then the profile file, then the global ~/.veyyon/AGENTS.md last of all. Your live instruction in the conversation beats every one of them. A narrower file may add detail a broader one does not cover, but it never contradicts, loosens, or forbids what a broader one allows, because a project file is content checked into a repository you may not have written. Within the project layer the file closest to your working directory is the most specific one. See instruction layers below for how to split rules between the global and per-profile files.

Instruction layers

Veyyon reads two AGENTS.md files that you own, plus the project file:

• ~/.veyyon/AGENTS.md is the global file. Put rules here that should hold in every profile.
• ~/.veyyon/profiles/<name>/agent/AGENTS.md is the profile file. Put rules here that apply only to that profile.

Keep each rule in one place. A rule that belongs to every profile goes in the global file; a rule that is specific to one profile goes in that profile’s file. Splitting them this way avoids duplicating the same guidance across profiles.

Veyyon creates the global file for you on first run with a short note at the top explaining this split. The note is an HTML comment wrapped in Veyyon markers, and Veyyon strips it before sending the file to the model, so it never spends any of your instruction budget. It is there for you when you open the file to edit it, not for the agent. A new profile’s AGENTS.md gets the same kind of note. Delete the note if you like; Veyyon does not add it back.

Profiles isolate skills

Each profile is a separate config root ($HOME/.veyyon/profiles/<name>/agent), and every skill source resolves under that root, so profiles never share a skill directory. Switching profiles re-homes user skills, managed (auto-learn) skills, and plugin skills to the active profile, and all skills.* settings are stored per profile. One profile can hold a large skill set while another stays empty.

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.
---

# 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 (required). A skill without one is skipped at load time.
• enabled: Set to false to skip the skill at load time (optional).
• hide / disableModelInvocation: Either one hides the skill from the model-facing list (optional).

Configuration

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

Master switch

skills.enabled (default true) turns skill discovery off entirely:

skills:
  enabled: false

Skill commands

enableSkillCommands (default true) controls whether skills also register as /skill:name commands.

skills:
  enableSkillCommands: false

There are no per-source toggles and no customDirectories setting. Skills load only from the active profile (see Skill locations), so there is nothing to enable or disable per source. To use a skill from another tool, import it into your profile.

Manage individual skills

includeSkills and ignoredSkills are glob lists matched against skill names. An empty includeSkills means every discovered skill is active; ignoredSkills then subtracts.

skills:
  ignoredSkills:
    - my-custom-skill
    - internal-*

Interactive TUI controls

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

Slash commands

• /extensions opens the Extension Control Center, which lists every discovered skill alongside tools and hooks, and lets you enable or disable individual skills.

Toggles persist immediately to disabledExtensions; there is no close-time summary message.

Related recipes

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

Engineering detail: docs/handbook/src/reference/skills.md.

Skills authoring

A skill is a folder that adds a reusable capability to Veyyon. For how skills are discovered and loaded, see Skills.

Directory structure

Skills load only from the active profile. Veyyon reads these locations, all under the profile’s agent dir (profiles/default/ when you have not selected a profile):

Nothing else contributes skills. A project-local .veyyon/skills directory and another tool’s skill directory ($HOME/.claude/skills, $HOME/.codex/skills, $HOME/.agents/skills, and the rest) are never scanned. To use a skill from another tool, import it into your profile, see Skills. For the full provider list and dedup rules, see Skills.

Create a new skill by making a directory inside the profile’s skills dir 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
└── scripts/, references/, assets/ ...optional

Only SKILL.md is required. The other files are loaded when the skill is active or when the model requests 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.
---

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.
• enabled: Set to false to skip the skill at load time.
• hide / disableModelInvocation: Either one hides the skill from the model-facing list.

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.

Configuring in config.yml

There is no registration step: a skill placed in any discovered directory (see Skills) loads automatically. The skills section of config.yml controls which discovered skills are active.

Turn skill discovery off entirely:

skills:
  enabled: false

Filter individual skills by name glob (includeSkills allowlist, ignoredSkills denylist):

skills:
  ignoredSkills:
    - internal-*

includeSkills is the allowlist twin: when it is non-empty, only matching skills load.

Worked example: a profile skill

This example creates a skill in your active profile that adds a custom onboarding check.

Create the skill directory under the active profile (profiles/default when you have not selected one):

mkdir -p ~/.veyyon/profiles/default/agent/skills/onboarding-check

Create onboarding-check/SKILL.md in that directory:

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

# 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.

No registration is needed, a skill under the active profile’s skills directory is picked up automatically. If your config.yml uses an includeSkills allowlist, add the skill’s name to it:

skills:
  includeSkills:
    - onboarding-check

Invoking the skill

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

1. Open /extensions to confirm the skill is enabled, then invoke it with /skill:onboarding-check (available when skills.enableSkillCommands is on).
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

A plugin bundles several extensions into one installable package: skills, MCP servers, hooks, and related assets that ship and update together. Reach for a plugin when you want to share a whole capability at once instead of wiring each piece by hand. See Connectors for the current integration surface (MCP, plugins, hooks, and skills).

Plugin Structure

Every plugin is a directory with a .claude-plugin/plugin.json manifest file (the Claude Code-compatible path). The manifest describes the plugin’s metadata and lists its integration points.

Plugin Manifest (plugin.json)

Veyyon reads these fields from plugin.json:

Other plugin content loads from conventional locations rather than manifest fields: MCP servers from a .mcp.json file at the plugin root, and hooks from .ts or .js modules under the plugin’s hooks/pre/ and hooks/post/ directories. A hook is loaded as an extension module and must default-export a factory, so a shell script placed in those directories is discovered but not run; veyyon reports each one it had to skip.

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. .veyyon-plugin/marketplace.json (preferred)
2. .claude-plugin/marketplace.json (Claude Code-compatible fallback)

The marketplace catalog requires a name, an owner.name, and a plugins list. Each plugin entry requires only a name and a source; optional entry metadata includes description, version, author, homepage, repository, license, keywords, category, tags, strict, and embedded capability fields (commands, agents, hooks, mcpServers, lspServers, dapAdapters). A source can point to a local directory, a Git repository (with optional branch, tag, commit ref, or subdirectory path), a URL, or an npm package.

File Locations

Plugin install state is profile-scoped under ~/.veyyon/profiles/<profile>/plugins/ (default profile: profiles/default/plugins/). Config root is relocatable with VEYYON_CONFIG_DIR.

Command Line Interface

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

Managing Plugins

Install a Plugin

veyyon plugin install accepts four kinds of target:

$ veyyon plugin install sample@debug
$ veyyon plugin install @veyyon/exa
$ veyyon plugin install github:user/repo#v1.0
$ veyyon plugin install ./path/to/plugin

A local path is linked rather than copied: veyyon symlinks the directory into the profile’s node_modules, so edits to the source appear without a reinstall. veyyon plugin link <path> does the same thing, and either verb works.

Use --force to reinstall over an existing install and --scope user|project to choose the install scope. --scope applies to marketplace installs only; npm, git and local installs warn and ignore it. --json prints the installation result as JSON for npm, git and link installs; marketplace installs ignore it.

--dry-run resolves the target and reports the name and version it resolves to, without writing a dependency, a lockfile entry or a node_modules entry:

$ veyyon plugin install github:sindresorhus/slugify --dry-run
[dry-run] Would install @sindresorhus/slugify@github:sindresorhus/slugify#7c318bd

A git target’s package name comes from the repository, not the spec, so a dry run is how you learn the name a git plugin will install under. A target that cannot be resolved — an unpublished npm name, a version that does not exist, a private or missing repository — fails with the resolver’s output and exits 1. A dry run proves the target resolves; it does not prove the package is a veyyon plugin, because nothing is unpacked and no manifest is read.

List Plugins

List installed plugins and their statuses.

$ veyyon plugin list

Options:

• --json: Print the output as JSON.

Uninstall a Plugin

Uninstall a plugin from local cache and config. Pass the name veyyon plugin list shows, which for a git or local plugin is the package’s own name rather than the spec you installed it with.

$ veyyon plugin uninstall sample@debug
$ veyyon plugin uninstall @veyyon/exa
$ veyyon plugin uninstall linked-plugin

Every install route is removable by the same command. Uninstalling a linked plugin removes the symlink and the plugin’s stored settings, and leaves the directory it pointed at untouched: that is your working copy, not veyyon’s.

Use the --json flag to return the removal result as JSON for npm plugins; marketplace uninstalls ignore it.

To keep a plugin installed but inert, use veyyon plugin disable <name>, which leaves it listed and reversible with enable.

Check Plugin Health

Report what is wrong with your plugin installation, and optionally repair it.

$ veyyon plugin doctor
$ veyyon plugin doctor --fix
$ veyyon plugin doctor --json

Each check reports ok, a warning, or an error. doctor exits 1 when any error is left unrepaired and 0 otherwise, so you can gate a script on it. Warnings never affect the exit code, and an error that --fix repaired does not either. --json prints the checks as an array instead of the human-readable report.

On a machine with no plugins installed every check is ok: nothing is missing, because nothing was ever installed. That is the state a fresh install is in, and doctor is quiet about it on purpose.

The checks are:

• plugins_directory, package_manifest, node_modules: the three things a plugin install needs. Each one distinguishes “not created yet” from “there but unreadable”. The first is normal and reports ok; the second is an error stating the path, because a plugins directory whose permissions have been mangled looks identical to an empty one from the outside and the fix is chmod, not a reinstall. A profile holding only linked plugins has no package.json, because linking writes no dependency; package_manifest reports ok and states how many linked plugins are present.
• plugin:<name>: one per installed plugin. An error means the package is missing from node_modules or has no package.json. A warning means it loaded but contains no plugin manifest, so veyyon can see the package and cannot use it.
• plugin:<name>:tools, :hooks, :extension:<path>: an entry point the manifest names and the package does not contain.
• plugin:<name>:feature:<feature>: a feature you enabled that the plugin’s manifest does not define, usually because the plugin dropped it in an update. A warning, since the plugin still works.
• orphan:<name>: a plugin your config enables that is not installed. A warning, since your config is intact and only the package is gone.
• plugin_config, installed_registry: reported only when one of those files cannot be read. doctor continues and reports the rest, so one unreadable file does not cost you the whole report.

--fix repairs what can be repaired without a decision: it runs an install for a missing package, drops an orphaned config entry, and removes an enabled feature the manifest does not define. A check that was repaired is reported. Everything else is left for you, because the remedy depends on what you meant.

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
$ veyyon plugin marketplace add https://github.com/owner/repo

List Marketplaces

List all configured marketplaces and their sources.

$ veyyon plugin marketplace list

Update Marketplaces

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

$ veyyon plugin marketplace update
$ veyyon plugin marketplace update debug

Remove a Marketplace

Remove a configured marketplace by name.

$ veyyon plugin marketplace remove debug

The plugin marketplace subcommands print human-readable output only; --json has no effect on them.

TUI Integration

Slash Commands

• /plugins: Lists installed npm and link plugins.
• /extensions: Opens the Extension Control Center dashboard, which shows plugin-provided skills, tools, and hooks alongside everything else that is loaded.

The Plugins tab of /settings lists installed npm and marketplace plugins and toggles each one on or off. Browsing and installing happen through the veyyon plugin CLI.

Registry Files

Marketplace and plugin state is not kept in config.yml. Two JSON registries, managed by the veyyon plugin CLI (and the /settings Plugins tab for the enabled toggle; edit through those, not by hand):

• marketplaces.json (~/.veyyon/profiles/<profile>/marketplaces.json, the profile root beside agent/ and plugins/): which catalogs you have added. Each entry records the marketplace name, sourceType, sourceUri, catalogPath, and added/updated timestamps.
• installed_plugins.json (under the plugins dir): which plugins are installed. Each entry is keyed <plugin_name>@<marketplace_name> and records the install scope (user or project), installPath, version, install/update timestamps, the source git commit, and an enabled toggle.

The one plugin-related key that does live in config.yml is marketplace.autoUpdate, which controls the startup update check. It runs in the background, so it never delays the first paint, and it takes one of three values:

• notify (the default) refreshes any marketplace catalog older than a day, compares your installed versions against it, and prints one line with how many updates are available. Install them with veyyon plugin upgrade (all) or veyyon plugin upgrade <name>@<marketplace>.
• auto does the same check and installs the updates itself, then prints one line with how many landed. The running session keeps the versions it loaded at startup, so restart to use the new ones.
• off skips the check entirely and contacts no marketplace.

A check that fails, usually because you are offline, is written to the log and does not interrupt the session.

Related recipes

Plugins are installed through the veyyon plugin CLI above, there is no model-facing plugin-install tool. For task-shaped recipes that combine plugins with MCP and skills, see Task guides.

Extensions

Primary guide for authoring runtime extensions in packages/coding-agent.

Extension runtime modules:

• src/extensibility/extensions/types.ts
• src/extensibility/extensions/runner.ts
• src/extensibility/extensions/wrapper.ts
• src/extensibility/extensions/index.ts
• src/modes/controllers/extension-ui-controller.ts

For discovery paths and filesystem loading rules, see extension-loading.md.

For packaged user-facing extension CLIs/features such as packages/swarm-extension, see user-facing-packages.md.

What an extension is

An extension is a TS/JS module exporting a default factory:

import type { ExtensionAPI } from "@veyyon/coding-agent";

export default function myExtension(pi: ExtensionAPI) {
  // register handlers/tools/commands/renderers
}

Extensions can combine all of the following in one module:

• event handlers (pi.on(...))
• LLM-callable tools (pi.registerTool(...))
• slash commands (pi.registerCommand(...))
• keyboard shortcuts and flags
• custom message rendering
• session/message injection APIs (sendMessage, sendUserMessage, appendEntry)

Runtime model

1. Extensions are imported and their factory functions run.
2. During that load phase, registration methods are valid; runtime action methods are not yet initialized.
3. ExtensionRunner.initialize(...) wires live actions/contexts for the active mode.
4. Session/agent/tool lifecycle events are emitted to handlers.
5. Every tool execution is wrapped with extension interception (tool_call / tool_result).

Extension lifecycle (simplified)

load paths
   │
   ▼
import module + run factory (registration only)
   │
   ▼
ExtensionRunner.initialize(mode/session/tool registry)
   │
   ├─ emit session/agent events to handlers
   ├─ wrap tool execution (tool_call/tool_result)
   └─ expose runtime actions (sendMessage, setActiveTools, ...)

Important constraint from loader.ts:

• calling action methods like pi.sendMessage() during extension load throws ExtensionRuntimeNotInitializedError
• register first; perform runtime behavior from events/commands/tools

Quick start

import type { ExtensionAPI } from "@veyyon/coding-agent";

export default function (pi: ExtensionAPI) {
  const { z } = pi.zod;

  pi.setLabel("Safety + Utilities");

  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify(`Extension loaded in ${ctx.cwd}`, "info");
  });

  pi.on("tool_call", async (event) => {
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      return { block: true, reason: "Blocked by extension policy" };
    }
  });

  pi.registerTool({
    name: "hello_extension",
    label: "Hello Extension",
    description: "Return a greeting",
    parameters: z.object({ name: z.string() }),
    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
      return {
        content: [{ type: "text", text: `Hello, ${params.name}` }],
        details: { greeted: params.name },
      };
    },
  });

  pi.registerCommand("hello-ext", {
    description: "Show queue state",
    handler: async (_args, ctx) => {
      ctx.ui.notify(`pending=${ctx.hasPendingMessages()}`, "info");
    },
  });
}

Extension API surfaces

1) Registration and actions (ExtensionAPI)

Core methods:

• on(event, handler)
• registerTool, registerCommand, registerShortcut, registerFlag
• registerMessageRenderer, registerAssistantThinkingRenderer
• setLabel, getFlag
• sendMessage, sendUserMessage, appendEntry, exec
• getActiveTools, getAllTools, setActiveTools
• getCommands
• getSessionName, setSessionName
• setModel, getThinkingLevel, setThinkingLevel
• registerProvider
• events (shared event bus)

In interactive mode, input handlers run before the built-in first-message auto-title check. Extensions that call await pi.setSessionName(...) from input can set the persisted session name and prevent the default auto-generated title from running for that session.

Also exposed:

• pi.logger
• pi.typebox (zod-backed compatibility shim for legacy TypeBox-style schemas)
• pi.zod (injected zod/v4 module: canonical for tool parameter schemas)
• pi.pi (package exports)

Message delivery semantics

pi.sendMessage(message, options) supports:

• deliverAs: "steer" (default): interrupts current run
• deliverAs: "followUp": queued to run after current run
• deliverAs: "nextTurn": stored and injected on the next user prompt
• triggerTurn: true: starts a turn when idle (also honored with deliverAs: "nextTurn": idle prompts immediately; while streaming the queued message schedules an internal continuation)

pi.sendUserMessage(content, { deliverAs }) always goes through prompt flow. Omit deliverAs to start a normal prompt when idle; while streaming, omitted deliverAs queues the message as a steer. Set deliverAs: "followUp" to wait until the current run finishes.

2) Handler context (ExtensionContext)

Handlers and tool execute receive ctx with:

• ui
• hasUI
• cwd
• sessionManager (read-only)
• modelRegistry, model
• models (read-only model query: see below)
• getContextUsage()
• compact(...)
• isIdle(), hasPendingMessages(), abort()
• shutdown()
• getSystemPrompt()
• memory (optional structured memory runtime: status/search/save across the configured backend)

Model selection (ctx.models)

ctx.models is a read-only facade for picking and comparing models the same way core does:

• list(): authenticated models available this session.
• current(): the live session model (read lazily, so it reflects /model switches).
• resolve(spec): a model string (provider/id, bare id) or role alias (@slow, a configured role) → Model, honoring the same settings-backed aliases and match preferences as --model. Returns undefined when nothing matches.
• family(model): an opaque lineage token for “same family?” checks (Claude point releases share a token; Claude and GPT differ). Compare it; don’t persist it (the vocabulary tracks new releases).

// Pick a model from a different family than the current one (e.g. a cross-family reviewer).
const current = ctx.models.current();
const contrasting = ctx.models
  .list()
  .find(m => current && ctx.models.family(m) !== ctx.models.family(current));

3) Command context (ExtensionCommandContext)

Command handlers additionally get:

• waitForIdle()
• newSession(...)
• switchSession(...)
• branch(entryId)
• navigateTree(targetId, { summarize })
• reload()

Use command context for session-control flows; these methods are intentionally separated from general event handlers.

Event surface (current names and behavior)

Canonical event unions and payload types are in types.ts.

Session lifecycle

• session_start
• session_before_switch / session_switch
• session_before_branch / session_branch
• session_before_compact / session_compacting / session_compact
• session_before_tree / session_tree
• session_shutdown

Cancelable pre-events:

• session_before_switch → { cancel?: boolean }
• session_before_branch → { cancel?: boolean; skipConversationRestore?: boolean }
• session_before_compact → { cancel?: boolean; compaction?: CompactionResult }
• session_before_tree → { cancel?: boolean; summary?: { summary: string; details?: unknown } }

Prompt and turn lifecycle

• input
• before_agent_start: receives the base system prompt. Memory context (recalled memories, mental models) is not part of it: that content is delivered as a message on the turn instead, because changing the system prompt mid-session throws away the provider’s cache prefix.
• before_provider_request (may replace provider request payload)
• after_provider_response
• context
• agent_start / agent_end: agent loop lifecycle notification; agent_end remains notification-only
• session_stop: main-session stop hook, awaited before settle; may continue with { continue: true, additionalContext } or { decision: "block", reason }; capped at 8 consecutive continuations and never fires for task/subagent sessions
• turn_start / turn_end
• message_start / message_update / message_end

Tool lifecycle

• tool_call (pre-exec, may block)
• tool_result (post-exec, may patch content/details/isError)
• tool_execution_start / tool_execution_update / tool_execution_end (observability)
• tool_approval_requested / tool_approval_resolved (observability; emitted by wrapper.ts only when a tool requires approval and an approval handler is registered)

tool_result is middleware-style: handlers run in extension order and each sees prior modifications.

Reliability/runtime signals

• auto_compaction_start / auto_compaction_end
• auto_retry_start / auto_retry_end
• ttsr_triggered
• todo_reminder
• goal_updated
• credential_disabled

User command interception

• user_bash (override with { result })
• user_python (override with { result })

resources_discover

resources_discover exists in extension types and ExtensionRunner. Current runtime note: ExtensionRunner.emitResourcesDiscover(...) is implemented, but there are no AgentSession callsites invoking it in the current codebase.

Tool authoring details

registerTool uses ToolDefinition from types.ts.

Current execute signature:

execute(
	toolCallId,
	params,
	signal,
	onUpdate,
	ctx,
): Promise<AgentToolResult>

A custom tool (a file under tools/, documented in ../using/custom-tools.md) takes the same five arguments in a different order, with the signal last: execute(toolCallId, params, onUpdate, ctx, signal). Copying one into the other place raises no error at the call site and none at runtime either: the arguments still arrive, so ctx is the update callback and the first ctx.sessionManager you touch is undefined.

Template:

const { z } = pi.zod;

pi.registerTool({
  name: "my_tool",
  label: "My Tool",
  description: "...",
  parameters: z.object({}),
  hidden: false,
  defaultInactive: false,
  deferrable: false,
  async execute(_id, _params, signal, onUpdate, ctx) {
    if (signal?.aborted) {
      return { content: [{ type: "text", text: "Cancelled" }] };
    }
    onUpdate?.({ content: [{ type: "text", text: "Working..." }] });
    return { content: [{ type: "text", text: "Done" }], details: {} };
  },
  onSession(event, ctx) {
    // reason: start|switch|branch|tree|shutdown
  },
  renderCall(args, options, theme) {
    // optional TUI render
  },
  renderResult(result, options, theme, args) {
    // optional TUI render
  },
});

tool_call/tool_result intercept all tools once the registry is wrapped in sdk.ts, including built-ins and extension/custom tools. ToolDefinition also supports optional hidden, defaultInactive, deferrable, approval, mcpServerName, mcpToolName, renderCall, and renderResult fields.

UI integration points

ctx.ui implements the ExtensionUIContext interface. Support differs by mode.

Interactive mode (extension-ui-controller.ts)

Supported:

• dialogs: select, confirm, input, editor
• input editing: setEditorText, getEditorText, pasteToEditor, editor
• autocomplete stacking: addAutocompleteProvider(factory) wraps the built-in editor provider (factories apply in registration order and re-apply on every slash-command refresh)
• terminal title and working message (setTitle, setWorkingMessage)
• notifications/status/editor text/terminal input/custom overlays
• theme listing/loading by name (setTheme supports string names)
• tools expanded toggle

Current no-op methods in this controller:

• setFooter
• setHeader

setEditorComponent is wired to the live editor (ctx.setEditorComponent(factory)). setWidget renders real widget components above or below the editor via setHookWidget(...) (placement: "aboveEditor" | "belowEditor"; string-array content capped at 10 lines).

RPC mode (rpc-mode.ts)

ctx.ui is backed by RPC extension_ui_request events:

• dialog methods (select, confirm, input, editor) round-trip to client responses
• fire-and-forget methods emit requests (notify, setStatus, setWidget for string arrays, setEditorText; setTitle emits only when VEYYON_RPC_EMIT_TITLE=1)

Unsupported/no-op in RPC implementation:

• onTerminalInput
• custom
• setFooter, setHeader, setEditorComponent, addAutocompleteProvider
• setWorkingMessage
• theme switching/loading (setTheme returns failure)
• tool expansion controls are inert

Print/headless/subagent paths

When no UI context is supplied to runner init, ctx.hasUI is false and methods are no-op/default-returning.

ACP mode

ACP installs an elicitation-bridged UI context (createAcpExtensionUiContext in acp-agent.ts). ctx.hasUI is true while only select/confirm/input round-trip (as ACP elicitations; defaults are returned when the client lacks the elicitation.form capability). The non-elicitation surface (widgets, editor, theming, terminal input, autocomplete stacking) is stubbed no-op.

Session and state patterns

For durable extension state:

1. Persist with pi.appendEntry(customType, data).
2. Rebuild state from ctx.sessionManager.getBranch() on session_start, session_branch, session_tree.
3. Keep tool result details structured when state should be visible/reconstructible from tool result history.

Example reconstruction pattern:

pi.on("session_start", async (_event, ctx) => {
  let latest;
  for (const entry of ctx.sessionManager.getBranch()) {
    if (entry.type === "custom" && entry.customType === "my-state") {
      latest = entry.data;
    }
  }
  // restore from latest
});

Rendering extension points

Custom message renderer

pi.registerMessageRenderer("my-type", (message, { expanded }, theme) => {
  // return pi-tui Component
});

Used by interactive rendering when custom messages are displayed.

Return undefined to decline and let veyyon draw its built-in card for that message. If your renderer throws instead, veyyon draws the built-in card and adds a notice row to it:

✗ custom message "my-type" renderer threw: cannot read properties of undefined — showing the default card; fix or remove the renderer

The failure is also written to the log, so a renderer that breaks only on certain payloads is visible in the transcript rather than silently replaced.

Assistant thinking renderer

import { Container, Text } from "@veyyon/tui";

pi.registerAssistantThinkingRenderer((context, theme) => {
  const container = new Container();
  container.addChild(new Text(theme.fg("dim", `thinking chars: ${context.text.length}`), 1, 0));
  return container;
});

Used by interactive rendering to add display-only supplemental UI below each visible assistant thinking block. The renderer receives the already-visible thinking text, content/thinking indexes, theme, and a requestRender() callback for async renderers. All registered renderers that return a component are appended in registration order. Renderers must not mutate messages; the original thinking block remains the provider/session source of truth.

Tool call/result renderer

Provide renderCall / renderResult on registerTool definitions for custom tool visualization in TUI.

Constraints and pitfalls

• Runtime actions are unavailable during extension load.
• tool_call errors block execution (fail-closed).
• Command name conflicts with built-ins are skipped with diagnostics.
• Reserved shortcuts are ignored (ctrl+c, ctrl+d, ctrl+z, ctrl+k, ctrl+p, ctrl+l, ctrl+o, ctrl+t, ctrl+g, ctrl+q, alt+m, shift+tab, shift+ctrl+p, alt+enter, escape, enter).
• Treat ctx.reload() as terminal for the current command handler frame.

Extensions vs hooks vs custom-tools

Use the right surface:

• Extensions (src/extensibility/extensions/*): unified system (events + tools + commands + renderers + provider registration).
• Hooks (src/extensibility/hooks/*): separate legacy event API.
• Custom-tools (src/extensibility/custom-tools/*): tool-focused modules; when loaded alongside extensions they are adapted and still pass through extension interception wrappers.

If you need one package that owns policy, tools, command UX, and rendering together, use extensions.

Extensions authoring

name: authoring-extensions description: Use when creating a new veyyon extension. Covers ExtensionAPI, factory signature, tool/command/event registration, and local-dev testing.

Authoring Extensions

Extensions are the primary way to add capabilities to Veyyon. A single extension module can register tools the LLM can call, slash commands users can invoke, and event handlers that run throughout the session lifecycle, all from one TypeScript file.

Minimum viable extension

import type { ExtensionAPI } from "@veyyon/coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify("My extension loaded!", "info");
  });
}

That is a working extension. Drop it into ~/.veyyon/profiles/default/agent/extensions/hello.ts (or the active profile’s agent dir) and restart veyyon to see the notification.

Full example

The following extension registers a slash command, a tool, and a session-start hook:

import type { ExtensionAPI } from "@veyyon/coding-agent";

export default function myExtension(pi: ExtensionAPI) {
  const z = pi.zod;

  // Runs once when the session loads
  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify(`Session ready in ${ctx.cwd}`, "info");
  });

  // Slash command: /greet
  pi.registerCommand("greet", {
    description: "Send a greeting into the conversation",
    handler: async (args, ctx) => {
      const name = args.trim() || "world";
      pi.sendMessage(
        {
          customType: "greeting",
          content: `Hello, ${name}!`,
          display: true,
          attribution: "user",
        },
        { triggerTurn: false }
      );
      ctx.ui.notify(`Greeted ${name}`, "info");
    },
  });

  // LLM-callable tool
  pi.registerTool({
    name: "word_count",
    label: "Word Count",
    description: "Count the words in a string",
    parameters: z.object({
      text: z.string().describe("Text to count"),
    }),
    async execute(_id, params, _signal, _onUpdate, _ctx) {
      const count = params.text.split(/\s+/).filter(Boolean).length;
      return {
        content: [{ type: "text", text: String(count) }],
        details: { count },
      };
    },
  });
}

Discovery paths

veyyon loads extension modules from these sources:

1. The active profile’s native locations, discovered through the capability system:

   • ~/.veyyon/profiles/default/agent/extensions/
   • legacy extension paths listed in ~/.veyyon/profiles/default/agent/settings.json#extensions

   A working tree’s .veyyon/extensions/ or .veyyon/settings.json#extensions is not read: a checked-in file must not hand the agent executable modules.

2. Installed plugins under ~/.veyyon/profiles/default/plugins/node_modules (veyyon plugin install npm/git/marketplace specs, or veyyon plugin link) via their veyyon.extensions manifests (legacy omp.extensions/pi.extensions still accepted). Marketplace installs are symlinked into the same node_modules tree, so their veyyon.extensions manifests load extension modules too.

3. Explicit configured paths passed by the CLI (veyyon --extension ./my-ext.ts, also -e; --hook is treated as an alias) and by the extensions: setting in config.

The runtime de-duplicates by resolved absolute path, first seen wins.

When a path points to a directory, veyyon resolves the entry point in this order:

1. package.json with veyyon.extensions (legacy omp.extensions / pi.extensions) field
2. index.ts
3. index.js

When scanning an extensions/ directory, veyyon also loads direct *.ts/*.js files and one-level subdirectories that have index.ts, index.js, or a manifest.

Extension packages can also bundle sibling capability directories. When a package is loaded through extensions: or --extension/-e, the veyyon-plugins provider discovers its skills/, hooks/pre|post/, tools/, commands/, rules/, prompts/, and .mcp.json.

package.json manifest

To package an extension as an installable plugin, add a veyyon field to package.json (legacy omp / pi keys still load; veyyon wins when several are present):

{
  "name": "my-veyyon-extension",
  "veyyon": {
    "extensions": ["./src/main.ts"]
  }
}

The legacy pi key is also accepted for backwards compatibility:

{
  "pi": {
    "extensions": ["./index.ts"]
  }
}

Multiple entry points are supported:

{
  "veyyon": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"]
  }
}

Registering commands

pi.registerCommand("my-cmd", {
  description: "What the command does",
  handler: async (args, ctx) => {
    // args: everything the user typed after /my-cmd
    // ctx: ExtensionCommandContext, includes ctx.ui, ctx.cwd, session controls
    ctx.ui.notify("Running!", "info");
    await ctx.waitForIdle();
    await ctx.newSession();
  },
});

ExtensionCommandContext session-control methods (safe to call from commands only):

Registering tools

Tools are called by the LLM. Parameters use Zod schemas, available at pi.zod:

const z = pi.zod;

pi.registerTool({
  name: "search_notes",           // snake_case, unique
  label: "Search Notes",          // human-readable label for TUI
  description: "Full-text search through project notes",
  parameters: z.object({
    query: z.string().describe("Search query"),
    limit: z.number().default(10).describe("Max results").optional(),
  }),
  async execute(toolCallId, params, signal, onUpdate, ctx) {
    if (signal?.aborted) {
      return { content: [{ type: "text", text: "Cancelled" }] };
    }
    onUpdate?.({ content: [{ type: "text", text: "Searching..." }] });
    // ... do work ...
    return {
      content: [{ type: "text", text: `Found N results for "${params.query}"` }],
      details: { query: params.query, count: 0 },
    };
  },
});

Subscribing to events

pi.on("tool_call", async (event, ctx) => {
  // event.toolName, event.input, event.toolCallId
  if (event.toolName !== "bash") return;

  const command = String((event.input as { command?: unknown }).command ?? "");
  if (command.includes("rm -rf /")) {
    return { block: true, reason: "Blocked by safety policy" };
  }
});

pi.on("turn_end", async (_event, ctx) => {
  ctx.ui.setStatus("tokens", `~${ctx.getContextUsage()?.tokens ?? "?"} tokens`);
});

pi.on("session_stop", async (event) => {
  if (event.stop_hook_active) return;
  return { continue: true, additionalContext: `Review final status after turn ${event.turn_id}.` };
});

Full event catalog: see extension authoring guide.

Extension vs hook: when to use which

Extensions are a strict superset of hooks. New authoring should use ExtensionAPI.

Debugging

veyyon writes structured logs to a rotating file under the active profile logs dir (~/.veyyon/profiles/<name>/logs/; debug level is always on; nothing is written to the console, which would corrupt the TUI). Tail today’s log to see extension load diagnostics:

tail -f ~/.veyyon/profiles/default/logs/veyyon.$(date +%F).log

Failed extension loads are logged with their path and error. Loaded extensions may also emit their own debug logs via pi.logger.

To temporarily disable a specific extension module by name without removing the file:

# ~/.veyyon/profiles/default/agent/config.yml
disabledExtensions:
  - extension-module:my-ext

The derived name is the filename stem (or directory name for index.ts-style entries): /path/to/my-ext.ts → my-ext.

Important constraints

• Do not call runtime actions during load. Methods like pi.sendMessage() throw ExtensionRuntimeNotInitializedError if called synchronously during module evaluation (before a session is active). Register handlers/tools/commands during load; perform runtime actions only from event handlers, tools, or commands.
• tool_call errors are fail-closed. If a tool_call handler throws, the tool is blocked.
• Command names must not clash with built-ins. Conflicts are skipped with a diagnostic log.
• Reserved shortcuts are ignored (ctrl+c, ctrl+d, ctrl+z, ctrl+k, ctrl+p, ctrl+l, ctrl+o, ctrl+t, ctrl+g, ctrl+q, alt+m, shift+tab, shift+ctrl+p, alt+enter, escape, enter).

Further reading

• docs/handbook/src/features/extensions.md: runtime internals and full API surface reference
• docs/internal/extension-loading.md: detailed path resolution rules
• docs/handbook/src/reference/hooks.md: hook subsystem internals
• packages/coding-agent/examples/hello-extension/: complete working example

Custom Tools

Custom tools are model-callable functions that plug into the same tool execution pipeline as built-in tools.

A custom tool is a TypeScript/JavaScript module that exports a factory. The factory receives a host API (CustomToolAPI) and returns one tool or an array of tools.

What this is (and is not)

• Custom tool: callable by the model during a turn (execute + Zod parameter schema).
• Extension: lifecycle/event framework that can register tools and intercept/modify events.
• Hook: TypeScript module that registers handlers with pi.on(...) (same event bus as extensions; --hook aliases --extension).
• Skill: static guidance/context package, not executable tool code.

If you need the model to call code directly, use a custom tool.

Integration paths in current code

There are two active integration styles:

1. SDK-provided custom tools (options.customTools)

   • Wrapped into agent tools via CustomToolAdapter or extension wrappers.
   • Always included in the initial active tool set in SDK bootstrap.

2. Filesystem-discovered modules via loader API (discoverAndLoadCustomTools / loadCustomTools)

   • Exposed as library APIs in src/extensibility/custom-tools/loader.ts.
   • Host code can call these to discover and load tool modules from config/provider/plugin paths.

Model tool call flow

LLM tool call
   │
   ▼
Tool registry (built-ins + custom tool adapters)
   │
   ▼
CustomTool.execute(toolCallId, params, onUpdate, ctx, signal)
   │
   ├─ onUpdate(...)  -> streamed partial result
   └─ return result  -> final tool content/details

Discovery locations (loader API)

discoverAndLoadCustomTools(configuredPaths, cwd, builtInToolNames) merges:

1. Capability providers (toolCapability), all user-level (a working tree never contributes tools):
   • Native Veyyon config (~/.veyyon/profiles/<name>/agent/tools)
   • Claude config (~/.claude/tools)
   • Codex config (~/.codex/tools)
   • Claude marketplace plugin cache provider
2. Installed plugin manifests (~/.veyyon/profiles/<profile>/plugins/node_modules/* via plugin loader; a project root <anchor>/.veyyon/plugins is enumerated the same way)
3. Explicit configured paths passed to the loader

Important behavior

• Duplicate resolved paths are deduplicated.
• Tool name conflicts are rejected against built-ins and already-loaded custom tools.
• .md and .json files are discovered as tool metadata by some providers, but the executable module loader rejects them as runnable tools.
• Relative configured paths are resolved from cwd; ~ is expanded.

Module contract

A custom tool module must export a function (default export preferred):

import type { CustomToolFactory } from "@veyyon/coding-agent";

const factory: CustomToolFactory = (pi) => ({
  name: "repo_stats",
  label: "Repo Stats",
  description: "Counts tracked TypeScript files",
  parameters: pi.zod.object({
    glob: pi.zod.string().optional().default("**/*.ts"),
  }),

  async execute(toolCallId, params, onUpdate, ctx, signal) {
    onUpdate?.({
      content: [{ type: "text", text: "Scanning files..." }],
      details: { phase: "scan" },
    });

    const result = await pi.exec(
      "git",
      ["ls-files", params.glob ?? "**/*.ts"],
      { signal, cwd: pi.cwd },
    );
    if (result.killed) {
      throw new Error("Scan was cancelled");
    }
    if (result.code !== 0) {
      throw new Error(result.stderr || "git ls-files failed");
    }

    const files = result.stdout.split("\n").filter(Boolean);
    return {
      content: [{ type: "text", text: `Found ${files.length} files` }],
      details: { count: files.length, sample: files.slice(0, 10) },
    };
  },

  onSession(event) {
    if (event.reason === "shutdown") {
      // cleanup resources if needed
    }
  },
});

export default factory;

Schemas are authored with Zod (pi.zod) and flow through the shared validation/wire pipeline.

Factory return type:

• CustomTool
• CustomTool[]
• Promise<CustomTool | CustomTool[]>

API surface passed to factories (CustomToolAPI)

From types.ts and loader.ts:

• cwd: host working directory
• exec(command, args, options?): process execution helper
• ui: UI context (can be no-op in headless modes)
• hasUI: false in non-interactive flows
• logger: shared file logger
• typebox: self-contained compatibility shim for legacy TypeBox-style schemas (legacy/compat, prefer arktype or zod for new tools)
• zod: injected zod/v4 module (canonical for new schemas)
• pi: injected @veyyon/coding-agent exports
• pushPendingAction(action): register a preview action for hidden resolve tool (docs/internal/resolve-tool-runtime.md) Loader starts with a no-op UI context and requires host code to call setUIContext(...) when real UI is ready.

Execution contract and typing

CustomTool.execute signature:

execute(toolCallId, params, onUpdate, ctx, signal);

• params is statically typed from your Zod/TypeBox schema via Static<TParams>.
• Runtime argument validation happens before execution in the agent loop.
• onUpdate emits partial results for UI streaming.
• ctx includes sessionManager, modelRegistry, current model, isIdle(), hasQueuedMessages(), abort(), and optional settings, fetch, and autoApprove.
• signal carries cancellation.

An extension tool registered with pi.registerTool takes the same five arguments in a different order, with the signal third:

execute(toolCallId, params, signal, onUpdate, ctx);

Use the order that belongs to the API you are writing against. Copying one into the other place raises no error at the call site and none at runtime either: the arguments still arrive, so ctx is the update callback and the first ctx.sessionManager you touch is undefined.

CustomToolAdapter bridges this to the agent tool interface and forwards calls in the correct argument order.

Tool definitions may also declare strict, hidden, deferrable, mcpServerName, mcpToolName, approval, and formatApprovalDetails.

How tools are exposed to the model

• Tools are wrapped into AgentTool instances (CustomToolAdapter or extension wrappers).
• They are inserted into the session tool registry by name.
• In SDK bootstrap, custom and extension-registered tools are force-included in the initial active set.
• CLI --tools currently validates only built-in tool names; custom tool inclusion is handled through discovery/registration paths and SDK options.

Rendering hooks

Optional rendering hooks:

• renderCall(args, options, theme)
• renderResult(result, options, theme, args?)

Runtime behavior in TUI:

• If hooks exist, tool output is rendered inside a Box container.
• renderResult receives { expanded, isPartial, spinnerFrame? }.

If a rendering hook throws, veyyon catches it so the session keeps running, and then reports it where your card would have been:

✗ tool "widget" result renderer threw: payload has no rows — showing raw output; fix or remove the renderer

The notice states which hook failed, because renderCall and renderResult fail independently, and it shows what you are looking at instead: the tool label alone for a failed renderCall, the raw text output for a failed renderResult. When there is no raw output to fall back to, it reports that too rather than implying output you cannot see. The failure is also written to the log.

Returning undefined from a hook is different: that is how you decline to draw for a particular call, and it renders the default with no notice.

Session/state handling

Optional onSession(event, ctx) receives session lifecycle events, including:

• start, switch, branch, tree, shutdown
• auto_compaction_start, auto_compaction_end
• auto_retry_start, auto_retry_end
• ttsr_triggered, todo_reminder

Use ctx.sessionManager to reconstruct state from history when branch/session context changes.

Failures and cancellation semantics

Synchronous/async failures

• Throwing (or rejected promises) in execute is treated as tool failure.
• Agent runtime converts failures into tool result messages with isError: true and error text content.
• With extension wrappers, tool_result handlers can further rewrite content/details and even override error status.

Cancellation

• Agent abort propagates through AbortSignal to execute.
• Forward signal to subprocess work (pi.exec(..., { signal })) for cooperative cancellation.
• ctx.abort() lets a tool request abort of the current agent operation.

onSession errors

• onSession errors are caught and logged as warnings; they do not crash the session.

Real constraints to design for

• Tool names must be globally unique in the active registry.
• Prefer deterministic, schema-shaped outputs in details for renderer/state reconstruction.
• Guard UI usage with pi.hasUI.
• Treat .md/.json in tool directories as metadata, not executable modules.

Marketplace plugin system

Discover, install, and manage plugins from Git, local, or catalog sources. Catalog layout is compatible with the Claude Code plugin registry format.

Quick start

veyyon plugin marketplace add anthropics/claude-plugins-official
veyyon plugin install wordpress.com@claude-plugins-official

The interactive /marketplace TUI was removed from Veyyon. Manage marketplaces and marketplace plugins through the veyyon plugin CLI. Inside the TUI, /plugins list shows installed npm/link plugins.

Concepts

A marketplace is a Git repository (or local directory) containing a catalog file at .veyyon-plugin/marketplace.json (preferred) or .claude-plugin/marketplace.json (Claude Code-compatible fallback). The catalog lists available plugins with their sources, descriptions, and metadata.

A plugin is a directory containing Claude/Veyyon plugin content such as skills, commands, agents, hooks, tools, MCP servers, or LSP servers. Extension modules (package.json veyyon.extensions entry points; legacy omp/pi keys still accepted) load from marketplace installs just as they do from npm-installed or veyyon plugin linked plugins, because the install symlinks the cached plugin into the runtime node_modules tree. Plugins are identified by name@marketplace (e.g. code-review@claude-plugins-official).

Scopes: marketplace plugins can be installed at two scopes:

• user (default) – available in all projects under the active profile, stored in ~/.veyyon/profiles/<profile>/plugins/installed_plugins.json (default profile: profiles/default/plugins/)
• project – available only in the active project, stored in the nearest project .veyyon/plugins/installed_plugins.json

Enabled project-scoped installs shadow enabled user-scoped installs of the same plugin. A disabled project install does not shadow the user install.

Commands

Marketplace management:

veyyon plugin marketplace add <source>
veyyon plugin marketplace remove <name>
veyyon plugin marketplace update [name]
veyyon plugin marketplace list

Plugin operations:

veyyon plugin discover [marketplace]
veyyon plugin install [--force] [--scope user|project] name@marketplace
veyyon plugin uninstall [--scope user|project] name@marketplace
veyyon plugin upgrade [--scope user|project] [name@marketplace]
veyyon plugin enable [--scope user|project] name@marketplace
veyyon plugin disable [--scope user|project] name@marketplace

Marketplace sources

When you run veyyon plugin marketplace add <source>, the system classifies the source:

Git and local sources must contain a catalog at .veyyon-plugin/marketplace.json (preferred) or .claude-plugin/marketplace.json (Claude Code-compatible fallback). Direct catalog URLs cache only the JSON catalog; plugins in URL-sourced catalogs cannot use relative string sources like "./plugins/foo".

Catalog format (marketplace.json)

A marketplace catalog lives at .veyyon-plugin/marketplace.json in the repository root. When veyyon is the only intended consumer, prefer this path. To remain Claude Code-compatible (veyyon loads the same shape from either path), publish at .claude-plugin/marketplace.json instead, veyyon uses it as a fallback when .veyyon-plugin/marketplace.json is absent. A repository may ship both: veyyon reads the .veyyon-plugin/ copy, Claude Code reads the .claude-plugin/ copy. Same catalog format either way:

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "my-marketplace",
  "owner": {
    "name": "Your Name",
    "email": "[email protected]"
  },
  "metadata": {
    "description": "A collection of plugins",
    "version": "1.0.0",
    "pluginRoot": "plugins"
  },
  "plugins": [
    {
      "name": "my-plugin",
      "description": "What this plugin does",
      "source": "./my-plugin",
      "category": "development",
      "homepage": "https://github.com/you/my-plugin"
    }
  ]
}

Required fields

Top-level metadata.description, metadata.version, and metadata.pluginRoot are optional. When metadata.pluginRoot is set, it is prepended to relative plugin source paths.

Plugin entry fields

Plugin source formats

The source field supports these formats. String sources must start with ./ and are resolved inside the marketplace root, after optional metadata.pluginRoot is prepended:

Relative path (within the marketplace repo):

"source": "./my-plugin"

Git repository URL:

"source": {
  "source": "url",
  "url": "https://github.com/org/repo.git",
  "sha": "abc123..."
}

GitHub shorthand:

"source": {
  "source": "github",
  "repo": "org/repo",
  "ref": "main",
  "sha": "abc123..."
}

Git subdirectory (monorepo):

"source": {
  "source": "git-subdir",
  "url": "https://github.com/org/monorepo.git",
  "path": "plugins/my-plugin",
  "ref": "main",
  "sha": "abc123..."
}

npm package (parsed but not installable yet):

"source": {
  "source": "npm",
  "package": "@scope/my-plugin",
  "version": "1.0.0"
}

Current installer behavior rejects npm marketplace sources with npm plugin sources are not yet supported; use relative, GitHub, URL, or git-subdir sources.

On-disk layout

~/.veyyon/
  marketplaces.json              # Registry of added marketplaces
  profiles/<profile>/plugins/
    installed_plugins.json       # User-scoped marketplace plugins (version: 2)
    cache/
      marketplaces/<name>/       # Cached marketplace clone/catalog
      plugins/<marketplace>___<plugin>___<version>/  # Cached plugin directories

<project>/.veyyon/
  plugins/
    installed_plugins.json       # Project-scoped marketplace plugins (version: 2)

Naming rules

Marketplace and plugin names must:

• Start and end with a lowercase letter or digit
• Contain only lowercase letters, digits, hyphens, and dots
• Be at most 64 characters

Plugin IDs (name@marketplace) must be at most 128 characters total.

Valid examples: my-plugin, code-review, wordpress.com, ai-firstify Invalid examples: -bad, bad-, .bad, Bad, under_score

Marketplace authoring

name: authoring-marketplaces description: Use when creating a new veyyon marketplace. Covers marketplace.json schema, source types, install commands, and publishing.

Authoring Marketplaces

A marketplace is a Git repository (or local directory) that contains a catalog file at either .veyyon-plugin/marketplace.json (preferred for veyyon-specific catalogs) or .claude-plugin/marketplace.json (Claude Code-compatible; used as the fallback). Anyone can author one. Users add it with veyyon plugin marketplace add owner/repo and then install individual plugins from it.

Minimum viable marketplace

my-marketplace/
  .claude-plugin/
    marketplace.json
  plugins/
    my-plugin/
      skills/
        my-skill/
          SKILL.md

{
  "name": "my-marketplace",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "my-plugin",
      "description": "What it does",
      "source": "./plugins/my-plugin"
    }
  ]
}

Push to GitHub. Users install with:

veyyon plugin marketplace add your-github-username/my-marketplace
veyyon plugin install my-plugin@my-marketplace

marketplace.json schema

The catalog file lives at either .veyyon-plugin/marketplace.json or .claude-plugin/marketplace.json in the repository root. veyyon prefers the .veyyon-plugin/ path and falls back to the Claude path; a repository may publish both to expose tool-specific catalogs from a single source tree.

Top-level fields

Plugin entry fields

Full catalog example

{
  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  "name": "acme-plugins",
  "owner": {
    "name": "Acme Corp",
    "email": "[email protected]"
  },
  "metadata": {
    "description": "Official Acme plugins for Veyyon"
  },
  "plugins": [
    {
      "name": "acme-linter",
      "description": "Enforce Acme coding standards",
      "category": "development",
      "source": "./plugins/linter"
    },
    {
      "name": "acme-deploy",
      "description": "One-command deploy to Acme cloud",
      "category": "devops",
      "source": {
        "source": "github",
        "repo": "acme-corp/veyyon-deploy-plugin",
        "ref": "main"
      }
    }
  ]
}

Plugin source types

1. Relative path string

Points to a subdirectory inside the marketplace repository itself. Must start with ./.

"source": "./plugins/my-plugin"

The path is resolved relative to the marketplace repository root. Path traversal outside the repo root is rejected.

Use metadata.pluginRoot to avoid repeating a common prefix:

{
  "metadata": { "pluginRoot": "./plugins" },
  "plugins": [
    { "name": "plugin-a", "source": "./plugin-a" },
    { "name": "plugin-b", "source": "./plugin-b" }
  ]
}

2. Git URL

A full Git repository URL. Optionally pin to a branch/tag (ref) or exact commit (sha):

"source": {
  "source": "url",
  "url": "https://github.com/org/my-plugin.git",
  "ref": "main",
  "sha": "a1b2c3d4..."
}

3. GitHub shorthand

Shorthand for GitHub repositories. Functionally equivalent to a Git URL but more concise:

"source": {
  "source": "github",
  "repo": "org/my-plugin",
  "ref": "v2.1.0",
  "sha": "a1b2c3d4..."
}

4. Git subdirectory (monorepo)

For plugins living inside a subdirectory of a larger repository. url accepts a full HTTPS URL or a GitHub owner/repo shorthand:

"source": {
  "source": "git-subdir",
  "url": "https://github.com/org/monorepo.git",
  "path": "packages/my-plugin",
  "ref": "main",
  "sha": "a1b2c3d4..."
}

The path must resolve inside the cloned repository, directory escape is rejected.

5. NPM package

Declares the plugin as an npm package. version is optional:

"source": {
  "source": "npm",
  "package": "@acme/veyyon-plugin",
  "version": "1.2.0"
}

Note: npm plugin sources are declared in the schema but installation support is not yet fully implemented. Use Git-based sources for plugins that need to work today.

Plugin structure

A plugin directory (regardless of source type) ships its content in conventional locations, all optional:

my-plugin/
  skills/<name>/SKILL.md   ← skills
  commands/*.md            ← slash commands
  agents/*.md              ← subagent definitions
  hooks/pre/, hooks/post/  ← hooks
  tools/                   ← custom tools
  .mcp.json                ← MCP server definitions
  package.json             ← optional; its version is a fallback when the catalog entry has no version
  README.md                ← recommended: description + usage

Note: extension modules declared via package.json veyyon.extensions (legacy omp/pi) load from marketplace installs exactly as they do from npm-installed or veyyon plugin linked plugins: the install symlinks the cached plugin into the runtime node_modules tree that the extension loader enumerates.

Install command

veyyon plugin install name@marketplace-name
veyyon plugin install --force name@marketplace-name     # reinstall
veyyon plugin install --scope project name@marketplace  # project-scoped

Add the marketplace first:

veyyon plugin marketplace add owner/repo
veyyon plugin install name@marketplace-name

Scope behavior:

• user (default): installed in ~/.veyyon/profiles/default/plugins/installed_plugins.json, available in all projects
• project: installed in <project>/.veyyon/plugins/installed_plugins.json, available only in that project

Project-scoped installs shadow user-scoped installs of the same plugin name.

Naming rules

Marketplace names and plugin names must:

• Contain only lowercase letters, digits, hyphens (-), and dots (.)
• Start and end with a lowercase letter or digit
• Be at most 64 characters

Plugin IDs (name@marketplace) must be at most 128 characters total.

Valid: my-plugin, code-review, acme.tools, ai-v2 Invalid: -bad-start, bad-end-, .dot-start, Under_score, HAS_CAPS

Publishing workflow

1. Create marketplace.json at .veyyon-plugin/marketplace.json (veyyon-only) or .claude-plugin/marketplace.json (shared with Claude Code) in a new Git repo.
2. Add plugin entries pointing to subdirectories (or external sources).
3. Push to GitHub.
4. Share the owner/repo string. Users add it with veyyon plugin marketplace add owner/repo.
5. When you update the catalog, users run veyyon plugin marketplace update your-marketplace-name to pull the latest.

To test locally before publishing:

veyyon plugin marketplace add ./path/to/my-marketplace

Local path sources also accept ~/ and absolute paths.

Further reading

• docs/handbook/src/features/marketplace.md: marketplace system internals, on-disk layout, command reference
• docs/handbook/src/features/extensions-authoring.md: how to author the extension modules inside plugins
• packages/coding-agent/examples/mini-marketplace/: minimal working marketplace example

Hooks

A hook lets you run your own code at a moment in the session: before a tool call, after a message, when a turn ends. You use one to enforce policy (block a dangerous command), add context, or record what happened. The example below rejects any bash command containing rm -rf.

A hook is a TypeScript module. You put it under a hook path in your profile (for example ~/.veyyon/profiles/<name>/agent/hooks/), and Veyyon loads it through the extension runner. A repository cannot ship a hook: a .veyyon/hooks/ directory inside a working tree is not read. The module default-exports a factory function that registers handlers with pi.on(...), one handler per event you care about.

CLI: --hook is an alias for --extension (paths merge into extension loading).

Full API and event list: repository docs/handbook/src/reference/hooks.md and packages/coding-agent/src/extensibility/hooks/.

Module shape

import type { HookAPI } from "@veyyon/coding-agent/extensibility/hooks";

export default function hook(pi: HookAPI): void {
	pi.on("tool_call", async (event, ctx) => {
		if (
			event.toolName === "bash" &&
			String(event.input.command ?? "").includes("rm -rf")
		) {
			return { block: true, reason: "blocked by policy" };
		}
	});
}

The factory can:

• register handlers with pi.on(...)
• send custom messages with pi.sendMessage(...)
• persist non-LLM state with pi.appendEntry(...)
• register slash commands with pi.registerCommand(...)
• register message renderers with pi.registerMessageRenderer(...)
• run shell commands with pi.exec(...)

Discovery

Hook/extension paths are resolved as absolute, ~-expanded, or relative to cwd. Discovery loads capability-registered modules, importable .ts/.js factories, plugin extension entry points, and explicit paths.

Lifecycle (extension bus)

Handlers attach to the runtime event bus used by the extension runner (tool call, session, compaction, and related events as defined in types.ts). Exact event names and payloads are in packages/coding-agent/src/extensibility/hooks/types.ts and docs/handbook/src/reference/hooks.md.

Typical uses

• Block or annotate specific tools before they run
• Inject policy text when a session starts
• Audit tool usage outside the TUI
• Register your own slash commands

Related

• Repository docs/handbook/src/reference/hooks.md

Hooks authoring

name: authoring-hooks description: Use when creating a new veyyon hook. Covers HookAPI, event catalog, blocking/overriding tool calls, and context modification.

Authoring Hooks

Hooks are event-driven interceptors that run alongside the agent loop. They are best used for cross-cutting concerns: safety policy, secret redaction, context pruning, audit logging. A hook module registers handlers via pi.on(event, handler) and can block tool execution, override tool output, or rewrite the message context before each LLM call.

Relationship to extensions: The hook subsystem (HookAPI) is the legacy API. The extension runner now handles everything hooks can do plus more. ExtensionAPI supports the hook event model plus extension-only events. Use ExtensionAPI for new work; use HookAPI only if you are maintaining an existing hook module.

Factory signature

import type { HookAPI } from "@veyyon/coding-agent/extensibility/hooks";

export default function myHook(veyyon: HookAPI): void {
  veyyon.on("tool_call", async (event, ctx) => {
    // intercept every tool call
  });
}

The default export must be a function (not a class). It receives a HookAPI instance and registers all handlers when called; the loader awaits its return value, so an async factory is awaited before the hook is considered loaded.

Alternatively, using ExtensionAPI (preferred):

import type { ExtensionAPI } from "@veyyon/coding-agent";

export default function myExtension(pi: ExtensionAPI): void {
  pi.on("tool_call", async (event, ctx) => { /* ... */ });
}

Event catalog

Tool lifecycle

Session lifecycle

Agent/turn lifecycle

Extension-only events such as tool_execution_start, tool_execution_update, tool_execution_end, input, user_bash, and user_python require ExtensionAPI.

Pre-tool blocking contract

Return { block: true, reason: "..." } from a tool_call handler to prevent execution:

veyyon.on("tool_call", async (event, ctx) => {
  if (event.toolName === "bash") {
    const cmd = String(event.input.command ?? "");
    if (/\brm\s+-rf\s+\//.test(cmd)) {
      return { block: true, reason: "Refusing to delete root filesystem" };
    }
  }
});

Contract:

• If any handler returns { block: true }, execution stops immediately.
• reason is returned to the LLM as the tool error text.
• If a handler throws, the tool is also blocked (fail-closed).
• Last non-blocking return wins for non-blocking results; first block: true short-circuits.

Post-tool override contract

Return { content, details, isError } from a tool_result handler to patch what the LLM sees:

veyyon.on("tool_result", async (event, ctx) => {
  if (event.toolName === "read" && !event.isError) {
    const redacted = event.content.map(chunk => {
      if (chunk.type !== "text") return chunk;
      return {
        ...chunk,
        text: chunk.text.replace(/(?:sk|pk)-[a-zA-Z0-9]{20,}/g, "[REDACTED_API_KEY]"),
      };
    });
    return { content: redacted };
  }
});

Contract:

• Handlers run in registration order. For HookAPI, each handler receives the original tool result event, and the last returned override wins.
• content replaces the full content array for the LLM.
• details replaces the structured details object.
• isError exists on the shared result type, but HookToolWrapper does not propagate it into a successful tool result; on a tool failure, the original error is rethrown after handlers complete.
• On a tool failure, tool_result is still emitted with isError: true.

Context modification contract

Return { messages: [...] } from a context handler to rewrite the message list before each LLM API call:

veyyon.on("context", async (event, ctx) => {
  // Remove debug-only custom messages from LLM context
  const filtered = event.messages.filter(
    msg => !(msg.role === "custom" && msg.customType === "debug-only")
  );
  return { messages: filtered };
});

Contract:

• event.messages is the current accumulated list.
• Handlers run in order; each receives the output of the previous handler.
• Return undefined (or nothing) to pass messages through unmodified.