A terminal coding agent whose harness is built for inspectable context, controlled mutation, and long-running work.

Veyyon uses the same model weights available in other clients. The difference is the workbench around them: a prompt you can inspect, model-native effort controls, explicit state ownership, protected secret spending, typed workers, language-server refactors, durable sessions, and tools that fail before stale state becomes a bad write.

Veyyon is a source fork of oh-my-pi. It is not a clean-room rewrite. UPSTREAM.md records the inherited foundation and the contracts Veyyon changed.

Linux and macOS

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

Windows

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

The release installer stages one self-contained binary, then checks its SHA-256 sidecar, exact release version, and native search support before it replaces an active install or changes your shell. Prebuilt releases are Linux x64 and arm64 (glibc), macOS x64 and arm64, and Windows x64 only. Windows arm64 runs the x64 build under emulation.

Self-updates use the same preflight. They preserve the previous binary and atomically switch the live path, so a hard kill leaves either the old or new binary available, never a missing command. If an installed completion file cannot be refreshed, the automatic-update notice in the TUI tells you to re-run the installer. Veyyon ships through GitHub Releases and source checkouts only. There is no npm, Homebrew, or crates.io distribution for the application.

Install and uninstall operations use sidecar ownership receipts. They refuse to overwrite or remove an unrelated executable or completion file that already occupies a Veyyon target path. Source updates also verify the checkout remote and restore the previous clean revision if post-merge provisioning or runtime verification fails.

To build from source:

git clone https://github.com/santhreal/veyyon.git
cd veyyon
bun setup
bun dev

See Install Veyyon for pinned releases, source installs, updates, rollback, and uninstall commands.

You can ask Veyyon what the model receives before you spend a token:

veyyon prompt --sections --cwd ./my-project
veyyon prompt --statements --cwd ./my-project
veyyon prompt --statement tool-selection --cwd ./my-project

The outer prompt is a zero-prose scaffold. Registered statements own the actual instructions and their activation conditions. Project context comes from layered AGENTS.md files and validated PROMPT_SECTIONS/ overrides. /move reloads cwd-derived context transactionally, so a failed discovery does not leave half of one project mixed with half of another.

Prompt customization · Context files

A session effort override wins first. An explicit selector suffix wins next, followed by the saved defaultEffort[model] row, the saved defaultEffort["*"] row, and finally the model default. Default removes the session override. The picker shows only effort variants the selected model supports, so Veyyon does not offer a choice that it will silently clamp into something else.

Compaction uses editable model chains and explicit fallback policy. Before a model summarizes history, a lossless pass removes contained duplicates. Manual and automatic compaction report what happened instead of silently switching models or discarding context.

Models and effort · Compaction and memory

Store a credential without typing it into the transcript:

/secret add DEPLOY_TOKEN --from-env DEPLOY_TOKEN --scope project

The model sees a named placeholder. Expansion happens at the final outbound tool boundary. The real value stays local, is encrypted at rest, is redacted from later outbound seams, and appears in an operator-visible use log by name rather than value. Scope, expiry, and removal are enforced when the credential is used.

Secret protection · Secret workflow

The task tool starts typed workers concurrently. Workers can coordinate through irc, return schema-validated results, persist their transcripts, and expose those results through agent:// and history:// URLs. /agents opens the Agent Control Center, where you can inspect each worker's live state, model, effort, and lifecycle controls.

Subagents · IRC · Internal URL routing

A rename is a symbol operation, not a text replacement. Veyyon asks the active language server for the workspace edit, applies it, and keeps file renames and references together. The edit tool separately uses content-hash anchors, so a file changed since the model read it fails closed before a patch lands.

Language servers · Editing and repair

Argot is experimental and off by default. A project dictionary maps repeated paths and phrases to short handles in the model's history. Handles expand before a tool, transcript, child result, parent result, or live display receives them. Disabling teaching does not disable decoding, so an old handle cannot leak after the feature is turned off.

The dependent controls are hidden while Argot is disabled:

Off

On

Its token economics remain unproven across workloads. The codec boundary is shipped; the performance claim is not assumed.

Argot design and limits

Every live workflow below uses the isolated demo profile with google-antigravity/gemini-3.6-flash at high effort. scripts/demos/setup-profile.sh creates that profile without copying a maintainer's working settings. scripts/demos/record.sh verifies the exact model before recording and refuses a fallback.

bash scripts/demos/setup-profile.sh --refresh
bash scripts/demos/record.sh

A committed tape must submit the action and finish on its result. A settings proof must show a differential, not one default screenshot. The recording contract lives in record-demo and prove-feature.

The gallery leads with Veyyon-owned contracts. The rest of the product is still available when the task needs it.

Use / to search commands and /settings to search configuration. The generated references stay closer to the registries than a hand-maintained README list:

• Slash commands
• Settings reference
• Tool guides
• Environment variables
• File locations

Use /model or --model for the interactive model. Assign smol, slow, plan, designer, commit, advisor, and custom roles independently. Compaction and subagents own separate ordered model chains. Retry fallback chains, path-scoped model filters, several credentials per provider, session affinity, and per-credential cooldown are explicit configuration.

Veyyon supports direct APIs, OAuth coding subscriptions, gateways, and local OpenAI-compatible servers. The catalog changes more often than this README. Run veyyon models for the active catalog and see Models, roles, and profiles for routing.

veyyon                         # interactive TUI
veyyon -p "inspect this repo"  # one-shot output
veyyon --mode rpc             # NDJSON RPC over stdio
veyyon acp                    # Agent Client Protocol for editors

TypeScript hosts can also use the session SDK. All four surfaces share the model registry, session runtime, tool policy, and approval semantics.

ACP and CLI modes · Extensions · Custom tools

Veyyon retains the Bun and TypeScript agent loop, terminal UI, provider catalog, role routing, hashline edit engine, mnemopi memory, and the original native grep, PTY, and tree-sitter hot-path foundations from oh-my-pi. These remain important product capabilities. They are not presented as Veyyon inventions.

Veyyon owns the statement-based prompt architecture, transactional context moves, model-native effort and explicit effort precedence, current compaction strategy and chains, provider-bound secret protection, profile/session durability rules, LSP write-through, capability and tool registry, typed worker and IRC operations, Agent Control Center, internal agent URLs, post-fork reusable Rust crate boundaries and their current contracts, and Argot integration boundaries described above.

This boundary describes this repository. It does not claim that current upstream has stood still. Read UPSTREAM.md, the mechanisms chapter, and the intentional divergence ledger for the detailed record.

bun setup
bun dev
bun run check

bun setup installs workspace dependencies and builds the local Rust/N-API addon. See CONTRIBUTING.md and packages/coding-agent/DEVELOPMENT.md before changing the runtime.

Veyyon is licensed under MIT. See LICENSE.

The project is derived from oh-my-pi. Upstream copyright and license notices are preserved in UPSTREAM.md and the source tree.