Settings reference

Every setting the schema declares: the ones /settings shows, grouped as that screen groups them, then the ones that exist only in a configuration file.

Generated by scripts/gen-settings-reference.ts. Edit the ui block on the setting in packages/coding-agent/src/config/settings-domains/, then run bun scripts/gen-settings-reference.ts --write. Never edit this file by hand: a test compares it against the generator and fails when the two disagree.

Read Settings first for where settings live, how precedence and merging work, and how to read and write them. The tables below are grouped as the /settings tabs are.

Set any of these keys in config.yml with the dotted path shown in the first column, or from the command line:

veyyon config set tui.tight true
veyyon config get compaction.threshold

Appearance

Theme

Key	Setting	Type	Default	What it does
`theme.dark`	Dark Theme	string	`titanium`	Theme used when the terminal has a dark background.
`theme.light`	Light Theme	string	`light`	Theme used when the terminal has a light background.
`symbolPreset`	Symbol Preset	enum	`unicode`	Glyph set for icons and symbols (Unicode, Nerd Font, or ASCII). Values: `unicode`, `nerd`, `ascii`.
`colorBlindMode`	Color-Blind Mode	boolean	`false`	Use blue instead of green for diff additions.

Status Line

Key	Setting	Type	Default	What it does
`statusLine.enabled`	Composer Footline	boolean	`true`	Show the quiet metadata line under the composer (model, mode, path, git, context). Off leaves the composer carrying nothing; the agent-focus exit hint still shows while a view is proxied.
`statusLine.preset`	Status Line Preset	enum	`default`	Pre-built status line configurations. Values: `default`, `minimal`, `compact`, `full`, `nerd`, `ascii`, `custom`.
`statusLine.sessionAccent`	Session Accent	boolean	`true`	Use the session name color for the editor border. Shown under the tab’s Advanced fold.
`statusLine.compactThinkingLevel`	Compact Thinking Level	boolean	`false`	Show the thinking level as a single icon on the model name instead of a separate `· \<level>` suffix. Shown under the tab’s Advanced fold.
`statusLine.showHookStatus`	Show Hook Status	boolean	`true`	Display hook status messages below the status line. Shown under the tab’s Advanced fold.
`statusLine.showAccount`	Show Serving Account	boolean	`false`	Name the account serving the next request on the composer footline, when the active provider stores more than one. Off: /account answers it on demand. Shown under the tab’s Advanced fold.

Display

Key	Setting	Type	Default	What it does
`terminal.showImages`	Show Inline Images	boolean	`true`	Render images inline in the terminal.
`images.autoResize`	Auto-Resize Images	boolean	`true`	Resize large images to 2000x2000 max for better model compatibility. Shown under the tab’s Advanced fold.
`terminal.showProgress`	Native Terminal Progress	boolean	`false`	Emit OSC 9;4 indeterminate progress while the agent or context maintenance is running. Shown under the tab’s Advanced fold.
`tui.textSizing`	Large Headings (Kitty)	boolean	`false`	Render Markdown H1 headings at 2x scale using Kitty’s OSC 66 text-sizing protocol. Only takes effect on Kitty terminals; ignored everywhere else. Off by default. Shown under the tab’s Advanced fold.
`tui.renderMermaid`	Render Mermaid Diagrams	boolean	`true`	Render Mermaid fenced code blocks as ASCII diagrams. Shown under the tab’s Advanced fold.
`tui.hyperlinks`	Terminal Hyperlinks	enum	`auto`	Wrap paths and URLs in OSC 8 hyperlinks for terminal-native click-to-open (auto: detect support; off: never; always: unconditional). Values: `off`, `auto`, `always`.
`tui.paintGround`	Paint Theme Ground	enum	`auto`	Set the terminal background (OSC 11) to the theme’s ground color while Veyyon runs, restoring it on exit (auto: only when the terminal background already matches the theme so no seam appears; always: unconditional; never: inherit the terminal background). Values: `auto`, `always`, `never`.
`tui.tight`	Tight Layout	boolean	`false`	Remove the 1-character horizontal padding from the left and right of the terminal output. Shown under the tab’s Advanced fold.
`tui.scrollbackRebuild`	Rewrite Scrollback	boolean	`true`	Erase and replay terminal scrollback when a block’s final form replaces its live preview. On by default: with it off, the stale preview stays in history and the final content is appended underneath, so the same paragraph appears twice. Terminal multiplexers keep the append-below behaviour either way, because erasing there would take the pane’s own history with it. Shown under the tab’s Advanced fold.
`tui.scrollIsolation`	Scroll Isolation	boolean	`false`	Read the mouse wheel so the transcript scrolls with the prompt pinned at the bottom, showing the position on the right edge. This costs you drag-select: while it is on, veyyon holds the mouse, so plain dragging selects nothing and you need shift+drag, or `/copy` to pick text and code out of the conversation without the mouse. When off (default), the terminal keeps the wheel and the mouse, so native scrollback, drag-select and copy all behave exactly as they do in any other program, and the prompt still sits at the bottom of the live view. Shown under the tab’s Advanced fold.
`display.transitions`	Transitions	enum	`on`	Structural motion: overlay open transitions and the moving rail beside a running tool. Values: `on`, `off`.
`display.shimmer`	Shimmer	enum	`disabled`	Animation style for working/loading messages. Values: `classic`, `kitt`, `living`, `disabled`.
`display.smoothStreaming`	Smooth Streaming	boolean	`true`	Reveal assistant text and streamed tool input smoothly while chunks arrive.
`display.showTokenUsage`	Show Token Usage	boolean	`false`	Show what each turn spent under the assistant message: tokens, how long it took, and its rate.
`display.cacheMissMarker`	Cache Miss Marker	boolean	`false`	Show a divider above an assistant turn whose request lost (missed) the prompt cache. Shown under the tab’s Advanced fold.
`display.toolOutputExpanded`	Expand Tool Output	boolean	`false`	Start tool calls expanded, showing full input and output instead of a preview; the in-session toggle updates this. Shown under the tab’s Advanced fold.
`showHardwareCursor`	Show Hardware Cursor	boolean	`true`	Show terminal cursor for IME support. Shown under the tab’s Advanced fold.

Model

Compaction

Key	Setting	Type	Default	What it does
`display.collapseCompacted`	Collapse Compacted History	boolean	`true`	Collapse pre-compaction history behind the summary divider on the live transcript; disable to keep the full transcript inline with dividers at each compaction point.
`compaction.remote`	Remote Compaction	boolean	`true`	Applies only when the session model is a supported OpenAI Responses model, which includes Azure OpenAI Responses deployments and ChatGPT Codex sessions; every other model ignores this setting and compacts locally. On, veyyon has the provider compact the span and keeps the window it returns, which preserves reasoning state across the cut. That window is the whole compacted context, so the entry stores no summary text and the compaction model chain does not apply. There is no second local summary on purpose: it would pay a model to re-summarize a span the provider already compacted and leave two versions of one range that can disagree. Off, compaction runs locally on the usual summary path and stores readable summary text.
`compaction.strategy`	Compaction Type	enum	`summary`	Summary condenses history in place and continues the same session. Values: `summary`.
`compaction.threshold`	Auto-Compaction Threshold	string	`auto`	When auto-compaction triggers. Auto uses the model’s window minus the reserve; a percent scales with each model’s window; a token amount is the same trigger on every model that can reach it, and a smaller model compacts at its own maximum.
`compaction.model`	Compaction Model	modelChain	(unset)	Models used for in-place summary compaction, tried in order. Default: inherit — follows the main model live. Add fallbacks for when the first is unauthenticated or its window is too small.
`compaction.modelFallbackStrategy`	Compaction Fallback	enum	`auto`	What to try after the compaction models you configured. Auto stays on models you named: the main model, its same-provider compaction sibling, and your model roles. Any authenticated model also reaches the largest window available, on any provider you have credentials for. Configured only stops at the chain and fails loudly. Values: `auto`, `any-model`, `configured-only`.
`compaction.modelContextWindow`	Compaction Model Context	number	(unset)	Context window in tokens to assume for the compaction model. Unset uses the compaction model’s own reported window. Candidates whose window cannot fit the summarization payload are skipped loudly.

Roles

Key	Setting	Type	Default	What it does
`modelRoles`	Role Models	record	`{}`	Assign a model to each role (Fast, Thinking, Vision, Architect, Designer, Commit, Tiny). Opens a searchable picker with auth status. The advisor’s model is asked for in the Advisor group, and a subagent’s in Subagents → Roster, so neither appears here. Scoped to the active profile — never edit config by hand.

Thinking

Key	Setting	Type	Default	What it does
`defaultEffort`	Default Effort	record	`{}`	Effort per model, applied when a run does not ask for one. Add a model and pick its effort; the “any model” row covers every model without its own. Per profile.
`hideThinkingBlock`	Hide Thinking Blocks	boolean	`false`	Hide thinking blocks in assistant responses.
`proseOnlyThinking`	Prose Only Thinking	boolean	`true`	Omit code blocks from thinking summaries and replace them with an ellipsis.
`omitThinking`	Omit Thinking summaries	boolean	`false`	Instruct upstream providers to completely omit thinking summaries from responses (where supported).
`model.loopGuard.enabled`	Loop Guard	boolean	`true`	Enable automatic stream loop detection for model reasoning and prose.
`model.loopGuard.checkAssistantContent`	Loop Guard Scan Prose	boolean	`true`	Apply loop guard to assistant prose messages in addition to thinking logs.
`model.loopGuard.toolCallReminder`	Loop Guard Tool-Call Reminder	boolean	`true`	When a Gemini reasoning stream emits many consecutive planning headers without calling a tool, interrupt it and inject a reminder to issue a tool call (requires Loop Guard).
`model.toolCallLoopGuard.enabled`	Tool-Call Loop Guard	boolean	`true`	Detect consecutive identical tool calls across turns and inject a corrective steer.
`model.toolCallLoopGuard.threshold`	Tool-Call Loop Threshold	number	`5`	Consecutive identical tool calls required before the corrective steer is injected.
`model.toolCallLoopGuard.readSubsumptionThreshold`	Read Subsumption Loop Threshold	number	`3`	Consecutive fully-subsumed or redundant read calls on unchanged files before the corrective steer is injected.
`model.toolCallLoopGuard.exemptTools`	Tool-Call Loop Exempt Tools	array	`["job","irc"]`	Tool names that may repeat consecutively without triggering the cross-turn loop guard.
`providers.autoThinkingModel`	Auto Thinking Model	enum	`online`	Difficulty classifier for the `auto` thinking level: online (the TINY role from /models, else smol) by default, or a local on-device model. Values: `online`, `qwen3-1.7b`, `llama3.2:3b`, `gemma-3-1b`, `qwen2.5-1.5b`, `lfm2-1.2b`.

Sampling

Key	Setting	Type	Default	What it does
`temperature`	Temperature	number	(unset)	Sampling temperature. 0 is deterministic, 1 is creative. Unset lets the provider choose.
`topP`	Top P	number	(unset)	Nucleus sampling cutoff, 0 to 1. Unset lets the provider choose.
`topK`	Top K	number	(unset)	Sample from the top K tokens. Unset lets the provider choose.
`minP`	Min P	number	(unset)	Minimum probability threshold, 0 to 1. Unset lets the provider choose.
`presencePenalty`	Presence Penalty	number	(unset)	Penalty for introducing tokens already present. Negative values encourage repetition; unset lets the provider choose.
`repetitionPenalty`	Repetition Penalty	number	(unset)	Penalty for repeated tokens. Values below 1 encourage repetition; unset lets the provider choose.
`textVerbosity`	Text Verbosity	enum	`medium`	OpenAI Responses and Codex response verbosity (low, medium, or high). Values: `low`, `medium`, `high`.
`tier.openai`	Service Tier — OpenAI	enum	`none`	How your OpenAI / OpenAI-Codex requests are queued and served, including OpenAI-family models routed via OpenRouter (none = omit the field). Sent as `service_tier`. This is serving speed and cost, not reasoning depth; depth is Default Effort. Values: `none`, `auto`, `default`, `flex`, `scale`, `priority`.
`tier.anthropic`	Service Tier — Anthropic	enum	`none`	How your Claude requests are queued and served. `priority` realizes fast mode (`speed: "fast"`) on supported direct Anthropic models, and is ignored on Bedrock/Vertex Claude and via OpenRouter. This is serving speed and cost, not reasoning depth; depth is Default Effort. Values: `none`, `priority`.
`tier.google`	Service Tier — Google	enum	`none`	How your Gemini (Google AI Studio + Vertex) requests are queued and served, including Google-family models routed via OpenRouter (none = omit the field). Sent as the top-level `serviceTier` field. This is serving speed and cost, not reasoning depth; depth is Default Effort. Values: `none`, `flex`, `priority`.
`tier.subagent`	Service Tier — Subagent	enum	`inherit`	How spawned task/eval subagent requests are queued and served. Inherit matches the main agent’s live per-family tiers (tracks /fast); pick a value to apply it to whichever family the subagent’s model belongs to. Values: `inherit`, `none`, `auto`, `default`, `flex`, `scale`, `priority`.
`tier.advisor`	Service Tier — Advisor	enum	`none`	How advisor-model requests are queued and served. None is standard processing, Inherit matches the main agent’s live per-family tiers, and picking a value applies it to the advisor model’s family. Values: `inherit`, `none`, `auto`, `default`, `flex`, `scale`, `priority`.

Prompt

Key	Setting	Type	Default	What it does
`inlineToolDescriptors`	Inline Tool Descriptors	enum	`auto`	Render full tool descriptors in the system prompt and strip top-level/nested descriptions from provider tool schemas so descriptor text is sent once. Auto follows the active model, enabling this for Gemini and disabling it otherwise. Values: `auto`, `on`, `off`.
`includeModelInPrompt`	Include Model in Prompt	boolean	`false`	Surface the active model identifier in the system prompt so the agent knows which model it is. Costs a full prompt-cache invalidation on every model switch.
`includeWorkspaceTree`	Include Workspace Tree	boolean	`false`	Render the workspace directory tree in the system prompt. WARNING: This can bust prompt caching across sessions when files are modified.
`personality`	Personality	string	`default`	Communication style rendered into the system prompt’s personality block. Extend via ~/.veyyon/personalities/<name>.md or project .veyyon/personalities/<name>.md.

Retry & Fallback

Key	Setting	Type	Default	What it does
`retry.maxRetries`	Retry Attempts	number	`10`	Maximum retry attempts on API errors.
`retry.maxDelayMs`	Max Retry Delay	number	`300000`	Maximum wait between retries, in ms. When the provider asks us to wait longer than this and no credential or model fallback succeeds, the request fails fast instead of sleeping (e.g. 3-hour Anthropic rate-limit windows).
`retry.modelFallback`	Retry Model Fallback	boolean	`true`	Allow retry recovery to switch to configured fallback models.
`retry.fallbackChains`	Retry Fallback Chains	record	`{}`	JSON object mapping model roles, model selectors (“provider/model-id”), or provider wildcards (“provider/”) to ordered fallback selectors, e.g. {“default”:[“openai/gpt-4o-mini”],“google-antigravity/”:[“google/”,“google-vertex/”]}. Model-oriented keys apply whenever that model/provider is active, regardless of role; a “provider/*” entry keeps the failing model’s id and swaps the provider.
`retry.perProvider`	Per-Provider Retry	record	`{}`	JSON object overriding retry limits for specific backends, keyed like Retry Fallback Chains: a model selector (“provider/model-id”), a provider wildcard (“provider/*”), or a bare provider name. Each value may set maxRetries, baseDelayMs, and maxDelayMs; anything omitted falls back to the global retry settings. Example: {“cursor”:{“maxRetries”:3,“baseDelayMs”:2000}}. Backends whose retries are intrinsically expensive (cursor, devin) already ship with sensible limits; an entry here overrides those.
`retry.fallbackRevertPolicy`	Fallback Revert Policy	enum	`cooldown-expiry`	When to return to the primary model after a fallback. Values: `cooldown-expiry`, `never`.
`providers.anthropic.serverSideFallback`	Anthropic Server-Side Fallback (Fable 5)	boolean	`false`	When a Claude Fable 5 / Mythos 5 request is blocked by Anthropic’s safety classifier, retry it on Claude Opus 4.8 server-side (Anthropic `server-side-fallback-2026-06-01` beta). Opt-in — leaving this off preserves the pre-fallback behavior for every request.

Advisor

Key	Setting	Type	Default	What it does
`advisor.enabled`	Enable Advisor	boolean	`false`	Pair a second model that passively reviews each turn and injects notes. Which model it runs is Advisor Model, directly below.
`advisor.subagents`	Advisor for Subagents	boolean	`false`	Also enable the advisor on spawned task/eval subagents.
`advisor.syncBacklog`	Advisor Sync Backlog	enum	`off`	Pause the main agent for up to 30 seconds if the advisor falls behind by this many turns. Off disables catch-up delays. Values: `off`, `1`, `3`, `5`.
`advisor.immuneTurns`	Advisor Immune Turns	number	`3`	After an advisor concern or blocker interrupts, route further concerns/blockers non-interruptingly for this many primary turns.

Prewalk

Key	Setting	Type	Default	What it does
`prewalk.enabled`	Enable Prewalk	boolean	`false`	Plan on the strong model, then switch to the cheap model at the first edit/write after the plan nudge’s todo list exists — the strong model commits the todos and starts the implementation before handing off. The cheap model comes from Prewalk Cheap Model; Prewalk Strong Model overrides the start model. Overridable per session with –prewalk / –no-prewalk.
`prewalk.cheapModel`	Prewalk Cheap Model	modelChain	(unset)	Model prewalk hands off to at the first edit/write. Required once prewalk is on: /prewalk and –prewalk fail with a message naming this setting when it is unset. –prewalk-into overrides it per session; only the first entry is used.
`prewalk.strongModel`	Prewalk Strong Model	modelChain	(unset)	Model a prewalk session starts on — the strong model that plans before the handoff. Unset: inherit the normal start model (–model or the remembered default). Only the first entry is used.

Vision

Key	Setting	Type	Default	What it does
`images.describeForTextModels`	Describe Images for Text Models	boolean	`true`	When an image is attached to a model without vision support, save it under local:// and inject a description from a vision-capable model instead of dropping it.

Interaction

Input

Key	Setting	Type	Default	What it does
`steeringMode`	Steering Mode	enum	`one-at-a-time`	How to process queued messages while agent is working. Values: `all`, `one-at-a-time`.
`followUpMode`	Follow-Up Mode	enum	`one-at-a-time`	How to drain follow-up messages after a turn completes. Values: `all`, `one-at-a-time`.
`interruptMode`	Interrupt Mode	enum	`immediate`	When steering messages interrupt tool execution. Values: `immediate`, `wait`.
`loop.mode`	Loop Mode	enum	`prompt`	What happens between /loop iterations before re-submitting the prompt. Values: `prompt`, `compact`, `reset`.
`doubleEscapeAction`	Double-Escape Action	enum	`tree`	Action when pressing Escape twice with empty editor. Values: `branch`, `tree`, `none`.
`treeFilterMode`	Session Tree Filter	enum	`default`	Default filter mode when opening the session tree. Values: `default`, `no-tools`, `user-only`, `labeled-only`, `all`.
`autocompleteMaxVisible`	Autocomplete Items	number	`5`	Max visible items in autocomplete dropdown (3-20).
`emojiAutocomplete`	Emoji Autocomplete	boolean	`true`	Suggest emojis from `:name:` shortcodes and expand text emoticons like `:D` or `:-)`.
`paste.largeMenuThreshold`	Large Paste Menu	number	`100`	When a paste reaches this many lines, offer a menu to wrap it in a code block, wrap it in XML tags, or save it to a file. 0 disables the menu (large pastes still collapse to a [Paste] marker).

Session

Key	Setting	Type	Default	What it does
`session.newKeepsBackground`	/new Keeps The Old Session	boolean	`false`	Requires a restart: switching this on or off changes nothing in the running session. On /new while a response is still streaming, keep the old conversation running in the background and attach the screen to a fresh one. The status line counts running background conversations. Off stops the old turn and closes its provider stream before the new session starts, so nothing keeps billing once it leaves the screen.

Approvals

Key	Setting	Type	Default	What it does
`tools.approval`	Tool Approval Policies	record	`{}`	Per-tool approval policies. Set to ‘allow’ to auto-approve, ‘prompt’ to require confirmation, or ‘deny’ to block. Overrides are honored in every approval mode. Any other value denies that tool and is reported at startup.
`tools.protectedPaths`	Extra Protected Paths	array	`[]`	Additional absolute paths (a leading ~ is expanded) that a recursive delete must never target without approval. Adds to the built-in set; it cannot remove from it.
`tools.approvalMode`	Tool Approval	enum	`auto`	How much the agent may do without asking. Defaults to Auto: every tier runs, with the per-tool policies, working-directory boundary, credential and critical-call guards still asking. This is the persisted default; override it for one session with /permissions. Values: `plan`, `ask`, `ask-command`, `auto`, `yolo`, `always-ask`, `write`, `auto-edit`.

Notifications

Key	Setting	Type	Default	What it does
`completion.notify`	Completion Notification	enum	`off`	Notify when the agent finishes a turn (off by default: the turn is on your screen). Values: `on`, `off`.
`ask.timeout`	Ask Timeout	number	`0`	Auto-select the recommended ask option after this many seconds (0 disables).
`ask.notify`	Ask Notification	enum	`on`	Notify when the agent is blocked on a question you have not answered. Values: `on`, `off`.
`recap.enabled`	Idle Recap	boolean	`true`	Generate a brief LLM recap of where things stand after the terminal has been idle.
`recap.idleSeconds`	Idle Recap Delay	number	`240`	Seconds to wait while idle before showing the recap.

Speech

Key	Setting	Type	Default	What it does
`stt.enabled`	Speech-to-Text	boolean	`false`	Enable speech-to-text input via microphone.
`stt.modelName`	Speech Model	enum	`parakeet`	Local on-device speech model. Parakeet TDT v3 (sherpa-onnx) is the SoTA default; Whisper base/small/large-v3-turbo tiers (transformers.js) trade size for multilingual coverage. Downloaded on first use. Values: `fast`, `balanced`, `turbo`, `parakeet`.
`stt.submitTrigger`	Speech-to-Text Submit Trigger	enum	`never`	Choose when speech dictation automatically submits: Never, Release (2+ words), Release with complete sentence, or When I Say Submit. Values: `never`, `release`, `release-complete`, `say-submit`.

Collab

Key	Setting	Type	Default	What it does
`collab.relayUrl`	Relay URL	string	`wss://share.veyyon.dev`	Relay used by /collab (wss://host[:port]).
`collab.webUrl`	Web UI URL	string	(empty)	Browser UI used by /collab links; empty derives from collab.relayUrl; explicit http:// is localhost-only.
`collab.displayName`	Display Name	string	(empty)	Name shown to other collab participants (default: OS username).
`share.serverUrl`	Share Server	string	`https://share.veyyon.dev/s`	Share viewer/upload base used by /share (encrypted blob upload + viewer; links are <base>/<id>#<key>).
`share.store`	Share Store	enum	`blob`	Where /share uploads the encrypted session blob. Values: `blob`, `gist`.
`share.redactSecrets`	Share Secret Redaction	boolean	`true`	Run the secret obfuscator over /share snapshots before upload (uses the secrets.* config).

Magic Keywords

Key	Setting	Type	Default	What it does
`magicKeywords.enabled`	Enable Magic Keywords	boolean	`true`	Enable hidden notices for standalone ultrathink, orchestratez, and workflowz keywords.
`magicKeywords.ultrathink`	Ultrathink Keyword	boolean	`true`	Let standalone ultrathink request maximum automatic thinking and append its hidden notice.
`magicKeywords.orchestrate`	Orchestrate Keyword	boolean	`true`	Let standalone orchestratez append its hidden multi-agent orchestration notice.
`magicKeywords.workflow`	Workflow Keyword	boolean	`true`	Let standalone workflowz append its hidden eval workflow notice.
`magicKeywords.turnBudget`	Turn Budget Directive	boolean	`false`	Let a standalone +500k or +2m set this turn’s output-token budget; when off, +Nk in a message is treated as ordinary text.

Startup & Updates

Key	Setting	Type	Default	What it does
`autoResume`	Auto Resume	boolean	`false`	Automatically resume the most recent session in the current directory.
`startup.quiet`	Quiet Startup	boolean	`false`	Skip welcome screen and startup status messages.
`startup.showSplash`	Show Startup Splash	boolean	`false`	Show the full animated setup splash on normal interactive startup without rerunning setup. Quiet Startup still suppresses it.
`startup.clearScrollback`	Clear Scrollback on Startup	boolean	`false`	Erase the terminal’s saved scrollback when veyyon starts, so the session begins on an empty terminal. This also erases what was on screen before you launched, such as your shell history and any command output, and it cannot be undone. Off still starts you on a clear screen; it just leaves your history reachable by scrolling up.
`startup.setupWizard`	Setup Wizard	boolean	`true`	Run onboarding on first install only (updates never re-run it).
`startup.checkUpdate`	Check for Updates	boolean	`true`	Check for Veyyon updates on startup.
`marketplace.autoUpdate`	Marketplace Auto-Update	enum	`notify`	Check for plugin updates on startup. Values: `off`, `notify`, `auto`.
`startup.autoUpdate`	Automatic Updates	boolean	`true`	Install a newer version in the background; off means updates only when you run `veyyon update`.
`startup.updateNotice`	Update Notice	boolean	`true`	Show a one-line notice on the first launch after an update.

Profile

Key	Setting	Type	Default	What it does
`profile.displayName`	Profile Name	string	(empty)	Display name for the active profile, shown in /profile list and resolvable by /profile <name>. Stored per profile; empty falls back to the profile’s directory name (“default” for the base profile).
`session.workdir`	Default Working Directory	string	(unset)	Per-profile default session working directory used when launching without an explicit –cwd. Precedence: an explicit –cwd wins, then this setting, then the directory you launched from. Use an absolute or ~-relative path; a relative path or a missing directory makes launch fail loudly. The agent can override the live session cwd for that session only via set_cwd / /cwd without writing this setting.

Power (macOS)

Key	Setting	Type	Default	What it does
`power.sleepPrevention`	Sleep Prevention	enum	`idle`	Prevent macOS sleep during active sessions. Each level is cumulative — it adds the flags of all lower levels. Values: `off`, `idle`, `display`, `system`.

Agent

Key	Setting	Type	Default	What it does
`features.unexpectedStopDetection`	Detect unexpected stops	boolean	`false`	Use a small model to detect when the assistant says it will continue but stops without tool calls; automatically prompt it to continue.

Git

Key	Setting	Type	Default	What it does
`git.enabled`	Enable Git Integration	boolean	`true`	Show git branch, status, and PR information in the TUI and watch repository metadata.

Resources

CPU

Key	Setting	Type	Default	What it does
`session.cpuLimitCores`	Session CPU Limit	number	`0`	Maximum CPU a session’s spawned processes may use, in cores (0 = off). This is the per-profile default: every session that profile starts inherits it, and one session can depart from it with /cpu-limit <cores> or lift it entirely with /cpu-limit remove, neither of which writes this setting. Every process the session starts (bash commands, MCP servers, custom tools, launch tasks, workers) joins a per-session budget group: a cgroup v2 quota on Linux, a Job Object hard cap on Windows, both kernel-enforced, so the group throttles as a whole. While the group runs saturated, new commands are refused with an error naming the budget. On macOS there is no kernel quota, so enforcement is policy-only (refuse new commands, renice, optional kill) and a startup warning says so. The harness’s own compute (agent turns, in-process workers) is never capped.
`session.cpuLimitKill`	Kill Over-Budget Commands	boolean	`false`	What happens when spawned commands stay at the CPU limit for seconds at a time. Off (default): new commands are refused until usage drops, running ones keep running (throttled where the OS offers a quota, reniced on macOS). On: the over-budget group is also sent SIGTERM, and the kill is reported as a budget action, not a crash. /cpu-limit kill on\|off changes it for one session without writing this setting.

Memory

Key	Setting	Type	Default	What it does
`session.memoryLimitGb`	Session Memory Limit	number	`0`	Maximum resident memory the session tree may hold at once, in gigabytes (0 = off). The session tree is this session, every subagent under it at any depth, and every process any of them spawned: they share one budget group, so delegating work cannot multiply the allowance. This is a kernel cap, not a polite refusal: on Linux it is cgroup v2 memory.max on the session budget group, so a group at the limit is reclaimed first and then a process INSIDE it is OOM-killed by the kernel, whichever process the kernel picks, with no warning and no chance to finish. Set it where an OOM kill is preferable to the machine swapping, and leave it off if a killed command would cost more than the memory does. A host without a memory controller reports the limit as unenforceable once at startup rather than pretending to hold it.

Disk

Key	Setting	Type	Default	What it does
`session.writeBudgetGb`	Session Write Budget	number	`0`	Cumulative gigabytes the session tree may WRITE to disk before further writes are refused (0 = off). The session tree is this session, every subagent under it at any depth, and every process any of them spawned: they share one budget group, so delegating work cannot multiply the allowance. Writes are metered by the same group that meters CPU (cgroup v2 io accounting on Linux, Job Object I/O accounting on Windows). Once the total is reached, a new command is refused with an error naming the budget and how much it has written; already running commands keep running unless Kill Over-Budget Writers is on. A host where write accounting cannot be read reports the limit as unenforceable once at startup rather than pretending to hold it.
`session.writeBudgetKill`	Kill Over-Budget Writers	boolean	`false`	What happens when the session tree passes its write budget. Off (default): new commands are refused, and whatever is already writing runs to completion. On: the over-budget group is also sent SIGTERM, and the kill is reported as a budget action rather than a crash, so a command that vanished mid-write is explained instead of looking like a failure. Hidden while the write budget is 0, because a kill policy for a budget that does not exist is a knob with nothing behind it.

Processes

Key	Setting	Type	Default	What it does
`session.maxProcesses`	Session Max Processes	number	`0`	Hard cap on how many processes may be alive at once across the session tree (0 = off). The session tree is this session, every subagent under it at any depth, and every process any of them spawned, all in one budget group, so the cap is not multiplied by delegating. Enforced by the kernel where it can be: cgroup v2 pids.max on Linux and a Job Object process limit on Windows both refuse the fork itself, so a runaway loop stops instead of filling the process table. Elsewhere the cap is policy-only, refusing a new spawn with an error naming the limit and the current count, and a startup notice says the kernel is not holding it.

Context

General

Key	Setting	Type	Default	What it does
`contextPromotion.enabled`	Auto-Promote Context	boolean	`false`	Promote to a larger-context model on context overflow instead of compacting.
`branchSummary.enabled`	Branch Summaries	boolean	`false`	Prompt to summarize when leaving a branch.
`context.thinkingRetention`	Thinking Retention	number	`-1`	How many of the most recent assistant turns keep their unsigned thinking when the conversation is sent back. Gemini summarises its reasoning for you to read but replays the real reasoning from the signature on the tool call, so an old summary is transcript text the model re-reads and the provider ignores. Keep All resends every summary ever produced. Thinking that does carry a signature is always kept. Other providers ignore this. Shown under the tab’s Advanced fold.
`context.thoughtSignatureRetention`	Thought Signature Retention	number	`-1`	How many of the most recent assistant turns keep their Gemini thought signature when the conversation is sent back. Signatures let the model replay its own reasoning, and they are large, so the recent ones are the ones worth paying to resend. Keep All resends every signature ever produced, which on a long session is the single biggest thing in the context. Other providers ignore this. Shown under the tab’s Advanced fold.
`context.thoughtSignatureMaxLength`	Thought Signature Size Limit	number	`-1`	Longest Gemini thought signature still worth resending, in characters. Anything longer sends the skip sentinel instead, however recent it is. Signature sizes are lopsided: the largest tenth of them carry roughly two thirds of all signature bytes, so a limit sheds most of the weight while keeping the great majority of the reasoning chain. Use this instead of Thought Signature Retention when you want a gentler trade, or alongside it, in which case a signature is resent only if it is both recent enough and small enough. Other providers ignore this. Shown under the tab’s Advanced fold.

Prompt Cache

Key	Setting	Type	Default	What it does
`cache.reportRejection`	Report Cache Rejections	boolean	`true`	Warn when a turn asked the provider to cache a prefix and the provider cached nothing. Anthropic only; other providers do not report cache rejection.
`cache.blockOnRejection`	Block On Cache Rejection	boolean	`false`	Anthropic only. Fail the next request after a rejected cache instead of continuing to pay full input rate. Off by default: the verdict is proven against provider usage reporting, so a provider that changes what it reports would stop the session rather than cost money.

Session Instrumentation

Key	Setting	Type	Default	What it does
`session.instrumentation`	Instrumentation Level	enum	`off`	Record structured, redacted study data in the session file. Higher levels add lifecycle, task-state, tool, model-turn, context, and agent-communication detail for `veyyon session stats`. Off still stores the normal resumable conversation and tool history, but adds no study fields. Values: `off`, `basic`, `rich`, `ultra`.

Rules

Key	Setting	Type	Default	What it does
`ttsr.builtinRules`	Built-in Rules	boolean	`true`	Load the default rules shipped with the agent. Turn individual rules off under All Rules.
`ttsr.disabledRules`	All Rules	array	`[]`	Every rule this project loads, each on or off. Stores only the ones you turn off, so a rule added in a later release arrives on.

Stream Interrupts (TTSR)

Key	Setting	Type	Default	What it does
`ttsr.enabled`	TTSR	boolean	`true`	Interrupt the agent mid-stream when output matches rule patterns (Time-Traveling Stream Rules).
`ttsr.contextMode`	Context Mode	enum	`discard`	What to do with partial output when TTSR triggers. Values: `discard`, `keep`.
`ttsr.interruptMode`	Rule Interrupt Mode	enum	`always`	When to interrupt mid-stream vs inject warning after completion. Values: `never`, `prose-only`, `tool-only`, `always`.
`ttsr.repeatMode`	Repeat Mode	enum	`once`	How rules can repeat: once per session or after a message gap. A rule may override this in its frontmatter. Values: `once`, `after-gap`.
`ttsr.repeatGap`	Repeat Gap	number	`10`	Messages before a rule can trigger again. A rule may override this in its frontmatter.

Memory

General

Key	Setting	Type	Default	What it does
`memory.backend`	Memory Backend	enum	`off`	Off, local summary pipeline, Mnemopi SQLite, or Hindsight remote memory. Values: `off`, `local`, `hindsight`, `mnemopi`.
`providers.memoryModel`	Memory Model	enum	`online`	Mnemopi LLM for fact extraction + consolidation: online (the TINY role from /models, else smol/remote) by default, or a local on-device model. Values: `online`, `qwen3-1.7b`, `llama3.2:3b`, `gemma-3-1b`, `qwen2.5-1.5b`, `lfm2-1.2b`.

Mnemopi

Key	Setting	Type	Default	What it does
`mnemopi.dbPath`	Mnemopi DB Path	string	(unset)	Optional SQLite DB path. Defaults to the agent memories directory.
`mnemopi.bank`	Mnemopi Bank	string	(unset)	Optional shared bank base name. Per-project modes derive project-local banks from it.
`mnemopi.scoping`	Mnemopi Scoping	enum	`per-project`	global = one shared bank; per-project = isolated bank per cwd; per-project-tagged = project-local writes plus global recall visibility. Values: `global`, `per-project`, `per-project-tagged`.
`mnemopi.embeddingVariant`	Embedding variant	enum	`en`	Local embedding model family. en = stronger English model; multilingual = cross-language model. Changing this rebuilds existing memory embeddings on next start. Values: `en`, `multilingual`.
`mnemopi.autoRecall`	Mnemopi Auto Recall	boolean	`true`	Recall local memories into the first turn of each session.
`mnemopi.autoRetain`	Mnemopi Auto Retain	boolean	`true`	Retain completed conversation turns into local Mnemopi memory.
`mnemopi.polyphonicRecall`	Mnemopi Polyphonic Recall	boolean	`false`	Enable 4-voice recall (vector, graph, fact, temporal) fused with reciprocal rank fusion.
`mnemopi.enhancedRecall`	Mnemopi Enhanced Recall	boolean	`false`	Enable the tiered query result cache for repeated and similar recall queries.
`mnemopi.proactiveLinking`	Mnemopi Proactive Linking	boolean	`false`	Ingest new memories into the episodic graph as they are stored, linking them to related entities and memories.
`mnemopi.noEmbeddings`	Mnemopi Disable Embeddings	boolean	`false`	Force deterministic FTS-only recall instead of vector embeddings.
`mnemopi.embeddingModel`	Mnemopi Embedding Model	string	(unset)	Advanced: explicit embedding model id that overrides the variant. Leave empty to use mnemopi.embeddingVariant.
`mnemopi.embeddingApiUrl`	Mnemopi Embedding API URL	string	(unset)	Optional OpenAI-compatible embedding endpoint passed to Mnemopi.
`mnemopi.embeddingApiKey`	Mnemopi Embedding API Key	string	(unset)	Optional embedding API key passed to Mnemopi.
`mnemopi.llmMode`	Mnemopi LLM Mode	enum	`smol`	Use no LLM, the online tiny model (the TINY role from /models, else @smol), or a remote OpenAI-compatible endpoint. Values: `none`, `smol`, `remote`.
`mnemopi.llmBaseUrl`	Mnemopi LLM Base URL	string	(unset)	Optional OpenAI-compatible LLM endpoint for Mnemopi remote mode.
`mnemopi.llmApiKey`	Mnemopi LLM API Key	string	(unset)	Optional LLM API key for Mnemopi remote mode.
`mnemopi.llmModel`	Mnemopi LLM Model	string	(unset)	Optional LLM model name for Mnemopi remote mode.

Hindsight

Key	Setting	Type	Default	What it does
`hindsight.apiUrl`	Hindsight API URL	string	`http://localhost:8888`	Hindsight server URL (Cloud or self-hosted).
`hindsight.bankId`	Hindsight Bank ID	string	(unset)	Base memory bank name. Unset uses `veyyon`. Hindsight Bank Prefix is prepended when set, and Hindsight Scoping decides whether the project name is appended (per-project) or carried as a `project:` tag instead (per-project-tagged).
`hindsight.scoping`	Hindsight Scoping	enum	`per-project-tagged`	global = one shared bank; per-project = isolated bank per cwd; per-project-tagged = shared bank with project tags so global + project memories merge on recall. Values: `global`, `per-project`, `per-project-tagged`.
`hindsight.autoRecall`	Hindsight Auto Recall	boolean	`true`	Recall memories on the first turn of each session.
`hindsight.autoRetain`	Hindsight Auto Retain	boolean	`true`	Retain transcript every N turns and at session boundaries.
`hindsight.retainMode`	Hindsight Retain Mode	enum	`full-session`	full-session = upsert one document per session, last-turn = chunked. Values: `full-session`, `last-turn`.
`hindsight.mentalModelsEnabled`	Hindsight Mental Models	boolean	`true`	Read curated reflect summaries (mental models) into developer instructions at boot. Loads existing models on the bank — does not write. Pair with hindsight.mentalModelAutoSeed to also auto-create the built-in seed set.
`hindsight.mentalModelAutoSeed`	Hindsight Mental Model Auto-Seed	boolean	`true`	At session start, create any built-in mental models (project-conventions, project-decisions, user-preferences) that do not yet exist on the bank.

Files

Editing

Key	Setting	Type	Default	What it does
`edit.mode`	Edit Mode	enum	`hashline`	Select the edit tool variant (replace, patch, hashline, or apply_patch). Values: `apply_patch`, `hashline`, `patch`, `replace`.
`edit.fuzzyMatch`	Fuzzy Match	boolean	`true`	Accept high-confidence fuzzy matches for whitespace differences.
`edit.fuzzyThreshold`	Fuzzy Match Threshold	number	`0.95`	Similarity threshold (0-1) for accepting fuzzy matches.
`edit.streamingAbort`	Abort on Failed Preview	boolean	`false`	Abort streaming edit tool calls when patch preview fails.
`edit.blockAutoGenerated`	Block Auto-Generated Files	boolean	`true`	Prevent editing of files that appear to be auto-generated (protoc, sqlc, swagger, etc.).
`edit.afterEdit`	After an Edit	enum	`verify`	What happens when a turn ends having changed files: verify runs one check when none followed the last edit, review reads back every file the turn changed and judges correctness, maintainability and cross-file contracts, off ends the turn where the model ends it. Values: `verify`, `review`, `off`.

Reading

Key	Setting	Type	Default	What it does
`readLineNumbers`	Line Numbers	boolean	`false`	Prepend line numbers to read tool output by default.
`read.defaultLimit`	Default Read Limit	number	`300`	Line count returned when read is called without one. The window also stops at the tool output budget, so a file of long lines returns fewer lines than this.
`read.toolResultPreview`	Inline Read Previews	boolean	`false`	Render read tool results inline in the transcript instead of summary rows.

Read Summaries

Key	Setting	Type	Default	What it does
`read.summarize.enabled`	Enable Read Summaries	boolean	`true`	Return structural code summaries when read is called without an explicit selector.
`read.summarize.prose`	Prose Summaries	boolean	`false`	Return structural summaries for Markdown and plain text reads.
`read.summarize.minBodyLines`	Read Summary Body Lines	number	`4`	Minimum multiline body or literal length before read summaries collapse it.
`read.summarize.minCommentLines`	Read Summary Comment Lines	number	`6`	Minimum multiline block comment length before read summaries collapse it.
`read.summarize.minTotalLines`	Read Summary Minimum File Length	number	`100`	Files with fewer total lines are read verbatim instead of structurally summarized.
`read.summarize.unfoldUntil`	Read Summary Unfold Target	number	`50`	BFS-unfold elidable spans until the summary is at least this many visible lines. 0 keeps only the outermost elisions.
`read.summarize.unfoldLimit`	Read Summary Unfold Ceiling	number	`100`	Hard ceiling on summary size while BFS-unfolding. An unfold whose revealed lines would exceed this is skipped (that span stays folded) and unfolding continues with the remaining spans.

LSP

Key	Setting	Type	Default	What it does
`lsp.enabled`	Language Servers	boolean	`false`	Start language servers. Files → LSP is the row you enter; this switch and the others on that page (agent tool, diagnostics after write, diagnostics after edit, format after write) are independent once servers are running.
`lsp.tool`	Agent Tool	boolean	`true`	Give the agent the lsp tool (definitions, references, rename, query diagnostics). Off keeps servers for format and injected diagnostics only.
`lsp.lazy`	Lazy Startup	boolean	`true`	Start language servers on first use (lsp tool or editing a matching file type) instead of at session startup.
`lsp.formatOnWrite`	Format after Write	boolean	`false`	Format the file with the language server after the write tool saves it. Independent of the agent tool and of diagnostics.
`lsp.diagnosticsOnWrite`	Diagnostics after Write	boolean	`true`	After the write tool saves a file, inject language-server diagnostics into the session. Independent of the agent tool.
`lsp.diagnosticsOnEdit`	Diagnostics after Edit	boolean	`false`	After the edit tool saves a file, inject language-server diagnostics into the session. Independent of the agent tool.
`lsp.diagnosticsDeduplicate`	Deduplicate Diagnostics	boolean	`true`	Suppress post-edit LSP diagnostics already shown for a file; only surface new or changed ones.

Shell

Bash

Key	Setting	Type	Default	What it does
`bash.enabled`	Enable Bash	boolean	`true`	Enable the bash tool for shell command execution.
`bash.stallDetection.enabled`	Bash Stall Detection	boolean	`false`	Watch for a bash command that stops producing output; background it and tell the model it may be stuck so it can cancel a truly hung command. Recommends, never force-kills.
`bashInterceptor.enabled`	Bash Interceptor	boolean	`false`	Block shell commands that have dedicated tools.
`shellMinimizer.enabled`	Shell Minimizer	boolean	`true`	Compress verbose shell output (git, npm, cargo, etc.) before returning it to the agent.
`shellMinimizer.sourceOutlineLevel`	Shell Minimizer Source Outline	enum	`default`	Source outline mode for cat/read of source files: default or aggressive. Values: `default`, `aggressive`.
`bash.autoBackground.enabled`	Bash Auto-Background	boolean	`true`	Move a long-running bash command to a background job on its own and deliver the result when it lands, instead of holding the turn open. Off, a command holds the foreground until it finishes or times out. Either way you can background the running command yourself with the composer’s background key.
`bash.autoBackground.thresholdMs`	Auto-Background After	number	`300000`	Max wall-clock time a bash call runs in the foreground before it is moved to a background job (result delivered later). Frees the model to keep working and protects the prompt cache, which a long foreground command would otherwise blow past. Fires on elapsed time even while output is streaming. 0 backgrounds immediately.
`bash.stallDetection.stallMs`	Stall After	number	`30000`	When stall detection is on, how long a bash call may produce no new output before it is treated as possibly stuck, backgrounded, and flagged so the model can cancel it if it is truly hung. Measures idle time (quiet output), not total run time.

Eval & Runtimes

Key	Setting	Type	Default	What it does
`eval.py`	Python Eval Backend	boolean	`true`	Allow the eval tool to dispatch Python cells to the IPython kernel.
`eval.js`	JavaScript Eval Backend	boolean	`true`	Allow the eval tool to dispatch JavaScript cells to the in-process runtime.
`eval.rb`	Ruby Eval Backend	boolean	`false`	Allow the eval tool to dispatch Ruby cells to the persistent Ruby kernel.
`eval.jl`	Julia Eval Backend	boolean	`false`	Allow the eval tool to dispatch Julia cells to the persistent Julia kernel.
`ruby.kernelMode`	Ruby Kernel Mode	enum	`session`	Keep the Ruby kernel alive across eval calls or start fresh each time. Values: `session`, `per-call`.
`julia.kernelMode`	Julia Kernel Mode	enum	`session`	Keep the Julia kernel alive across eval calls or start fresh each time. Values: `session`, `per-call`.
`python.kernelMode`	Python Kernel Mode	enum	`session`	Keep the IPython kernel alive across eval calls or start fresh each time. Values: `session`, `per-call`.
`python.interpreter`	Python Interpreter	string	(empty)	Optional path to an exact Python executable. When set, automatic Python runtime discovery is skipped.
`ruby.interpreter`	Ruby Interpreter	string	(empty)	Optional path to an exact Ruby executable. When set, automatic Ruby runtime discovery is skipped.
`julia.interpreter`	Julia Interpreter	string	(empty)	Optional path to an exact Julia executable. When set, automatic Julia runtime discovery is skipped.

Tools

Available Tools

Key	Setting	Type	Default	What it does
`todo.enabled`	Todos	boolean	`true`	Enable the todo tool for task tracking.
`astEdit.enabled`	AST Edit	boolean	`true`	Enable the ast_edit tool for structural AST rewrites.
`debug.enabled`	Debug	boolean	`true`	Enable the debug tool for DAP-based debugging. The tool loads only where a configured adapter command resolves.
`launch.enabled`	Launch	boolean	`true`	Enable the launch tool for supervising shared long-running project processes.
`speechgen.enabled`	Speech Generation	boolean	`false`	Enable the tts tool for on-device (Kokoro) or xAI Grok Voice speech-file synthesis.
`generate_image.enabled`	Generate Image	boolean	`false`	Enable the generate_image tool for text-to-image generation and editing.
`inspect_image.enabled`	Inspect Image	boolean	`false`	Enable the inspect_image tool, delegating image understanding to a vision-capable model.
`checkpoint.enabled`	Checkpoint/Rewind	boolean	`false`	Enable the checkpoint and rewind tools for context checkpointing.
`fetch.enabled`	Read URLs	boolean	`true`	Allow the read tool to fetch and process URLs.
`vault.enabled`	Obsidian Vault	boolean	`false`	Enable the vault:// internal URL for reading and editing Obsidian vault content via the Obsidian CLI. When disabled, vault:// resolution is refused and the vault:// entry is omitted from the system prompt.
`github.enabled`	GitHub CLI	boolean	`false`	Enable the github tool (op-based dispatch for repository, issue, pull request, diff, search, checkout, push, and Actions watch workflows).
`web_search.enabled`	Web Search	boolean	`true`	Enable the web_search tool for live web results.
`ask.enabled`	Ask	boolean	`true`	Enable the ask tool for interactive user questions.
`browser.enabled`	Browser	boolean	`false`	Enable the browser tool for scripted Chromium automation (puppeteer).

Todos

Key	Setting	Type	Default	What it does
`todo.reminders`	Todo Reminders	boolean	`true`	Prompt continued execution when unfinished todos remain.
`todo.reminders.max`	Todo Reminder Limit	number	`3`	Maximum distinct todo-state reminders before reminders stay silent.
`todo.eager`	Create Todos Automatically	enum	`default`	How strongly to push automatic todo-list creation after the first message. Values: `default`, `preferred`, `always`.
`tasks.todoClearDelay`	Todo Auto-Clear Delay	number	`-1`	Delay before completed or abandoned todos are removed from the todo widget.

Launch

Key	Setting	Type	Default	What it does
`launch.cleanupWaitMs`	Launch Cleanup Wait	number	`900000`	How long an exited process record is retained before being purged from memory and disk (0 = never clean up).

Search Context

Key	Setting	Type	Default	What it does
`search.contextBefore`	Text Context Before	number	`1`	Lines of context before each text search match.
`search.contextAfter`	Text Context After	number	`1`	Lines of context after each text search match.

Browser

Key	Setting	Type	Default	What it does
`browser.headless`	Headless Browser	boolean	`true`	Launch browser in headless mode (disable to show browser UI).
`browser.cmux`	cmux Browser	boolean	`true`	Use cmux WKWebView surfaces for browser automation when a cmux socket is available. Set VEYYON_BROWSER_CMUX=0 or VEYYON_BROWSER_CMUX=1 to override.
`browser.screenshotDir`	Screenshot Directory	string	(unset)	Directory to save screenshots. If unset, screenshots go to a temp file. Supports ~. Examples: ~/Downloads, ~/Desktop, /sdcard/Download (Android).

GitHub

Key	Setting	Type	Default	What it does
`github.cache.enabled`	GitHub View Cache	boolean	`true`	Cache rendered issue/PR view output in the active profile’s `cache/github-cache.db` so repeated reads are free.
`github.cache.softTtlSec`	GitHub Cache Soft TTL	number	`300`	Within this window, cached issue/PR view rows are returned directly (seconds; default 5 minutes).
`github.cache.hardTtlSec`	GitHub Cache Hard TTL	number	`604800`	Past the soft TTL the cached row is returned and refreshed in the background; past the hard TTL it is dropped (seconds; default 7 days).

Output Limits

Key	Setting	Type	Default	What it does
`tools.artifactSpillThreshold`	Artifact Spill Threshold (KB)	number	`50`	Tool output above this size is saved as an artifact and the result keeps a head/tail window no larger than this size, plus the artifact:// id that reads the full text back, so a lower threshold costs a re-read rather than losing output. It governs every tool that streams output, including bash, eval, ssh and the interactive shell, as well as search and the browser.
`tools.artifactTailBytes`	Artifact Tail Size (KB)	number	`20`	Amount of tail content kept inline when output spills to artifact, bounded by the spill threshold.
`tools.artifactHeadBytes`	Artifact Head Size (KB)	number	`20`	Amount of head content kept inline alongside the tail when output spills to artifact (middle elision), bounded with the tail by the spill threshold. 0 disables — keep tail only.
`tools.outputMaxColumns`	Output Column Cap	number	`768`	Per-line byte cap for streaming tool outputs (bash, ssh, python, js eval) and `read`. Lines wider than this are ellipsis-truncated; remaining bytes up to the next newline are dropped. 0 disables.
`tools.artifactTailLines`	Artifact Tail Lines	number	`500`	Maximum lines of tail content kept inline when output spills to artifact.
`tools.inlineOutputFloor`	Inline Output Floor	number	`0.25`	Smallest share of the inline output budget an early tool result may use before the rest spills to an artifact. A result that arrives early is re-read on every later turn, so it is charged more tightly than one that arrives near the end. Lower spills sooner and costs fewer context tokens; 1 keeps the flat cap and never spills early. This governs every tool that streams output, including eval, bash, ssh and the interactive shell, as well as search and the browser. Shown under the tab’s Advanced fold.

Execution

Key	Setting	Type	Default	What it does
`tools.intentTracing`	Intent Tracing	boolean	`true`	Ask the agent to describe the intent of each tool call before executing it.
`tools.abortOnFabricatedResult`	Abort On Fabricated Tool Result	boolean	`true`	With in-band tool calls, stop the model immediately when it starts hallucinating a tool result mid-turn. Disable to let the model finish generating and discard the fabricated continuation instead.
`tools.maxTimeout`	Max Tool Timeout	number	`0`	Maximum timeout in seconds the agent can set for any tool (0 = no limit).
`async.enabled`	Async Execution	boolean	`true`	Enable async bash commands and background task execution.
`async.pollWaitDuration`	Max Poll Time	enum	`smart`	How long the poll tool waits for background job updates before returning the current state. A fixed value waits that exact duration every time. `smart` adapts: it starts at 30s and climbs to 4m on a back-to-back poll, then resets to 30s after about a minute without polling. The 4m ceiling stays below the 5-minute prompt-cache boundary. Values: `5s`, `10s`, `30s`, `1m`, `5m`, `smart`.

Discovery & MCP

Key	Setting	Type	Default	What it does
`tools.discoveryMode`	Tool Discovery	enum	`auto`	Hide tools behind a search tool to save tokens. ‘auto’ hides MCP tools once the tool set has more than 40 tools; ‘mcp-only’ always hides MCP tools; ‘all’ also hides non-essential built-ins and first-party heavyweight tools such as generate_image. Values: `auto`, `off`, `mcp-only`, `all`.
`tools.essentialOverride`	Essential Tools Override	array	`[]`	Override the always-loaded built-in tools (default: read, bash, launch, edit, write, search, eval). Leave empty to use defaults.
`mcp.discoveryMode`	MCP Tool Discovery	boolean	`false`	Hide MCP tools by default and expose them through a tool discovery tool.
`mcp.discoveryDefaultServers`	MCP Discovery Default Servers	array	`[]`	Keep MCP tools from these servers visible while discovery mode hides other MCP tools.
`mcp.notifications`	MCP Update Injection	boolean	`false`	Inject MCP resource updates into the agent conversation.
`mcp.notificationDebounceMs`	MCP Notification Debounce	number	`500`	Debounce window in milliseconds for MCP resource updates before injecting them into the conversation.

Developer

Key	Setting	Type	Default	What it does
`dev.autoqa`	Auto QA	boolean	`false`	Record unexpected built-in tool behavior in this profile’s local grievance database.
`dev.autoqaPush.enabled`	Auto-upload Grievances	boolean	`false`	Send new and queued grievances to veyyon.dev after recording them. Off keeps reports local until you run veyyon grievances push.
`dev.autoqaPush.endpoint`	Grievance Upload Endpoint	string	`https://veyyon.dev/api/grievances`	Destination for automatic and manual grievance uploads.

Tasks

Modes

Key	Setting	Type	Default	What it does
`plan.enabled`	Plan Mode	boolean	`true`	Enable plan mode for read-only exploration and planning before execution.
`plan.defaultOnStartup`	Start in Plan Mode	boolean	`false`	Automatically enter plan mode at the start of every new session.
`goal.enabled`	Goal Mode	boolean	`true`	Enable per-session goal mode and the hidden goal tool.
`goal.modelBudgetsEnabled`	Model Goal Budgets	boolean	`false`	Expose and enforce persisted per-goal token budgets for the model. This control is available only in Settings.
`goal.statusInFooter`	Goal Progress Bar in Footer	boolean	`true`	Add a compact progress bar next to the goal token count in the status line. The token count is always shown; this controls the extra bar.
`goal.continuationModes`	Goal Continuation Modes	array	`["interactive"]`	Run modes where active goals may auto-continue between turns.
`title.refreshOnReplan`	Refresh Title on Replan	boolean	`true`	Refresh generated session titles after todo init replans unless the title was set by the user.

Commands & Skills

Key	Setting	Type	Default	What it does
`skills.enableSkillCommands`	Skill Commands	boolean	`true`	Register skills as /skill:name commands.
`commands.enableClaudeUser`	Claude User Commands	boolean	`true`	Load commands from ~/.claude/commands/.
`commands.enableOpencodeUser`	OpenCode User Commands	boolean	`true`	Load commands from ~/.config/opencode/commands/.

Subagents

Delegation

Key	Setting	Type	Default	What it does
`subagent.enabled`	Subagents	boolean	`true`	Whether this session may use subagents at all. Off removes the task tool and every delegation instruction from the prompt, so nothing can be spawned. This is the only setting that takes the ability away: Subagent Delegation below decides how hard the model is PUSHED to delegate, never whether it may. Your delegation strength and your Roster are kept while this is off and take effect again when you turn it back on.
`subagent.delegation`	Subagent Delegation	enum	`preferred`	How strongly this session routes work to the subagent types you enabled. Allowed leaves delegation available without prompting for it. Preferred asks for substantial eligible work to be delegated. Required adds a first-turn reminder. The enabled Roster is the routing policy: each name is a distinct type that owns only work matching its description, no type is a fallback for another, and work no enabled type covers stays with the main agent. Turn Subagents off above to remove delegation entirely. Values: `allowed`, `preferred`, `required`.
`subagent.batch`	Batch Task Calls	boolean	`true`	Switch the task tool to its batch shape: one call carries { agent, context, tasks[] } — one subagent per item (with per-item isolation) and a required shared context prepended to every assignment. With async.enabled=true, each spawn runs as an independent background agent with the normal idle/parked lifecycle; otherwise the call blocks for merged results. Disable to restore the flat single-spawn schema. Shown under the tab’s Advanced fold.

Subagents

Key	Setting	Type	Default	What it does
`subagent.agents`	Roster	record	`{}`	Which subagent types the model may choose, and what each one runs. Enabled means the model can pick that subagent on its own; disabled means it cannot. With no row, only the general-purpose deep worker is enabled. Bundled specialists and subagents you add are opt-in through onboarding or this roster. Each subagent’s page carries its own Model and Effort, and a Subagents chain naming what it may spawn in turn, level by level; unset anywhere follows the level above, and an agent that names nothing runs the default model role. Same Model for All Subagents below replaces the per-agent Model and Effort rows with one pair for the whole roster.
`subagent.maxNestedSpawnDepth`	Max Nested Spawn Depth	number	`0`	How many nested levels subagents may spawn, for every level no roster chain decides. 0 still lets this session spawn direct subagents, but those children do not receive the task tool. Open Roster above, pick a subagent, then Subagents, to turn individual levels on or off for that one; this number answers from the first level its chain does not name.
`subagent.sharedModel`	Same Model for All Subagents	boolean	`false`	Run every subagent on one model and one effort instead of choosing per agent. Off, each agent’s page decides. On, the two rows below decide for the whole roster and the per-agent Model and Effort rows are hidden; what those rows hold is kept and comes back when this goes off.
`subagent.model`	Shared Model	modelChain	(unset)	The model chain every subagent runs while Same Model for All Subagents is on. Unset falls back to the default model role, the same model a new session starts on.
`subagent.thinkingLevel`	Shared Effort	string	(unset)	The effort every subagent runs at while Same Model for All Subagents is on. Narrowed to what the model above declares; a `:level` suffix on the chain still wins. Inherit leaves the documented default.
`subagent.showResolvedModelBadge`	Show Resolved Model Badge	boolean	`true`	Show each subagent’s resolved model, and the setting that decided it, in the task widget status line and the agent surfaces. Shown under the tab’s Advanced fold.

Limits

Key	Setting	Type	Default	What it does
`subagent.maxConcurrency`	Max Concurrent Subagents	number	`32`	Maximum number of subagents running concurrently.
`subagent.maxRuntimeMs`	Max Subagent Runtime	number	`0`	Hard wall-clock limit per subagent (ms). 0 disables it. Defense-in-depth against provider-side stream hangs that escape the inference-layer watchdog; triggers a normal subagent abort with a ‘timed out’ reason.
`subagent.softRequestBudget`	Soft Request Budget	number	`200`	Soft per-subagent request budget (assistant requests per run). Crossing it injects a wrap-up steering notice (see the notice setting below); at 1.5x the budget the run is force-stopped and the agent must yield its partial findings. 0 disables the guard. Bundled scout/sonic agents use a lower built-in budget.
`subagent.softRequestBudgetNotice`	Soft Request Budget Notice	boolean	`true`	Inject one steering notice when a subagent crosses its soft request budget, asking it to wrap up before the 1.5x forced-yield stop.
`subagent.enableLsp`	LSP in Subagents	boolean	`false`	Allow spawned subagents to use the lsp tool. Off by default to keep subagents cheap; enable when LSP-aware delegation is worth the extra tokens.

Park

Key	Setting	Type	Default	What it does
`subagent.idleTtlMs`	Park After	number	`300000`	Stage one. How long a finished subagent stays live before it parks (ms). Parking releases the live session — the process, its MCP clients, its memory — and keeps everything else: the row stays in the roster and the agent rebuilds itself when messaged or opened. Counted from the agent’s last activity, so a revived agent starts this budget again from the revival. ‘Until exit’ keeps idle agents live for the whole session.

Prune

Key	Setting	Type	Default	What it does
`subagent.prune.enabled`	Prune Parked Subagents	boolean	`true`	Stage two, and a different thing from parking. Pruning takes a parked subagent out of the roster and gives up the ability to wake it; parking only released its session. Nothing on disk is touched: the transcript stays where it is and stays readable at `history://\<agent>`. Off keeps every parked subagent listed and wakeable until you exit.
`subagent.prune.afterMs`	Prune After	number	`3600000`	How long a parked subagent stays in the roster before it is pruned (ms). Counted from its last activity, so a subagent read back from a previous run is judged on when its transcript was last written rather than on when this session found it.
`subagent.prune.waitingAfterMs`	Prune After While Waiting	number	`7200000`	The same budget for a subagent whose last message said it was waiting on another agent (ms). It stopped on purpose to let a peer finish, so it keeps its row longer than one that simply went quiet: pruning it on the ordinary budget would drop the agent you are most likely to message next. Set it equal to Prune After to treat both the same; a shorter value is raised to it.

Isolation

Key	Setting	Type	Default	What it does
`subagent.isolation.mode`	Isolation Mode	enum	`none`	Isolation backend for subagents. “auto” lets the native PAL pick the best available backend (CoW-aware filesystems, then overlayfs/ProjFS, then a git worktree / recursive-copy fallback). Values: `none`, `auto`, `apfs`, `btrfs`, `zfs`, `reflink`, `overlayfs`, `projfs`, `block-clone`, `rcopy`.
`subagent.isolation.merge`	Isolation Merge Strategy	enum	`patch`	How isolated subagent changes are integrated (patch apply or branch merge). Values: `patch`, `branch`.
`subagent.isolation.commits`	Isolation Commit Style	enum	`generic`	Commit message style for nested repo changes (generic or AI-generated). Values: `generic`, `ai`.
`worktree.base`	Worktree Base Directory	string	(unset)	Base directory for agent-managed worktrees: subagent isolation copies, `github` PR checkouts, and `veyyon worktree` cleanup all live here. Unset uses the active profile’s `wt/` directory (~/.veyyon/profiles/<name>/wt, or its XDG data equivalent). Must be an absolute or ~-relative path; relative paths are ignored. The VEYYON_WORKTREE_DIR env var overrides this.

Coordination

Key	Setting	Type	Default	What it does
`irc.timeoutMs`	IRC Timeout	number	`120000`	Default timeout for irc wait (and send await:true) in milliseconds; 0 disables the timeout. IRC is how a parent and its subagents talk, which is why it is configured here.

Providers

Accounts

Key	Setting	Type	Default	What it does
`accounts.loadBalancing`	Account Load Balancing	boolean	`false`	Off: only the account you chose is used, and a session waits out its quota window. On: when that account hits its quota or rate limit, continue on another account of the same provider and say so. A revoked account always fails over regardless, with a notice.

Services

Key	Setting	Type	Default	What it does
`providers.maxInFlightRequests`	Max In-Flight Requests	record	`{}`	Maximum concurrent LLM requests per provider id (for example “openai” or “anthropic”), shared across local veyyon processes with this config root. Omitted providers are unlimited.
`providers.ollama-cloud.maxConcurrency`	Ollama Cloud Max Concurrency	number	`3`	Maximum concurrent Ollama Cloud subagent runs per process; 0 disables the provider-specific limit.
`providers.webSearch`	Web Search Provider	enum	`auto`	The provider web_search uses; auto tries each in turn. Values: `auto`, `perplexity`, `gemini`, `anthropic`, `codex`, `xai`, `zai`, `exa`, `tinyfish`, `jina`, `kagi`, `tavily`, `firecrawl`, `brave`, `kimi`, `parallel`, `synthetic`, `searxng`, `startpage`, `duckduckgo`, `google`, `mojeek`, `public`.
`providers.webSearchExclude`	Excluded Web Search Providers	array	`[]`	Providers that web_search should never use, even as fallbacks.
`providers.webSearchGeminiModel`	Gemini web_search model	string	(unset)	Model ID for Gemini Google Search grounding. Defaults to gemini-2.5-flash.
`providers.antigravityEndpoint`	Antigravity Endpoint Mode	enum	`auto`	Endpoint routing strategy for google-antigravity providers (chat, search, image, discovery). Values: `auto`, `production`, `sandbox`.
`providers.image`	Image Provider	enum	`auto`	Preferred provider for image generation. Values: `auto`, `openai`, `antigravity`, `xai`, `gemini`, `openrouter`.
`providers.tts`	Text-to-Speech Provider	enum	`auto`	Backend for the tts tool: local on-device neural TTS (Kokoro-82M) or xAI Grok Voice. Values: `auto`, `local`, `xai`.
`tts.localModel`	Local TTS Model	enum	`kokoro`	On-device neural TTS model (Kokoro-82M) used by the local TTS backend. Values: `kokoro`.
`tts.localVoice`	Local TTS Voice	enum	`af_heart`	Kokoro voice used by the local TTS backend (American/British, female/male). Values: `af_heart`, `af_bella`, `af_nicole`, `af_aoede`, `af_kore`, `af_sarah`, `am_michael`, `am_fenrir`, `am_puck`, `bf_emma`, `bm_george`, `bm_fable`.
`speech.enabled`	Speech Vocalization	boolean	`false`	Speak the assistant’s output aloud through the speakers as it streams.
`speech.mode`	Speech Vocalization Mode	enum	`assistant`	What to speak: all = assistant messages + thinking; assistant = messages only; yield = only the final message at turn end. Values: `all`, `assistant`, `yield`.
`speech.enhanced`	Enhanced Speech Rewriting	boolean	`false`	Rewrite assistant output into natural spoken prose with the tiny/smol model before synthesis (describes code, drops links and markdown). Falls back to mechanical cleanup on failure.
`speech.voice`	Speech Vocalization Voice	enum	`af_heart`	Kokoro voice used when speaking the assistant’s output aloud. Values: `af_heart`, `af_bella`, `af_nicole`, `af_aoede`, `af_kore`, `af_sarah`, `am_michael`, `am_fenrir`, `am_puck`, `bf_emma`, `bm_george`, `bm_fable`.
`providers.fetch`	Fetch Provider	enum	`auto`	Reader backend priority for the fetch/read URL tool. Values: `auto`, `native`, `trafilatura`, `lynx`, `parallel`, `jina`.
`codexResets.autoRedeem`	Codex Auto-Redeem Saved Resets	enum	`unset`	When a turn is blocked by the Codex weekly limit on the active account and no other account is available, run the conservative saved-reset check. unset asks before spending the first eligible reset, yes spends eligible resets without prompting, and no disables the check entirely. Requires retries enabled. Values: `unset`, `yes`, `no`.
`codexResets.minBlockedMinutes`	Codex Auto-Redeem Min Block	number	`60`	Only auto-redeem when the natural weekly reset is at least this many minutes away (don’t spend a ~30-day credit to save a short wait).
`codexResets.keepCredits`	Codex Auto-Redeem Reserve	number	`0`	Never auto-spend below this many saved resets (0 = the last credit may be spent automatically).
`exa.enabled`	Exa	boolean	`true`	Master toggle for all Exa search tools.
`exa.enableSearch`	Exa Search	boolean	`true`	Enable Exa basic search, deep search, code search, and crawl tools.
`exa.searchDelayMs`	Exa Search Delay	number	`1000`	Minimum delay between Exa web search requests in milliseconds; set 0 to disable pacing.
`exa.enableResearcher`	Exa Researcher	boolean	`false`	Enable the Exa researcher tool for AI-powered deep research.
`exa.enableWebsets`	Exa Websets	boolean	`false`	Enable Exa webset management and enrichment tools.
`searxng.endpoint`	SearXNG Endpoint	string	(unset)	Base URL of a self-hosted SearXNG instance used for web search.

Discovery

Key	Setting	Type	Default	What it does
`discovery.importForeignConfig`	Import Other Tools’ Config	boolean	`false`	Auto-discover skills, context files, rules, and MCP servers authored for other AI tools (Claude, Codex, Gemini, Cursor, opencode, and more) found on disk. Off by default: veyyon runs on its own instruction layers only (the system prompt, the global ~/.veyyon/AGENTS.md, the active profile’s AGENTS.md, and the project’s own AGENTS.md/CLAUDE.md walked from the repo root down to cwd), and never ambiently picks up a foreign tool’s own config directory, GEMINI.md, or the skills, rules and MCP servers those tools define. Turn on to import them as a base layer.

Fireworks

Key	Setting	Type	Default	What it does
`providers.fireworksTier`	Fireworks Tier	enum	`standard`	Serving path for Fireworks requests. Priority sends `service_tier: "priority"` for higher reliability during peak traffic at a higher price; Standard omits it. Fast (`-fast`) models ignore this — Fast is its own serving path. Values: `standard`, `priority`.

Tiny Model

Key	Setting	Type	Default	What it does
`providers.tinyModel`	Session Title Model	enum	`online`	Session-title model: online (the TINY role from /models, else @smol) by default, or a local on-device model. Values: `online`, `lfm2-350m`, `qwen3-0.6b`, `gemma-270m`, `qwen2.5-0.5b`, `lfm2-700m`.
`providers.tinyModelDevice`	Tiny Model Device	enum	`default`	ONNX execution provider for local tiny models (titles + memory). Default uses CPU-only inference. The VEYYON_TINY_DEVICE env var overrides this. Values: `default`, `gpu`, `cpu`, `metal`, `webgpu`, `cuda`, `dml`, `coreml`, `auto`, `wasm`, `webnn`, `webnn-gpu`, `webnn-cpu`, `webnn-npu`.
`providers.tinyModelDtype`	Tiny Model Precision	enum	`default`	ONNX quantization/precision for local tiny models. Default uses each model’s shipped dtype (q4); lower precision is faster, higher is more faithful. The VEYYON_TINY_DTYPE env var overrides this. Values: `default`, `q4`, `q4f16`, `q8`, `fp16`, `fp32`, `int8`, `uint8`, `bnb4`, `q2`, `q2f16`, `q1`, `q1f16`, `auto`.
`providers.unexpectedStopModel`	Unexpected Stop Model	enum	`online`	Classifier for unexpected-stop detection: online (the TINY role from /models, else smol) by default, or a local on-device model. Values: `online`, `qwen3-1.7b`, `llama3.2:3b`, `gemma-3-1b`, `qwen2.5-1.5b`, `lfm2-1.2b`.

Protocol

Key	Setting	Type	Default	What it does
`providers.kimiApiFormat`	Kimi API Format	enum	`anthropic`	API format for Kimi Code provider. Values: `openai`, `anthropic`.
`providers.openaiWebsockets`	OpenAI WebSockets	enum	`auto`	Websocket policy for OpenAI Codex models (auto uses model defaults, on forces, off disables). Values: `auto`, `off`, `on`.
`providers.openrouterVariant`	OpenRouter Routing	enum	`default`	Default routing-variant suffix appended to OpenRouter model IDs (overridden when the selector already names a variant). Values: `default`, `nitro`, `floor`, `online`, `exacto`.
`provider.appendOnlyContext`	Append-Only Context	enum	`auto`	Cache system prompt + tool specs and keep an append-only message log so provider prefix caches (DeepSeek, Xiaomi/SGLang, Anthropic) hit at maximum rate. Auto enables for known prefix-cache providers. Values: `auto`, `on`, `off`.

Timeouts

Key	Setting	Type	Default	What it does
`providers.streamFirstEventTimeoutSeconds`	Stream First Event Timeout	number	`-1`	Seconds to wait for the first model stream event; -1 uses provider/env defaults, 0 disables the watchdog.
`providers.streamIdleTimeoutSeconds`	Stream Idle Timeout	number	`-1`	Seconds a model stream may stay silent between events; -1 uses provider/env defaults, 0 disables the watchdog.

Privacy

Key	Setting	Type	Default	What it does
`images.blockImages`	Block Images	boolean	`false`	Prevent images from being sent to LLM providers.
`secrets.enabled`	Hide Secrets	boolean	`false`	Obfuscate secrets before sending to AI providers. Storing a credential with /secret turns this on for you.
`secrets.defaultTtl`	Secret Lifetime	string	`1d`	How long a /secret lasts when the command does not say. Default 1d; also accepts forms like 30m, 12h, 7d, 2w, or “never”.
`secrets.auditLog`	Record Secret Use	boolean	`true`	Append which secret was used in which command to the profile’s log. Never records values.
`secrets.expiryWarnings`	Warn Before A Secret Expires	boolean	`true`	Say at the start of a session when a stored secret is halfway through its lifetime, and again near the end. Off: /secret list still shows the STATUS column and the status line still shows a deadline in the last hour.

Experimental

Argot

Key	Setting	Type	Default	What it does
`argot.enabled`	Argot Shorthand	boolean	`false`	Let the agent load token-saving shorthand for the projects it works in, kept in a local cache (nothing is written to the repository). The project you launch in is loaded for you, and the model loads any further project with the argot_load tool; it then writes short handles that the harness expands to full text before any tool runs or the display shows them.
`argot.autoload`	Argot Startup Load	boolean	`true`	Load the project you started the session in, in the background, so shorthand works without the model spending a turn on it. Off, a session starts with no dictionary until the model calls argot_load itself. Either way a handle already written still expands.
`argot.encode.models`	Argot Models	array	`[]`	Models allowed to write Argot shorthand, by model id. Empty (the default) means no model does, so turning Argot on alone stays inert until you add one here. A model left off this list is never taught the shorthand; handles already in history still expand.
`argot.tokenBudget`	Argot Dictionary Budget	number	`1000`	How many tokens the generated Argot dictionary may spend on its handle table. A larger budget teaches more handles (more transcript savings) but adds a longer preamble each turn; a smaller budget teaches only the most central strings. Changing it regenerates the dictionary.
`argot.encode.disableAboveTokens`	Argot Context Cutoff	number	`-1`	Stop teaching Argot shorthand once context passes this many tokens (the model then writes in full). Handles already written still expand losslessly. -1 disables the cutoff.
`argot.subagents`	Argot in Subagents	enum	`off`	How a subagent starts with Argot shorthand. Correctness never depends on this (handles never cross the parent/child wire); it only trades tokens. off: no shorthand in subagents. fresh: the subagent loads its task’s project itself through argot_load. inherit: the subagent starts from a copy of the parent’s loaded shorthand. Values: `off`, `fresh`, `inherit`.

Tool Calling

Key	Setting	Type	Default	What it does
`tools.format`	Tool Calling Mode	enum	`auto`	Controls how tools are exposed to the model. Auto uses provider-native tool calls unless the selected model is marked as not supporting them, then falls back to the GLM owned dialect. Native forces provider-native tools; the other values force the named owned dialect. Applies on session start. Values: `auto`, `native`, `glm`, `hermes`, `kimi`, `xml`, `anthropic`, `deepseek`, `harmony`, `qwen3`, `gemini`, `gemma`, `minimax`, `pi-native`.

Auto-Learn

Key	Setting	Type	Default	What it does
`autolearn.enabled`	Enable Auto-Learn	boolean	`false`	After the agent stops, nudge it to capture lessons to memory and create/enhance isolated managed skills.
`autolearn.autoContinue`	Auto-run capture at stop	boolean	`false`	When on, auto-run one capture turn at stop (uses extra tokens). Off = passive reminder on your next turn.

Global

Machine Limits

Key	Setting	Type	Default	What it does
`machine.cpuLimitCores`	Machine CPU Limit	number	`0`	Maximum CPU every veyyon process on this machine may use TOGETHER, in cores (0 = no limit). Stored in ~/.veyyon/config.yml rather than in a profile, so it covers every profile and every veyyon running at once, which is what makes it a machine limit: held per profile, two profiles would read their own copy and the machine would get the sum. Each session’s budget group is created INSIDE this one, so on Linux the kernel caps the whole subtree and no combination of sessions can exceed it. A per-session limit larger than this one is bounded by it and does not raise it. The machine tier therefore needs a parent that delegates two levels; a host that delegates one, such as a container whose cgroup root holds processes, still holds per-session limits and reports the machine tier as unheld. Where the kernel cannot hold it, a notice says so once at startup rather than reporting a cap that does not exist. Stored machine-wide, not per profile.
`machine.memoryLimitGb`	Machine Memory Limit	number	`0`	Maximum memory every veyyon process on this machine may hold together, in gigabytes (0 = no limit). Stored in ~/.veyyon/config.yml, so it spans profiles and concurrent veyyon instances. Every session budget group sits inside this one, so on Linux this is cgroup v2 memory.max on the parent, with memory.swap.max pinned to 0 so the cap is the whole anonymous footprint rather than a resident cap a process escapes by swapping. The kernel reclaims, then OOM-kills, inside the subtree once the total is reached — whichever process the kernel picks, with no warning and no chance to finish. Set it where an OOM kill is preferable to the machine swapping. Where no memory controller is delegated the cap cannot be held, and a notice says so once at startup. Stored machine-wide, not per profile.
`machine.writeBudgetGb`	Machine Write Budget	number	`0`	Cumulative gigabytes every veyyon process on this machine may WRITE before further writes are refused (0 = no limit). Stored in ~/.veyyon/config.yml, so it spans profiles and concurrent veyyon instances. Unlike CPU and memory this is a total that accumulates, not a level: it counts bytes written since the machine budget was last reset, across every session, and refuses new commands and harness writes once the total is reached. A write budget is the one limit no kernel enforces on its own — cgroup io accounting MEASURES bytes and caps rate, not a lifetime total — so this is a refusal, and work already writing runs to completion. Stored machine-wide, not per profile.
`machine.maxProcesses`	Machine Max Processes	number	`0`	Hard cap on how many processes every veyyon on this machine may have alive at once (0 = no limit). Stored in ~/.veyyon/config.yml, so it spans profiles and concurrent veyyon instances. Every session budget group sits inside this one, so on Linux this is cgroup v2 pids.max on the parent and the kernel refuses the fork itself once the subtree is full, whichever session asked. Where pids is not delegated the cap is a refusal at the spawn path instead, and a notice says so once at startup. Stored machine-wide, not per profile.

Profiles

Key	Setting	Type	Default	What it does
`defaultProfile`	Default Profile	string	`default`	Profile used when no –profile flag or VEYYON_PROFILE is set. Stored in ~/.veyyon/config.yml. Use the profile name (`default` clears the override). Stored machine-wide, not per profile.
`onboardingVersion`	Onboarding Version	number	`0`	Setup generation this machine has already completed. Stored in ~/.veyyon/config.yml, so switching profile or working directory never re-runs onboarding. Stored machine-wide, not per profile.

Credentials

Key	Setting	Type	Default	What it does
`profileSharing`	Share Credentials Across Profiles	boolean	`true`	When on (the default), every profile reads one machine-wide set of provider logins. Turn off to give each profile its own private credential store. Changing this setting shuts down the active session; restart is required before any further model dispatch. Stored machine-wide, not per profile.

Auth Broker

Key	Setting	Type	Default	What it does
`authBrokerUrl`	Auth Broker URL	string	(empty)	Base URL of the auth broker that mints provider credentials for this machine. Stored in ~/.veyyon/config.yml under auth.broker.url; empty disables broker discovery via config. Stored machine-wide, not per profile.
`authBrokerToken`	Auth Broker Token	string	(empty)	Bearer token for the auth broker. Write-only: a stored token shows as a mask and is never echoed. Enter a new value to replace it, leave the mask to keep it, or clear the field to delete it. Stored machine-wide, not per profile.

Configuration file only

These keys are not in /settings. Some are state veyyon writes for itself (a schema version, an onboarding marker), some are credentials that belong in a secret store rather than on a settings screen, and the rest are shapes a selector cannot edit, such as a table of patterns. All of them are read by production code, all of them are valid in config.yml, and all of them can be set with veyyon config set.

Key	Type	Default	Notes
`async.maxJobs`	number	`100`
`auth.broker.token`	string	(unset)
`auth.broker.url`	string	(unset)
`autolearn.minToolCalls`	number	`5`
`bashInterceptor.patterns`	array	`[{"pattern":"^\\s(cat\|head\|tail\|less\|more)\\s+","tool":"read","message":"Use the` read`tool instead of cat/head/tail. It provides better context and handles binary files."},{"pattern":"^\\s(grep\|rg\|ripgrep\|ag\|ack)\\s+","tool":"search","message":"Use`search`with`type: "text"`instead of shell grep/rg."},{"pattern":"^\\s(find\|fd\|locate)\\s+.(-name\|-iname\|-type\|--type\|-glob)","tool":"search","message":"Use`search`with`type: "files"`instead of shell find/fd."},{"pattern":"^\\ssed\\s+(-i\|--in-place)","tool":"edit","message":"Use the`edit`tool instead of sed -i. It provides diff preview and fuzzy matching."},{"pattern":"^\\sperl\\s+.-[pn]?i","tool":"edit","message":"Use the`edit`tool instead of perl -i. It provides diff preview and fuzzy matching."},{"pattern":"^\\sawk\\s+.-i\\s+inplace","tool":"edit","message":"Use the`edit`tool instead of awk -i inplace. It provides diff preview and fuzzy matching."},{"pattern":"^\\s(echo\|printf\|cat\\s\<\<)\\s+(?:(?:[^\"'>]\|\"[^\"]\"\|'[^']')\|(?\<!\\\|)>{1,2}\\\|?\\s(?:\"/dev/(?:null\|tty\|stdout\|stderr)\"\|'/dev/(?:null\|tty\|stdout\|stderr)'\|/dev/(?:null\|tty\|stdout\|stderr))(?:[\\s;&\|]\|$))(?\<!\\\|)>{1,2}\\\|?\\s(?!(?:\"/dev/(?:null\|tty\|stdout\|stderr)\"\|'/dev/(?:null\|tty\|stdout\|stderr)'\|/dev/(?:null\|tty\|stdout\|stderr))(?:[\\s;&\|]\|$))[$\\w./~\"'-]","tool":"write","message":"Use the`write`tool instead of echo/cat redirection. It handles encoding and provides confirmation."},{"pattern":"^\\snohup\\s+\|(?\<!&)\\&\\s$","tool":"launch","message":"Use the`launch`tool instead of nohup or background shell syntax so the process stays observable and managed."},{"pattern":"^\\s(?:(?:bun\|npm\|pnpm\|yarn)\\s+(?:run\\s+)?(?:dev\|start)(?:\\s\|$)\|(?:vite\|next\\s+dev\|nuxt\\s+dev\|nodemon\|lldb\|gdb\|tail\\s+-f)(?:\\s\|$)\|docker\\s+compose\\s+up(?!.(?:\\s-d(?:\\s\|$)\|--detach))(?:\\s\|$))","tool":"launch","message":"Use the`launch`tool for services, watchers, and debuggers so other veyyon instances can observe and control them."},{"pattern":"^\\s(?:(?:bun\|npm\|pnpm\|yarn)\\s+(?:run\\s+)?\\S+\|cargo\\s+watch\|watchexec\|pytest\|vitest\|jest\|tsc)(?:.\|\\n)(?:--watch\|-w)(?:\\s\|$)","tool":"launch","message":"Use the`launch `tool for watch mode so its output, input, and lifecycle stay managed."}]`
`branchSummary.reserveTokens`	number	`16384`
`commit.changelogMaxDiffChars`	number	`120000`
`commit.mapReduceEnabled`	boolean	`true`
`commit.mapReduceMaxConcurrency`	number	`5`
`commit.mapReduceMaxFileTokens`	number	`50000`
`commit.mapReduceMinFiles`	number	`4`
`commit.mapReduceTimeoutMs`	number	`120000`
`compaction.autoContinue`	boolean	`true`
`compaction.dropUseless`	boolean	`true`
`compaction.enabled`	boolean	`true`
`compaction.handoffSaveToDisk`	boolean	`false`
`compaction.idleEnabled`	boolean	`false`
`compaction.idleThresholdTokens`	number	`200000`
`compaction.idleTimeoutSeconds`	number	`300`
`compaction.keepRecentTokens`	number	`10000`
`compaction.midTurnEnabled`	boolean	`true`
`compaction.remoteEndpoint`	string	(unset)
`compaction.reserveTokens`	number	(unset)
`compaction.supersedeReads`	boolean	`true`
`compaction.thresholdPercent`	number	`-1`	Retired: use `compaction.threshold` instead.
`compaction.thresholdTokens`	number	`-1`	Retired: use `compaction.threshold` instead.
`cycleOrder`	array	`["smol","slow"]`
`defaultThinkingLevel`	enum	`high`	Values: `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `auto`. Retired: use `defaultEffort` instead.
`dev.autoqaPush.token`	string	(unset)
`disabledExtensions`	array	`[]`
`disabledProviders`	array	`[]`
`edit.modelVariants`	record	`{}`
`enabledModels`	array	`[]`
`eval.pyWorkspace`	boolean	`false`
`extensions`	array	`[]`
`gc.archive`	boolean	`true`
`gc.blobs`	boolean	`true`
`gc.coldArchiveAfterDays`	number	`30`
`gc.retainNewestGlobal`	number	`20`
`gc.retainNewestPerCwd`	number	`10`
`gc.wal`	boolean	`true`
`gc.writeGraceMinutes`	number	`5`
`harness.profiles`	record	`{}`
`hindsight.apiToken`	string	(unset)
`hindsight.bankIdPrefix`	string	(unset)
`hindsight.bankMission`	string	(unset)
`hindsight.debug`	boolean	`false`
`hindsight.mentalModelMaxRenderChars`	number	`16000`
`hindsight.mentalModelRefreshIntervalMs`	number	`300000`
`hindsight.recallBudget`	enum	`mid`	Values: `low`, `mid`, `high`.
`hindsight.recallContextTurns`	number	`1`
`hindsight.recallMaxQueryChars`	number	`800`
`hindsight.recallMaxTokens`	number	`1024`
`hindsight.recallTimeoutMs`	number	`30000`
`hindsight.recallTypes`	array	`["world","experience"]`
`hindsight.reflectTimeoutMs`	number	`120000`
`hindsight.requestTimeoutMs`	number	`30000`
`hindsight.retainContext`	string	`veyyon`
`hindsight.retainEveryNTurns`	number	`3`
`hindsight.retainMission`	string	(unset)
`hindsight.retainOverlapTurns`	number	`2`
`hindsight.retainTimeoutMs`	number	`60000`
`memories.enabled`	boolean	`false`
`memories.fallbackTokenLimit`	number	`16000`
`memories.maxRawMemoriesForGlobal`	number	`200`
`memories.maxRolloutAgeDays`	number	`30`
`memories.maxRolloutsPerStartup`	number	`64`
`memories.minRolloutIdleHours`	number	`12`
`memories.phase1InputTokenLimit`	number	`4000`
`memories.phase2HeartbeatSeconds`	number	`30`
`memories.phase2LeaseSeconds`	number	`180`
`memories.phase2RetryDelaySeconds`	number	`180`
`memories.rolloutPayloadPercent`	number	`0.7`
`memories.stage1Concurrency`	number	`8`
`memories.stage1LeaseSeconds`	number	`120`
`memories.stage1RetryDelaySeconds`	number	`120`
`memories.summaryInjectionTokenLimit`	number	`5000`
`memories.threadScanLimit`	number	`300`
`mnemopi.debug`	boolean	`false`
`mnemopi.injectionTokenLimit`	number	`5000`
`mnemopi.recallContextTurns`	number	`3`
`mnemopi.recallLimit`	number	`8`
`mnemopi.recallMaxQueryChars`	number	`4000`
`mnemopi.retainEveryNTurns`	number	`4`
`modelProviderOrder`	array	`[]`
`modelTags`	record	`{}`
`retry.baseDelayMs`	number	`500`
`retry.enabled`	boolean	`true`
`searxng.basicPassword`	string	(unset)
`searxng.basicUsername`	string	(unset)
`searxng.categories`	string	(unset)
`searxng.language`	string	(unset)
`searxng.token`	string	(unset)
`settingsMigrationVersion`	number	`0`
`setupVersion`	number	`0`	Retired: use `onboardingVersion` instead.
`shellMinimizer.except`	array	`[]`
`shellMinimizer.legacyFilters`	boolean	(unset)
`shellMinimizer.maxCaptureBytes`	number	`4194304`
`shellMinimizer.only`	array	`[]`
`shellMinimizer.settingsPath`	string	(unset)
`shellPath`	string	(unset)
`skills.enabled`	boolean	`true`
`skills.ignoredSkills`	array	`[]`
`skills.includeSkills`	array	`[]`
`statusLine.leftSegments`	array	`[]`
`statusLine.rightSegments`	array	`[]`
`statusLine.segmentOptions`	record	`{}`
`statusLine.separator`	enum	`pipe`	Values: `powerline`, `powerline-thin`, `slash`, `pipe`, `block`, `none`, `ascii`.
`statusLine.transparent`	boolean	`true`
`stt.language`	string	`en`
`subagent.modelByDepth`	record	`{}`	Retired: use `subagent.agents` instead.
`thinkingBudgets.high`	number	`16384`
`thinkingBudgets.low`	number	`2048`
`thinkingBudgets.max`	number	`32768`
`thinkingBudgets.medium`	number	`8192`
`thinkingBudgets.minimal`	number	`1024`
`thinkingBudgets.xhigh`	number	`32768`
`ttsr.experimentalRules`	array	`[]`
`tui.maxInlineImageColumns`	number	`100`
`tui.maxInlineImageRows`	number	`20`
`tui.maxInlineImages`	number	`8`

353 settings in /settings, 121 configuration-file keys, 474 in all.

Keyboard shortcuts

The Veyyon Harness Handbook