Settings reference
ctrlyoke reads its settings from two settings.json files. Both use the same shape:
- User scope:
~/.ctrlyoke/settings.json. Applies to every workspace. - Workspace scope:
.ctrlyoke/settings.jsonin the workspace. Applies only to that workspace and overrides user values.
Objects merge key by key across the two files. An array or a single value in the workspace file replaces the user value entirely. The one exception is permissions.trustedExternalRoots: ctrlyoke combines the roots from both files. When you run the ctrlyoke CLI, the flags you pass override both files for that run.
Some settings are machine-specific and are read only from user scope: worktrees, storage, statusLine, usageTracking.enabled, languageServers.idleShutdownMinutes, languageServers.maxRunning, and languageServers.startOnLaunch. ctrlyoke ignores these settings in a workspace file.
Settings that run programs
Some settings choose a program for ctrlyoke to run:
terminal.shellExecutabledefaults.additionalArgsdefaults.hooks- the entries in
defaults.mcpServersthat launch a command defaults.endConditionanddefaults.preConditiondefaults.toolPermissions, when it grants more than your user value: a broader mode, an allowed tool your custom list lacks, a denied tool removed, ornone/nullwhile yours is a managed mode. A value that only narrows your permissions applies without asking.defaults.worktree, when it names asetupcommand different from your user value's. A value withoutsetupapplies without asking.- servers in the workspace MCP registry that launch a command
A repository can commit any of these in its .ctrlyoke/settings.json. So a workspace value takes effect only after you approve that exact value on your machine. Until then, ctrlyoke uses your user value, or the default.
- In VS Code, the dashboard asks when it opens. Check only the values you trust. Ask me later decides nothing.
- In the CLI,
ctrlyoke runasks in a terminal before it loads the workflow. Without a terminal, it exits with code2. Review the values withctrlyoke trust-workspace-settings, or approve them all with--yes.
You don't need to approve a value you saved through the dashboard's Settings page, or one that matches your user value. If the value in the file changes, ctrlyoke asks again. To change an earlier answer, run ctrlyoke: Review Workspace Settings That Run Programs from the Command Palette, or ctrlyoke trust-workspace-settings --all. ctrlyoke stores your answers on the local machine and never writes them into the workspace.
The dashboard's Settings page edits these files for you. If you edit a file by hand in VS Code, ctrlyoke checks every .ctrlyoke/settings.json against its settings schema, so completion and error checking work as you type. Don't add a $schema key in VS Code: a $schema URL replaces the extension's bundled schema, so VS Code downloads the published copy instead, which fails offline and needs ctrlyoke.dev in json.schemaDownload.trustedDomains. In other editors, set $schema to https://ctrlyoke.dev/schema/v2/settings.json. Every key is optional, and a key you leave out keeps the default shown below.
{
"defaults": {
"harness": "claude-cli",
"models": { "claude-cli": "sonnet" },
"executionMode": "headless"
},
"execution": { "scriptTimeoutSec": 120 },
"queue": { "maxParallelSteps": 4 }
}Settings under defaults set the starting values for workflow fields. A workflow or step that sets the same field overrides them. See the workflow schema reference for the workflow fields.
| Section | Purpose |
|---|---|
general | General format, template, and behavior settings. |
templates | Template-specific settings. |
defaults | Default execution properties applied to all new workflows (mirrors ExecutionProperties). |
worktrees | User-only worktree checkout placement configuration. |
coordination | Retention and participant settings for the execution-root coordination board. |
languageServers | Managed language server definitions and language selections for the workspace editor. |
storage | User-only storage location configuration. |
permissions | Path trust and secret redaction settings. |
usageTracking | Controls provider quota and observed-usage collection. |
execution | Execution settings. |
queue | Queue management settings. |
runs | Execution run retention settings. |
terminal | Embedded terminal settings. |
ui | UI display settings. |
spelling | Spell checking in the prompt editor. |
server | ctrlyoke hosted server settings. |
notifications | Notification settings. |
commit | Commit message generation settings. |
statusLine | Machine-only settings for providers that install a global statusline command. |
diagnostics | Logging and diagnostic output settings. |
| Top-level settings | Settings that sit directly at the root of settings.json. |
| Shared types | Value shapes referenced by more than one setting. |
general
General format, template, and behavior settings.
general.defaultFormat
- Type:
"yaml" | "json" - Default:
"yaml"
Default file format for new workflows.
general.defaultTemplate
- Type:
string - Default:
"blank"
Default template to use for new workflows.
general.autoLoadRecentSession
- Type:
boolean - Default:
true
When a window opens, reopen the workflow the dashboard was last showing, or the most recently modified workflow if there is none or its run no longer exists. When off, every new window starts on a new workflow, and a hosted browser without a workflow in its URL shows the same workflow as the VS Code panel. Reloading the dashboard later in the same session always keeps its current workflow.
general.omitPreviouslyAttachedAgentsSkillsOnResume
- Type:
boolean - Default:
true
When resuming an existing session, omit only agent/skill declarations that were already attached earlier in that same session.
templates
Template-specific settings.
templates.variableDefaults
- Type: map of map of
string - Default:
{}
Saved defaults for declared template variables. Workspace values override User values per variable. A harness and its linked model variables resolve together from one scope; if that scope has no model value, the model uses the template's authored default. Unknown or invalid values are ignored until corrected or the template definition changes.
defaults
Default execution properties applied to all new workflows (mirrors ExecutionProperties).
defaults.harness
- Type:
"copilot-cli" | "claude-cli" | "codex-cli" | "opencode-cli" | "qwen-cli" | "antigravity-cli"or"" - Default:
"" - Workflow field:
harness— a workflow or step value overrides this default
The default harness for workflows and steps that do not name one. Empty = auto-detect: the first installed harness in alphabetical order (antigravity-cli, claude-cli, codex-cli, copilot-cli, opencode-cli, qwen-cli).
defaults.models
- Type:
{ copilot-cli?, claude-cli?, codex-cli?, … }
The model each harness uses when neither the step nor the workflow names one. Unset: ctrlyoke's built-in recommendation for that harness, which is none for every harness: no --model is passed, so the harness CLI uses its own configured default. The built-in recommendation can change between releases.
Default value
{
"copilot-cli": "none",
"claude-cli": "none",
"codex-cli": "none",
"opencode-cli": "none",
"qwen-cli": "none",
"antigravity-cli": "none"
}Fields:
copilot-cli·stringclaude-cli·stringcodex-cli·stringopencode-cli·stringqwen-cli·stringantigravity-cli·string
defaults.additionalArgs
- Type:
{ copilot-cli?, claude-cli?, codex-cli?, … } - Default:
{} - Workflow field:
additionalArgs— a workflow or step value overrides this default
The default additional CLI arguments for each harness for new workflows. A workspace-scope value takes effect only after you approve that exact value on this machine, through the VS Code prompt or ctrlyoke trust-workspace-settings; until then the user value applies.
Fields:
copilot-cli·stringclaude-cli·stringcodex-cli·stringopencode-cli·stringqwen-cli·stringantigravity-cli·string
defaults.agent
- Type:
stringor""ornull - Default:
"" - Workflow field:
agent— a workflow or step value overrides this default
Default portable ctrlyoke workflow agent attachment for new workflows. Native harness agent discovery is managed separately by the Agents & Skills settings page.
Accepted forms:
stringmatching^[a-zA-Z0-9-_]+$""— Empty string means no agent — the form the dashboard's "None" selection serializes to. Distinct from null, which explicitly disables an inherited agent.null
defaults.skills
- Type:
string[]ornull - Default:
[] - Workflow field:
skills— a workflow or step value overrides this default
Default portable ctrlyoke workflow skill attachments for new workflows. Native harness skill discovery is managed separately by the Agents & Skills settings page and does not determine workflow skill support.
defaults.secrets
- Type:
string[]ornull - Default:
[] - Workflow field:
secrets— a workflow or step value overrides this default
Default secret environment-variable names inherited by workflows that set no secrets of their own. Values are resolved by the execution host and never stored in workflow definitions.
defaults.executionMode
- Type:
"interactive" | "headless" - Default:
"interactive" - Workflow field:
executionMode— a workflow or step value overrides this default
Default execution mode for new workflows. 'interactive' spawns a live terminal (TUI) the user can steer; 'headless' runs in the background with output in the Output panel. Workflows and individual steps can override this.
defaults.resumeSession
- Type:
boolean - Default:
true - Workflow field:
resumeSession— a workflow or step value overrides this default
Default for whether a step continues an earlier step's conversation instead of starting a new session. With no sessionId, a step continues the most recent earlier step on the same harness; the first step always starts a new session. Workflows and individual steps can override this, e.g. set resumeSession: false at the workflow level for loops whose steps must each start fresh.
defaults.priorContext
- Type:
"all" | "previous" | "none" | "finalStepAll" | "finalStepPrevious"orinteger[]or{ previous } - Default:
"none" - Workflow field:
priorContext— a workflow or step value overrides this default
Default priorContext for every step that doesn't set its own.
Fields:
previous·integer· required — How many of the most recent earlier outputs to include
defaults.mcpServers
- Type: array of (
stringor{ id: "ctrlyoke", deniedTools? }or{ id, description?, command?, … }) - Default:
[] - Workflow field:
mcpServers— a workflow or step value overrides this default
Default MCP servers to attach to each prompt execution. A workspace-scope entry that launches a command takes effect only after you approve that exact entry on this machine, through the VS Code prompt or ctrlyoke trust-workspace-settings; until then the user value applies.
When id is "ctrlyoke":
Fields:
deniedTools·string[]
Fields:
id·string· required — Unique server identifierdescription·string— Human-readable description shown in MCP Manager. ctrlyoke-only metadata — deliberately omitted by every harness export path so it never leaks an unrecognized key into an external tool's native config file.command·string— Command to run the MCP server process (stdio servers, e.g. "npx" or "node")args·string[]— Arguments to pass to the command (stdio servers only)env· map ofstring— Environment variables for the server process (stdio servers only)autoApprove·booleanorstring[]— Tools to auto-approve from this MCP server: true = all tools, string[] = tool names. For Copilot CLI, server IDs must not match built-in permission kinds or contain whitespace, parentheses, or commas, and tool names must not contain parentheses or commas.url·string— Remote endpoint URL for streamable-http or SSE servers (e.g. "https://mcp.example.com")transport·"streamable-http" | "sse"— Transport protocol for remote servers. Defaults to "streamable-http".headers· map ofstring— HTTP headers to send with every request (remote servers only, e.g. { "Authorization": "Bearer token" }). Secret references are allowed as ${secret:NAME} values.deniedTools·string[]— Tool names from this server to deny at execution time. Use bare tool names without the mcp__<serverid>__ prefix (e.g. ["append_step"]). Translated to mcp__<id>__<tool> deny patterns and merged into the harness permission args. Supported on harnesses that accept tool deny patterns.
defaults.hooks
- Type: array of
{ event, command, env?, … } - Default:
[] - Workflow field:
hooks— a workflow or step value overrides this default
User-defined hooks to run at various execution lifecycle points. A workspace-scope hook takes effect only after you approve that exact hook on this machine, through the VS Code prompt or ctrlyoke trust-workspace-settings; until then the user value applies.
Fields:
event·"stop" | "sessionStart" | "preToolUse" | "postToolUse" | "userPromptSubmit" | "permissionRequest" | "notification" | "error"· required — Logical hook event. Unsupported events for the active harness are silently skipped. 'stop' maps to Stop (Claude/Qwen/Antigravity), Stop (Codex), agentStop (Copilot). 'notification' maps to Notification (Claude/Qwen), notification (Copilot), and is n/a for Codex/Antigravity/OpenCode.command·string· required — Command to execute. Resolved relative to workspace root if not absolute.env· map ofstring— Each hook receives only its own env values, merged over the harness environment when it runs. These values are not added to the harness process environment, but are written to a per-step temp file readable by the local user, so they are not hidden from a model with shell access. Secret references are allowed only as ${secret:NAME} values.timeoutSec·integer— Maximum time a user hook may run, in seconds. Applied by Copilot, Claude Code, Codex, Qwen Code, Antigravity, and OpenCode; harnesses that do not support per-hook timeouts use their own limit.
defaults.errorBehavior
- Type:
{ onError, maxRetries?, retryDelaySec? }ornull - Default:
null - Workflow field:
errorBehavior— a workflow or step value overrides this default
Default policy for internal errors in any step phase. null (the default) stops the workflow unless the workflow or step sets its own policy.
Fields:
onError·"stopWorkflow" | "retry" | "retryPhase" | "continue"orstring· required — What to do when a step phase cannot run or otherwise encounters an internal error. 'stopWorkflow': fail the step and stop the workflow (default). 'retry': re-run the whole step from its pre-condition, starting a fresh harness session. 'retryPhase': re-run only the phase that errored — an errored end-condition re-runs just its script against the existing response without another AI call, and a failed prompt is re-sent in a fresh harness session without re-running the pre-condition; for pre-conditions and script steps it behaves like 'retry'. 'continue': proceed as if the phase had not errored and record a warning. Each phase keeps its own retry count. A whole-value{{name}}placeholder is coerced and validated before dispatch.maxRetries·integerorstring— Maximum retry attempts when onError is retry or retryPhase. When omitted, one retry is allowed. A whole-value{{name}}placeholder is coerced and validated before dispatch.retryDelaySec·numberorstring— Delay before retrying, in seconds. A whole-value{{name}}placeholder is coerced and validated before dispatch.
defaults.sandbox
- Type:
booleanornull - Default:
false - Workflow field:
sandbox— a workflow or step value overrides this default
Default terminal-command containment for workflows and steps that omit sandbox. false (the default) turns each harness's sandbox off, true turns it on where the harness supports it and skips the others with a warning, and null passes no sandbox flags so each harness's own settings apply. A workspace-scope value that is less contained than your user value (false or null while yours is true, or false while yours is null) takes effect only after you approve that exact value on this machine, through the VS Code prompt or ctrlyoke trust-workspace-settings; until then the user value applies.
defaults.sandboxMode
- Type:
"workspace-write" | "read-only" - Default:
"workspace-write" - Workflow field:
sandboxMode— a workflow or step value overrides this default
How strict sandbox: true is for workflows and steps that omit sandboxMode. Replaces permissions.codexSandboxMode. A workspace-scope workspace-write while your user value is read-only takes effect only after you approve it on this machine, through the VS Code prompt or ctrlyoke trust-workspace-settings; until then the user value applies.
defaults.toolPermissions
- Type:
{ mode?, allowedTools?, deniedTools? }ornull - Workflow field:
toolPermissions— a workflow or step value overrides this default
Default tool permission settings for prompt execution. In auto mode, the harness's own safety judge approves or blocks each request; the deny list always blocks, while the allow list pre-approves tools without limiting what runs. Unsupported harnesses run with custom tool permissions and report a warning. Codex auto review can approve sandbox escalations. Allowed Tools and Denied Tools are currently supported by Copilot CLI, Claude CLI, Qwen Code, and OpenCode; Qwen is inline granular support and OpenCode uses OPENCODE_CONFIG_CONTENT without writing a workspace opencode.json. Codex and Antigravity only support an overall permission mode, not individual tool patterns, and do NOT ENFORCE these lists, except that Codex enforces denied mcp__<server>__<tool> entries for MCP servers the workflow attaches. While a list is still the shipped default, a harness that can't enforce it reports an information note rather than a compatibility warning. A workspace-scope value that grants more than your user value (a broader mode, an allowed tool your custom list lacks, a denied tool removed, or none/null while yours is managed) takes effect only after you approve that exact value on this machine, through the VS Code prompt or ctrlyoke trust-workspace-settings; until then the user value applies. A workspace value that only narrows permissions applies without asking.
Accepted forms:
{ mode?, allowedTools?, deniedTools? }— Per-workflow/prompt tool permission overrides. Follows three-tier precedence: prompt > workflow > thedefaults.toolPermissionssetting.null
Default value
{
"mode": "allowAll",
"allowedTools": [
"write",
"shell(git status:*)",
"shell(git diff:*)",
"shell(git show:*)",
"shell(git log:*)",
"shell(git add:*)",
"shell(git commit:*)",
"shell(git mv:*)",
"shell(git rm:*)",
"shell(npm:*)",
"shell(yarn:*)",
"shell(pnpm:*)",
"shell(node:*)",
"shell(npx:*)"
],
"deniedTools": [
"shell(sudo:*)",
"shell(git push:*)",
"shell(git reset --hard:*)",
"shell(git checkout:*)",
"shell(git restore:*)",
"shell(git clean:*)",
"shell(npm publish:*)",
"shell(yarn publish:*)",
"shell(pnpm publish:*)",
"shell(kubectl delete:*)"
]
}Fields:
mode·"dangerouslyAllowAll" | "allowAll" | "auto" | "custom" | "none"— Permission mode. 'dangerouslyAllowAll' bypasses all restrictions. 'allowAll' auto-grants all but respects the deny list. 'auto' lets the harness's own safety judge approve or block each request; the deny list always blocks, while the allow list pre-approves tools without limiting what runs. Unsupported harnesses run with custom tool permissions and report a warning. Codex auto review can approve sandbox escalations. 'custom' uses allowedTools + deniedTools. 'none' passes no permission flags at all — it does not deny tools; the harness applies whatever permissions are configured in its own local settings (e.g. ~/.claude/settings.json, Copilot CLI config). Not substituted: This structural field or identity value stays as authored.allowedTools·string[]— Tool patterns to allow (used in custom mode). Currently supported by Copilot CLI, Claude CLI, Qwen Code, and OpenCode. Qwen uses inline granular support. OpenCode delivers permissions through OPENCODE_CONFIG_CONTENT and writes no workspace opencode.json. Codex and Antigravity only support an overall permission mode, not individual tool patterns; Allowed Tools are NOT ENFORCED by those harnesses.deniedTools·string[]— Tool patterns to deny (takes precedence over allow list). Currently supported by Copilot CLI, Claude CLI, Qwen Code, and OpenCode. Qwen uses inline granular support. OpenCode delivers permissions through OPENCODE_CONFIG_CONTENT and writes no workspace opencode.json. Antigravity only supports an overall permission mode and does NOT ENFORCE Denied Tools. Codex enforces onlymcp__<server>__<tool>entries for MCP servers the workflow attaches, passed as that server'sdisabled_tools; it does NOT ENFORCE shell or other tool patterns.
defaults.endCondition
- Type:
{ mcpLiteralEnvKeys?, script, env?, … }ornull - Default:
null - Workflow field:
endCondition— a workflow or step value overrides this default
Default end condition for new workflows. null (the default) means new workflows have no end condition. A workspace-scope value takes effect only after you approve that exact value on this machine, through the VS Code prompt or ctrlyoke trust-workspace-settings; until then the user value applies.
Fields:
mcpLiteralEnvKeys·string[]— Internal provenance for MCP supplied literal env values.script·string· required — Shell command or path to script. Relative paths are checked in this order: execution directory, workspace root,.ctrlyoke/, then~/.ctrlyoke/scripts/.env· map ofstring— Environment map consumed by the script process. Secret references are allowed only as ${secret:NAME} values.compareSource·"stdout" | "stderr" | "exitCode"orstring— Which output the comparison reads. Default: 'exitCode'. 'stdout'/'stderr' compare the trimmed text; 'exitCode' compares the numeric exit code. There is no implicit clean-exit requirement layered onto a text comparison. A whole-value{{name}}placeholder is coerced and validated before dispatch.returns· removed — Removed — renamed toexpected, and 'true'/'false' are no longer mapped onto exit codes. Omit it entirely to pass on exit code 0.timeoutSec·numberorstring— Timeout in seconds. When omitted, theexecution.scriptTimeoutSecsetting applies. A whole-value{{name}}placeholder is coerced and validated before dispatch.shell·string— Pin the shell that runs this script's inline text. Used only whenscriptis inline text rather than a path to a script file with a known extension. Free-form executable name or path, e.g. "pwsh", "bash", "cmd". Overrides theterminal.shellExecutablesetting for this one script; falls back to it, then platform auto-detect, when omitted. Variable substitution: step text accepts{{name}}and resolves at dispatch; unresolved placeholders fail before execution.operator·"eq" | "ne" | "contains" | "notContains" | "gte" | "gt" | "lte" | "lt" | "matches" | "isEmpty" | "isNotEmpty"orstring— How the compare source is compared againstexpected. Default: 'eq' (whole-value literal match on trimmed text; numeric when compareSource is exitCode). 'contains'/'notContains' are substring tests. 'gte'/'gt'/'lte'/'lt' are numeric and fail when either side is not a number. 'matches' treatsexpectedas an unanchored regular expression — add ^ and $ to require a full match. Everymatchescomparison runs in a worker bounded byexecution.regexTimeoutSec; a timeout is an evaluation error handled byerrorBehavior. 'isEmpty'/'isNotEmpty' take noexpected. Use word tokens such asgteandne;operator: >=andoperator: !=are YAML parse errors. A whole-value{{name}}placeholder is coerced and validated before dispatch.expected·stringornumber— Value the compare source is compared against. Omit it to pass when the script exits 0 — there is no boolean form, and 'true'/'false' are not accepted as exit-code values. Omitting it whilecompareSourceoroperatorstates a comparison is allowed but ignores that comparison and still falls back to exit code 0; the dashboard flags this as a warning rather than refusing the workflow. Variable substitution: step text accepts{{name}}and resolves at dispatch; unresolved placeholders fail before execution.ignoreCase·booleanorstring— Compare text case-insensitively. Applies only to eq/ne/contains/notContains. Default: false. A whole-value{{name}}placeholder is coerced and validated before dispatch.maxRetries·-1orintegerorstring— Maximum number of retry attempts.-1means unlimited. 0 means no retries by default, or 1-100 for a specific limit. When onPass or onFail is 'retry' and this field is omitted, one retry is allowed. A whole-value{{name}}placeholder is coerced and validated before dispatch.retryPrompt·string— Template for retry prompt. Supports $preCondition:<field> and $endCondition:<field> for condition output fields (stdout, stderr, exitCode, actual, expected, compareSource). $preCondition:* works in the step and retry prompts; $endCondition:* is only available in the retry prompt.passRetryPrompt·string— Template for the prompt sent after the end condition passes and onPass is 'retry'. Supports $preCondition:<field> and $endCondition:<field> for condition output fields (stdout, stderr, exitCode, actual, expected, compareSource); both prefixes are substituted on a pass retry. If omitted, the step's own prompt is re-sent.resumeSessionOnRetry·boolean— Whether retries continue in the same session. Default: true (retries resume the existing session for context continuity). Set to false to start a fresh session for each retry.onPass·"continue" | "retry" | "stopWorkflow"orstring— What to do when the end condition passes. 'continue': advance to the next step (default). 'retry': re-run the step's prompt while the condition keeps passing, up to maxRetries; exhausting the retries advances to the next step. A failure during the loop is handled by onFail. 'stopWorkflow': halt execution immediately. A whole-value{{name}}placeholder is coerced and validated before dispatch.onFail·"continue" | "retry" | "stopWorkflow"orstring— What to do when end condition fails. 'retry': re-run the AI prompt (up to maxRetries times); if retryPrompt is omitted, a fallback prompt includes the expected and actual values and script output. When maxRetries is omitted, one retry is allowed. 'continue': advance to the next step even if validation fails. 'stopWorkflow': halt execution (default). A retryPrompt alone does not enable retries; set maxRetries above 0 on the condition or in defaults.endCondition.maxRetries, or use onFail: retry. A whole-value{{name}}placeholder is coerced and validated before dispatch.
defaults.preCondition
- Type:
{ mcpLiteralEnvKeys?, script, env?, … }ornull - Default:
null - Workflow field:
preCondition— a workflow or step value overrides this default
Default pre-condition for new workflows. null (the default) means new workflows have no pre-condition. A workspace-scope value takes effect only after you approve that exact value on this machine, through the VS Code prompt or ctrlyoke trust-workspace-settings; until then the user value applies.
Fields:
mcpLiteralEnvKeys·string[]— Internal provenance for MCP supplied literal env values.script·string· required — Shell command or path to script. Relative paths are checked in this order: execution directory, workspace root,.ctrlyoke/, then~/.ctrlyoke/scripts/.env· map ofstring— Environment map consumed by the script process. Secret references are allowed only as ${secret:NAME} values.compareSource·"stdout" | "stderr" | "exitCode"orstring— Which output the comparison reads. Default: 'exitCode'. 'stdout'/'stderr' compare the trimmed text; 'exitCode' compares the numeric exit code. There is no implicit clean-exit requirement layered onto a text comparison. A whole-value{{name}}placeholder is coerced and validated before dispatch.returns· removed — Removed — renamed toexpected, and 'true'/'false' are no longer mapped onto exit codes. Omit it entirely to pass on exit code 0.timeoutSec·numberorstring— Timeout in seconds. When omitted, theexecution.scriptTimeoutSecsetting applies. A whole-value{{name}}placeholder is coerced and validated before dispatch.shell·string— Pin the shell that runs this script's inline text. Used only whenscriptis inline text rather than a path to a script file with a known extension. Free-form executable name or path, e.g. "pwsh", "bash", "cmd". Overrides theterminal.shellExecutablesetting for this one script; falls back to it, then platform auto-detect, when omitted. Variable substitution: step text accepts{{name}}and resolves at dispatch; unresolved placeholders fail before execution.operator·"eq" | "ne" | "contains" | "notContains" | "gte" | "gt" | "lte" | "lt" | "matches" | "isEmpty" | "isNotEmpty"orstring— How the compare source is compared againstexpected. Default: 'eq' (whole-value literal match on trimmed text; numeric when compareSource is exitCode). 'contains'/'notContains' are substring tests. 'gte'/'gt'/'lte'/'lt' are numeric and fail when either side is not a number. 'matches' treatsexpectedas an unanchored regular expression — add ^ and $ to require a full match. Everymatchescomparison runs in a worker bounded byexecution.regexTimeoutSec; a timeout is an evaluation error handled byerrorBehavior. 'isEmpty'/'isNotEmpty' take noexpected. Use word tokens such asgteandne;operator: >=andoperator: !=are YAML parse errors. A whole-value{{name}}placeholder is coerced and validated before dispatch.expected·stringornumber— Value the compare source is compared against. Omit it to pass when the script exits 0 — there is no boolean form, and 'true'/'false' are not accepted as exit-code values. Omitting it whilecompareSourceoroperatorstates a comparison is allowed but ignores that comparison and still falls back to exit code 0; the dashboard flags this as a warning rather than refusing the workflow. Variable substitution: step text accepts{{name}}and resolves at dispatch; unresolved placeholders fail before execution.ignoreCase·booleanorstring— Compare text case-insensitively. Applies only to eq/ne/contains/notContains. Default: false. A whole-value{{name}}placeholder is coerced and validated before dispatch.onPass·"continue" | "skipPrompt" | "stopWorkflow"orstring— What to do when the pre-condition check passes (script exits 0 / returns matches). 'continue': run the prompt (default). 'skipPrompt': skip this prompt and advance the queue. 'stopWorkflow': halt execution. A whole-value{{name}}placeholder is coerced and validated before dispatch.onFail·"continue" | "skipPrompt" | "stopWorkflow"orstring— What to do when the pre-condition check fails. 'continue': run the prompt anyway (pre-condition is advisory). 'skipPrompt': skip this prompt and advance the queue (default). 'stopWorkflow': halt execution. A whole-value{{name}}placeholder is coerced and validated before dispatch.
defaults.worktree
- Type:
falseortrueorstringor{ mode: "managed", merge?, keep?, … }or{ mode: "named", branch, directory?, … } - Default:
false - Workflow field:
worktree— a workflow or step value overrides this default
Default worktree behavior for workflows that omit a root worktree value. Uses the same false, shorthand, and object forms as workflow worktree; an inherited value degrades to ordinary execution when the workspace is not eligible. A workspace-scope value with a setup command or path-form directory takes effect only after you approve that exact value on this machine, through the VS Code prompt or ctrlyoke trust-workspace-settings; until then the user value applies. A bare-name directory applies without asking. A value without setup or a path directory, or one whose setup command and path directory match your user value's, applies without asking.
Accepted forms:
false— No worktree: the workflow runs directly in the ordinary workspace checkout, sharing it with your own edits.true— Managed-worktree shorthand.string— Named-worktree branch shorthand. The value must be a valid local Git branch name.{ mode: "managed", merge?, keep?, … }— Managed creates a throw-away worktree and branch per run and removes the directory when the workflow completes, leaving the branch for review; pick it for isolated runs you will not follow up on.{ mode: "named", branch, directory?, … }— Named targets a persistent worktree you own, which ctrlyoke never commits, merges, or removes; pick it for conversational workflows you will append to.
When mode is "managed":
Fields:
merge·boolean— Merge the managed branch into the captured source checkout after the run. Not substituted: This structural field or identity value stays as authored.keep·boolean— Keeps the managed worktree directory after the run instead of removing it. Without it, appending a follow-up prompt recreates the directory from the branch; ignored files such as node_modules are gone and the setup command runs again, so a long setup pays that cost on every append. Removing the directory also ends filesystem undo for that run. Not substituted: This structural field or identity value stays as authored.base·string— Optional Git ref resolved to a commit when the worktree is created.setup·string— Optional setup command run after a new managed worktree is created. Setup is outside the step-scoped errorBehavior policy: it runs before any step is in flight, so a non-succeeded setup blocks the worktree and the next Run re-runs it; a succeeded outcome is skipped.
When mode is "named":
Fields:
branch·string· required — Local Git branch name for the named worktree.directory·string— Optional long-lived directory for this named worktree, so one directory can hold different branches over time. Use an absolute path, a ~-prefixed path, or a bare name with no slash or backslash; relative paths containing separators are rejected. A bare name reuses the registered linked worktree whose directory has that exact name (or the directory ctrlyoke derived for a branch of that name); otherwise ctrlyoke creates the directory as<worktree root>/<name>, with no hash suffix, or as<worktrees.root>/<repository>-<hash>/<name>when the sharedworktrees.rootsetting is set. Whenbranchdiffers from the branch the directory holds, ctrlyoke switches it only when it is clean and never switches it back. Omit to derive the directory from the branch.base·string— Optional Git ref resolved to a commit when the worktree is created.setup·string— Optional setup command run in the named worktree at the start of every run, such asnpm cito pick up dependency changes since the last run. Resuming or continuing a run whose setup already succeeded does not run it again. Omit it for no setup. Setup is outside the step-scoped errorBehavior policy: it runs before any step is in flight, so a failed setup blocks the worktree and the next Run re-runs it.
worktrees
User-only worktree checkout placement configuration.
worktrees.root
- Type:
string - Default:
""
Absolute or ~-prefixed directory where ctrlyoke creates worktrees. Every repository shares it, so a new bare-name directory goes in a <repository>-<hash> folder inside it.
coordination
Retention and participant settings for the execution-root coordination board.
coordination.readNotesPageSize
- Type:
integer - Default:
50 - Constraints: minimum 1
Maximum number of coordination entries returned by one read_notes page. Reads are always paged.
coordination.maxNoteLength
- Type:
integer - Default:
2000 - Constraints: minimum 1
Maximum number of characters in a coordination note.
coordination.maxEntries
- Type:
integer - Default:
1000 - Constraints: minimum 1
Maximum number of coordination entries retained after compaction.
coordination.maxBoardBytes
- Type:
integer - Default:
5242880 - Constraints: minimum 1
Hard maximum size of the coordination board in bytes.
coordination.maxNoteAgeHours
- Type:
integer - Default:
24 - Constraints: minimum 1
Hours a coordination note stays relevant once its author has left the board. Older notes from departed authors are hidden from read_notes and removed during compaction; notes from authors still on the board are kept until they leave.
coordination.cliParticipantTtlMinutes
- Type:
number - Default:
30 - Constraints: minimum 1
Lease lifetime for participants delivered through the CLI or built-in skill.
coordination.allowExternalParticipants
- Type:
boolean - Default:
true
Allow participants not launched by ctrlyoke to join the coordination board.
languageServers
Managed language server definitions and language selections for the workspace editor.
languageServers.definitions
- Type: map of languageServerDefinition
- Default:
{}
Server id to command definition. Workspace definitions remain pending until the user approves them.
languageServers.use
- Type: map of (
stringorfalse) - Default:
{}
Language id to selected server id, or false to disable language intelligence. Workspace scope may select available servers.
languageServers.settings
- Type: map of
object - Default:
{}
Server id to LSP initialization and workspace/configuration settings.
languageServers.idleShutdownMinutes
- Type:
integer - Default:
10 - Constraints: minimum 0
User-only idle timeout in minutes before a server without open documents is stopped. 0 disables idle shutdown.
languageServers.maxRunning
- Type:
integer - Default:
4 - Constraints: minimum 1
User-only maximum number of concurrently running language servers.
languageServers.startOnLaunch
- Type:
boolean - Default:
false
User-only opt-in to start selected language servers when the hosted server launches. Defaults to lazy startup.
storage
User-only storage location configuration.
storage.runHistoryLocation
- Type:
"user" | "workspace" - Default:
"user"
Store run history under the user state home or beside the workspace. Recently deleted runs, observed usage, and the history search index move with it. User scope only. Takes effect after a window reload, and existing history is not moved: the other location appears as a separate history, and switching back restores it. With workspace, each run's live definition sits where any agent with write access to the workspace can edit it, including a pending step's scripts and permissions. ctrlyoke keeps a record of every definition it writes under the user state home: a running workflow ignores a change made outside ctrlyoke, and a run with one cannot run or be edited until you accept or restore it. Choose workspace only for agents and repositories you trust.
storage.trashRetentionDays
- Type:
integer - Default:
30 - Constraints: minimum 1
Days a deleted run or workflow stays in Recently deleted before it is permanently removed. Every history delete, including Clear all history, moves runs to Recently deleted, where they can be restored until then.
permissions
Path trust and secret redaction settings.
External file roots
Workspace files are always trusted. To let ctrlyoke use a directory outside the workspace, add it to permissions.trustedExternalRoots:
{
"permissions": {
"trustedExternalRoots": ["C:/Users/me/.codex/sessions", "C:/temp/repros"]
}
}- User scope: trusted immediately, because you edited your own settings file.
- Workspace scope: treated as a request. Each machine must approve it once, through the prompt in VS Code or by running
ctrlyoke trust-external-rootsin the workspace. Add--yesto approve every pending root without being asked. ctrlyoke stores approvals on the local machine and never writes them into the workspace settings file.
Roots from the user and workspace files are combined. They don't replace each other.
A single workflow can inherit, replace, or disable this set with its trustedExternalRoots field. To approve the new roots a workflow declares, use ctrlyoke trust-workflow-external-roots <file>.
permissions.trustedExternalRoots
- Type:
string[] - Default:
[]
Absolute directory paths outside the workspace that ctrlyoke may read for prompt attachments and open from file links. Workspace files are always allowed. User-scope entries are trusted immediately; workspace-scope entries require a one-time batch approval before they take effect. Approved roots are also passed to the harness, and become extra writable roots of its sandbox when sandbox resolves to true (none under sandboxMode: read-only); they do not limit terminal commands while the sandbox is off.
permissions.heuristicSecretRedactionEnabled
- Type:
boolean - Default:
true
Apply pattern-based heuristics (e.g. 'token=...', 'Bearer ...', private-key blocks) when redacting logs, transports, exports, and history, in addition to exact matches of resolved managed/env secret values. Exact-value redaction of secrets ctrlyoke actually resolved always stays on regardless of this setting. Disable this if the heuristics are over-matching and corrupting legitimate output, such as code samples or public identifiers that merely look like credentials.
usageTracking
Controls provider quota and observed-usage collection.
usageTracking.enabled
- Type:
boolean - Default:
true
Enable usage collection for ctrlyoke-started harness sessions.
usageTracking.providerRefreshEnabled
- Type:
boolean - Default:
true
Allow provider quota refreshes from configured collectors. Requires usageTracking.enabled.
usageTracking.persistObservedUsage
- Type:
boolean - Default:
true
Save observed usage and lifetime statistics with this project's run history, so they survive a restart. The location follows storage.runHistoryLocation. Requires usageTracking.enabled.
usageTracking.warningPercentUsed
- Type:
number - Default:
80 - Constraints: minimum 0 · maximum 100
Quota usage percentage at which ctrlyoke starts warning that a provider limit is close.
usageTracking.percentDirection
- Type:
"used" | "remaining" - Default:
"used"
Whether quota percentages are displayed as used or remaining.
execution
Execution settings.
execution.reuseRunningTerminal
- Type:
boolean - Default:
true
When true, a step that resumes a session whose terminal is still open types its prompt into that running terminal instead of restarting the harness with a resume, which is faster. Interactive steps only, and only when the step's start-up properties (model, tool permissions, hooks, MCP servers, additional args, secrets) match the running process; otherwise a new process starts. Whether terminals stay open after a step is set by execution.closeTerminalOnComplete, so this has no effect while that is on.
execution.closeTerminalOnComplete
- Type:
boolean - Default:
false
Automatically close the interactive terminal when execution completes. Turning this on disables execution.reuseRunningTerminal.
execution.autoDeleteTempFiles
- Type:
boolean - Default:
true
Automatically delete categorized prompt temp files after execution. Set to false to retain files in .ctrlyoke/temp/ for debugging.
execution.inlineGeneratedPromptOnStdin
- Type:
boolean - Default:
true
Inline generated prompt sections into the first message for headless harnesses that support it. Turn off to use categorized temporary files and references.
execution.contextResolutionFailure
- Type:
"warn" | "fail" - Default:
"warn"
How to handle a declared reference that fails to resolve: a missing/invalid secret (!NAME), an unknown skill (/skill:) or MCP server (/mcp:), an unresolved @file/@dir/#selection/#sym reference, or an unresolved ~diff/~staged/~stash/~<hash> git reference. 'warn' (default) reports a diagnostic and lets the step run anyway. 'fail' stops the step before the harness spawns, naming the unresolved reference.
execution.maxPromptTimeoutSec
- Type:
-1orinteger - Default:
-1
Maximum time in seconds for one harness prompt to complete. A finite value stops the prompt when its execution budget expires; -1 disables the prompt timeout.
execution.scriptTimeoutSec
- Type:
number - Default:
3600
Maximum time in seconds for pre-condition, end-condition, and script-step scripts, and for a worktree's setup command, to run. This setting must be greater than zero and has no unlimited value. A script's own timeoutSec (in seconds) overrides it.
execution.regexTimeoutSec
- Type:
number - Default:
10
Maximum time in seconds for each matches regex comparison. A timeout is an evaluation error handled by the step's errorBehavior.
execution.ctrlyokeMcpMode
- Type:
"native" | "skill" - Default:
"native"
Whether ctrlyoke's own MCP server is attached natively or replaced with the built-in MCP tools skill. Only affects ctrlyoke's server, not other MCP servers configured in a workflow.
queue
Queue management settings.
queue.maxParallelSteps caps how many members of a parallel group run at once. If a group has more members than the cap, the extra members wait for a free slot. Set it to 1 to run grouped steps one at a time. Members share the workflow's workspace and its worktree. This setting limits how many run at once. It does not isolate members from each other or merge their work.
queue.maxSteps
- Type:
-1orinteger - Default:
100
Maximum number of entries in the run's steps array, including disabled steps and each member of a parallel group. Checked before execution starts and after steps are appended; retries and final-step passes do not add entries. A workflow's own maxSteps replaces this value for that workflow, so a workflow maxSteps: -1 lifts this cap. Dashboard appends, MCP append_step, and run continuation enforce the same resolved limit. -1 disables the queue-size limit.
queue.maxParallelSteps
- Type:
integer - Default:
6 - Constraints: minimum 1
Maximum number of active members in a parallel step group.
queue.maxWorkflowExecutionTimeSec
- Type:
-1orinteger - Default:
-1
Maximum active execution time in seconds for a workflow. Checked at safe step, parallel-group, final-step, and retry boundaries; paused time is excluded. -1 disables the workflow-time limit.
runs
Execution run retention settings. History is always on.
runs.maxRuns
- Type:
-1orinteger - Default:
-1
Maximum runs kept per workflow. When a new run starts, that workflow's oldest runs are permanently deleted, definition and output together, without passing through Recently deleted. Running runs and runs another workflow uses as prior context are kept, so the count can briefly exceed the limit. -1 means unlimited.
runs.historySearchCacheMb
- Type:
number - Default:
320 - Constraints: minimum 0
Approximate working-set budget in MB for caching parsed history-search documents from the most recent runs, evicted oldest-first when exceeded. Bounds real extension-host process memory (RSS), not a literal byte count — actual RSS runs above this number due to V8 overhead the estimate can't see, so the default is calibrated from measured RSS on a real index rather than the byte math alone. 0 disables the cache.
terminal
Embedded terminal settings.
terminal.fontSize
- Type:
number - Default:
14 - Constraints: minimum 8 · maximum 24
Terminal font size in pixels.
terminal.lineHeight
- Type:
number - Default:
1.2 - Constraints: minimum 1 · maximum 2
Terminal line height multiplier.
terminal.scrollback
- Type:
integer - Default:
5000 - Constraints: minimum 1000 · maximum 50000
Maximum scrollback lines retained in memory.
terminal.cursorStyle
- Type:
"block" | "underline" | "bar" - Default:
"block"
Terminal cursor shape.
terminal.cursorBlink
- Type:
boolean - Default:
true
Blink the terminal cursor.
terminal.macOptionIsMeta
- Type:
boolean - Default:
false
Treat the macOS Option key as Meta.
terminal.wordSeparators
- Type:
string - Default:
" ()[]{}',\""`
Characters treated as word boundaries on double-click selection.
terminal.replayBufferKb
- Type:
number - Default:
50 - Constraints: minimum 10 · maximum 500
Output replayed on webview reconnect, in KB.
terminal.shellExecutable
- Type:
string - Default:
""
Override the shell spawned for user terminal sessions and for inline script text. Empty means auto-detect. A workspace-scope value takes effect only after you approve that exact value on this machine, through the VS Code prompt or ctrlyoke trust-workspace-settings; until then the user value applies.
terminal.mobileControlBar
- Type:
"auto" | "always" | "never" - Default:
"auto"
When to show the mobile terminal control bar.
terminal.mobileBarLayout
- Type:
{ bar, popup, hidden }
Which keys the mobile terminal control bar shows: 'bar' keys are always visible, 'popup' keys sit behind the More menu, and 'hidden' keys are not shown. Each entry is a key ID: modifier:ctrl (a one-shot Ctrl toggle); key:esc, key:tab, key:up, key:down, key:left, key:right, or key:enter; shortcut:shift-tab, shortcut:ctrl-c, shortcut:ctrl-z, shortcut:ctrl-l, shortcut:ctrl-r, or shortcut:ctrl-a; or the id of an entry in terminal.mobileCustomShortcuts. Unknown IDs are dropped, and a known key missing from all three lists is added to 'popup'.
terminal.mobileBarLayout.bar
- Type:
string[] - Required: yes
Key IDs always visible on the bar, in order. modifier:ctrl is kept here unless it is hidden.
Default value
[
"modifier:ctrl",
"key:esc",
"key:tab",
"key:up",
"key:down",
"key:left",
"key:right",
"key:enter"
]terminal.mobileBarLayout.popup
- Type:
string[] - Required: yes
Key IDs shown in the More menu, in order. The menu shows shortcuts only, and modifier:ctrl placed here moves to 'bar'.
Default value
[
"shortcut:shift-tab",
"shortcut:ctrl-c",
"shortcut:ctrl-z",
"shortcut:ctrl-l",
"shortcut:ctrl-r",
"shortcut:ctrl-a"
]terminal.mobileBarLayout.hidden
- Type:
string[] - Required: yes
- Default:
[]
Key IDs not shown anywhere.
terminal.mobileCustomShortcuts
- Type: array of
{ id, label, sequence } - Default:
[]
Custom shortcuts in the mobile terminal control bar More menu.
Fields:
id·string· requiredlabel·string· requiredsequence·string· required
ui
UI display settings.
ui.showCliCommand
- Type:
boolean - Default:
true
Show the CLI command being executed.
ui.showHeadlessPermissionWarning
- Type:
boolean - Default:
true
Show a warning when headless execution uses limited tool permissions.
ui.autoFocusOutputOnExecution
- Type:
boolean - Default:
true
Automatically expand the output section and switch to the relevant output view when a prompt starts. Headless runs show Output; interactive and terminal-reuse runs show Terminal.
ui.openPromptsInSecondGroup
- Type:
boolean - Default:
false
Open prompt files in a second editor group.
ui.respectGitignoreForCompletions
- Type:
boolean - Default:
true
Filter file completions using .gitignore rules.
ui.autoExpandEditorWhenTyping
- Type:
boolean - Default:
true
Automatically grow the editor panel as you type past its current height, up to 60% of the available area. Shrinks back when text is deleted or the prompt is submitted.
ui.useAbsolutePathReferences
- Type:
boolean - Default:
false
Send absolute file paths to the harness/model instead of relative paths. Stored workflow text stays relative regardless of this setting. Forced on in multi-root workspaces and for OpenCode, Antigravity and Qwen, whose models often fail to resolve relative paths.
ui.outputVirtualizationRowThreshold
- Type:
-1orinteger - Default:
200
Minimum projected output row count before the Output panel uses virtualization. 0 means always virtualize. -1 means never.
ui.collapsedToolOutputLineCount
- Type:
integer - Default:
3 - Constraints: minimum 1
Approximate number of wrapped lines shown for Bash and generic tool results before they collapse.
ui.confirmDeleteOperations
- Type:
boolean - Default:
true
Show a confirmation dialog before delete operations like removing prompts, deleting workflow history, or discarding untracked files.
ui.confirmResetOperations
- Type:
boolean - Default:
true
Show a confirmation dialog before resetting workflow start position.
ui.confirmContinuationDiscardOperations
- Type:
boolean - Default:
true
Show a confirmation dialog before discarding a continuation's edited suffix (Discard Continuation, Start New Run Instead).
ui.confirmRerunOperations
- Type:
"always" | "exceptFavorites" | "never" - Default:
"exceptFavorites"
When to show a confirmation dialog before Re-run starts a new run of the workflow from its first step. 'always' asks for every workflow, 'exceptFavorites' (the default) asks for every workflow except favorites, so the workflows you re-run on purpose start straight away, and 'never' re-runs without asking.
ui.hideGitIgnoredFiles
- Type:
boolean - Default:
false
Hide files and directories ignored by .gitignore in the workspace file explorer and workflow file picker.
ui.wordWrap
- Type:
boolean - Default:
true
Wrap long lines in code views: the workspace file editor, script and condition editors, and diffs. When off, long lines extend past the view and scroll horizontally. The prompt editor always wraps.
ui.outputFontSize
- Type:
number - Default:
13 - Constraints: minimum 10 · maximum 24
Output pane font size in pixels. The output toolbar's − and + buttons change this setting.
ui.editorFontSize
- Type:
"vscode"ornumber - Default:
"vscode"
Font size of the prompt editor, retry prompts, condition and script-step scripts, and the workspace file editor, in pixels. 'vscode' matches the VS Code editor font size; a browser connected to the ctrlyoke server uses 14px for 'vscode' because it cannot read VS Code's setting. One-line form fields such as additional arguments, hook commands, and permission lists keep their own fixed size.
ui.atomicContextReferences
- Type:
boolean - Default:
true
In the prompt editor, treat @file/#symbol/~git/$context references as single units: arrow keys skip over them and Backspace/Delete removes the whole reference at once. In output, format clickable local references as compact chips. Clicking or tapping a chip opens it, and right-clicking or long-pressing it offers Go to Reference, Copy Reference, and Send as Plain Text; when off, editor references edit character by character and output uses ordinary text links.
ui.showCostEstimates
- Type:
boolean - Default:
true
Show token cost estimates in dashboard and CLI statistics.
ui.offerTrustForUntrustedFileLinks
- Type:
boolean - Default:
true
Allow AI-generated file links outside trusted roots to offer a Trust Parent Folder action. Untrusted paths are always blocked unless their parent is explicitly trusted; this only controls whether the trust offer appears.
ui.stepColorMode
- Type:
"none" | "harness" | "unique" - Default:
"none"
Choose how workflow step identity colors are rendered: none uses status colors only, harness uses harness colors, and unique assigns a distinct color to each step.
ui.harnessColors
- Type:
{ byHarness?, script? }
Controls the per-harness identity colors used to correlate workflow steps across the dashboard.
ui.harnessColors.byHarness
- Type:
{ copilot-cli?, claude-cli?, codex-cli?, … } - Default:
{}
Optional hex color overrides for each harness. Remove an override to follow the built-in theme-aware chart color.
Fields:
copilot-cli·stringclaude-cli·stringcodex-cli·stringopencode-cli·stringqwen-cli·stringantigravity-cli·string
ui.harnessColors.script
- Type:
string - Default:
"#808080" - Constraints: pattern
^#[0-9a-fA-F]{6}$
Hex color used for script steps.
ui.accessibility
- Type:
{ outputAnnouncements?, terminalScreenReaderMode? }
Screen-reader support in the dashboard.
ui.accessibility.outputAnnouncements
- Type:
"none" | "completions" | "streaming" - Default:
"completions"
What a screen reader is told about a run while you work elsewhere in the dashboard. 'completions' (the default) announces when a step starts, finishes or fails, when the AI asks a question or is waiting for input, and the final text of each response once it finishes. 'streaming' also reads the response a paragraph at a time while it arrives, at most one announcement every few seconds. 'none' announces nothing. Tool calls, thinking and diffs are only summarized ("edited 3 files"), never read out. Alt+L reads the last response on demand in every mode.
ui.accessibility.terminalScreenReaderMode
- Type:
boolean - Default:
false
Turn on screen-reader mode in the dashboard's Terminal tab, so a screen reader can read the terminal's text and follow new output. Browsers can't detect a screen reader, so this is off until you turn it on.
spelling
Spell checking in the prompt editor.
spelling.enabled
- Type:
boolean - Default:
true
Underline misspelled words in the prompt editor and offer spelling fixes. When off, the dictionary is not loaded at all.
spelling.words
- Type:
string[] - Default:
["ctrlyoke"]
Custom words the spell checker always accepts, added from the editor with **Add to dictionary**. User and workspace lists are combined, so a team can share project terms in the workspace file while each person keeps a personal list. A word saved in lowercase matches any capitalization (ctrlyoke also accepts Ctrlyoke and CTRLYOKE); a word with a capital letter must match exactly (GitHub does not accept github).
server
ctrlyoke hosted server settings.
server.autoStart
- Type:
boolean - Default:
false
Automatically start the hosted dashboard server when the VS Code extension activates. This is read at activation time; change it before reloading the window to affect startup.
server.port
- Type:
integer - Default:
4747 - Constraints: minimum 1 · maximum 65535
Port for the ctrlyoke hosted server. The port is selected when the server starts; restart the hosted server after changing it.
server.fallbackPorts
- Type:
integer[] - Default:
[]
Ordered ports to try, in order, if 'port' is already in use, before falling back to an OS-assigned port. Useful for a stable, bookmarkable URL across restarts when 'port' is often taken by another running instance. These ports are selected when the server starts; restart the hosted server after changing them.
server.theme
- Type:
"auto" | "light" | "dark" - Default:
"auto"
Color theme for the hosted server UI.
server.bindAddress
- Type:
string - Default:
"127.0.0.1"
Network interface to bind the server to. Use '127.0.0.1' for localhost only or '0.0.0.0' for all interfaces. The address is selected when the server starts; restart the hosted server after changing it.
server.publicHostname
- Type:
string - Default:
"" - Constraints: at most 253 characters · pattern
^$|^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$
Hostname other devices use to reach this computer from outside your network, such as a Tailscale MagicDNS name, a dynamic DNS name, or a public IPv4 address. Just the name: no https://, port, or path. Used only when the server listens on all interfaces: it is added to a generated HTTPS certificate (generate the certificate again after changing it) and offered under Connect via for the link and QR code. Leave empty to use only this computer's detected network addresses.
server.tls
- Type:
{ enabled?, certPath?, keyPath? }
TLS configuration for the hosted server.
server.tls.enabled
- Type:
boolean - Default:
false
Whether TLS is enabled.
server.tls.certPath
- Type:
string - Default:
""
Path to the TLS certificate file.
server.tls.keyPath
- Type:
string - Default:
""
Path to the TLS private key file.
server.iconBgColor
- Type:
string - Default:
"#3994BC" - Constraints: pattern
^#[0-9a-fA-F]{6}$
Background color for the workspace icon (hex, e.g. '#1076ba'). Applies to the SVG favicon and PWA homescreen icon.
server.iconFgColor
- Type:
string - Default:
"#051923" - Constraints: pattern
^#[0-9a-fA-F]{6}$
Foreground (path/stroke) color for the workspace icon (hex, e.g. '#ffffff'). Applies to the SVG favicon and PWA homescreen icon.
notifications
Notification settings.
notifications.vscode
- Type:
{ enabled? }
VS Code notification settings.
notifications.vscode.enabled
- Type:
boolean - Default:
true
Show VS Code notification popups for workflow and step completion and for hook events. Operational messages are controlled by notifications.toastLevel instead.
notifications.browser
- Type:
{ mode? }
Browser notification settings.
notifications.browser.mode
- Type:
"never" | "connectedOnly" | "push" - Default:
"never"
When to send browser notifications. 'connectedOnly' fires while the hosted dashboard is open; 'push' enables background push notifications.
notifications.toastLevel
- Type:
"all" | "warningAndError" | "errorOnly" | "none" - Default:
"all"
Minimum severity for operational toast/feedback popups, such as action results (save failures and validation errors); separate from completion notifications.
notifications.events
- Type:
{ workflowComplete?, promptComplete?, awaitingInput?, … }
Which events trigger notifications.
notifications.events.workflowComplete
- Type:
"all" | "failuresOnly" | "none" - Default:
"all"
When to notify on workflow completion.
notifications.events.promptComplete
- Type:
"all" | "failuresOnly" | "none" - Default:
"none"
When to notify on individual prompt completion.
notifications.events.awaitingInput
- Type:
boolean - Default:
true
Notify once each time the harness stops to ask you something: a permission prompt or a question. ctrlyoke listens to the one native hook that means this on each harness: permission and question notifications on Copilot CLI, Claude Code and Qwen Code, and permission requests on Codex CLI and OpenCode. Idle notifications and tool calls the harness approves on its own don't notify. Antigravity provides no such hook.
notifications.events.hookEvents
- Type:
{ stop?, sessionStart?, preToolUse?, … }
Which hook events trigger notifications. All default to false (opt-in).
notifications.events.hookEvents.stop
- Type:
boolean - Default:
false
Notify when the AI agent finishes responding.
notifications.events.hookEvents.sessionStart
- Type:
boolean - Default:
false
Notify when a new AI session is created.
notifications.events.hookEvents.preToolUse
- Type:
boolean - Default:
false
Notify before the AI invokes a tool.
notifications.events.hookEvents.postToolUse
- Type:
boolean - Default:
false
Notify after the AI receives the result of a tool call.
notifications.events.hookEvents.userPromptSubmit
- Type:
boolean - Default:
false
Notify when a user prompt is submitted to the AI.
notifications.events.hookEvents.permissionRequest
- Type:
boolean - Default:
false
Notify when the AI requests permission to perform an action.
notifications.events.hookEvents.notification
- Type:
boolean - Default:
false
Notify when the harness displays a notification, including prompts that may require user input.
notifications.events.hookEvents.error
- Type:
boolean - Default:
false
Notify when the harness reports a session-level error.
notifications.includeWorkflowName
- Type:
boolean - Default:
true
Include the workflow name in the notification message.
notifications.includePromptName
- Type:
boolean - Default:
true
Include the prompt name in the notification message.
notifications.onlyWhenWindowUnfocused
- Type:
boolean - Default:
true
Suppress notifications while the VS Code window or hosted dashboard is focused.
commit
Commit message generation settings.
commit.harness
- Type:
"copilot-cli" | "claude-cli" | "codex-cli" | "opencode-cli" | "qwen-cli" | "antigravity-cli"or"" - Default:
""
Harness to use for commit message generation. Empty = use the workspace default harness.
commit.model
- Type:
string - Default:
""
Model override for commit message generation. Empty = use the commit harness default.
commit.systemPrompt
- Type:
string
System prompt sent before the git diff. The diff is appended automatically.
Default value
Generate a conventional commit message based on the included git diff. Return ONLY the final commit message content based on the included diff — no explanation, no code fences, no author or co-author attribution lines. Treat the provided diff and any optional user draft as the complete context for composing the message; do not read extra instruction files or inspect other workspace files unless explicitly instructed. Follow the Conventional Commits format: one or more 'type(scope): short description' header lines (use multiple headers if the change covers multiple distinct features or fixes), followed by a blank line, then one or more body paragraphs explaining the implementation details of what changed and why. Use markdown formatting in the body to improve readability where appropriate. Use bullet points for lists where necessary. If you are explicitly instructed to submit the message with a tool, call that tool with the complete commit message and do not repeat the message outside the tool call.
Example format:
feat(auth): add OAuth2 login support
Implemented OAuth2 authorization code flow using the existing HTTP client. Token refresh is handled automatically on 401 responses. Session state is persisted to localStorage to survive page reloads
Only return or submit the commit message, no extra text. Here is the git diff to generate the commit message for:statusLine
Machine-only settings for providers that install a global statusline command.
statusLine.useDifferentFormatPerHarness
- Type:
boolean - Default:
false
Configure each harness's statusline format independently. When false (the default), every harness renders 'sharedFormat' and the per-harness 'format' values are left untouched but unused.
statusLine.sharedFormat
- Type: statusLineFormat
Statusline format every harness renders while 'useDifferentFormatPerHarness' is false.
Default value
[
{
"type": "field",
"field": "model"
},
{
"type": "literal",
"text": "·"
},
{
"type": "field",
"field": "context"
},
{
"type": "literal",
"text": "·"
},
{
"type": "field",
"field": "usage"
},
{
"type": "literal",
"text": "·"
},
{
"type": "literal",
"text": "edit in ctrlyoke",
"color": "gray"
}
]statusLine.byHarness
- Type:
{ claude-cli?, copilot-cli?, qwen-cli?, … }
Statusline configuration keyed by ctrlyoke harness ID.
statusLine.byHarness.claude-cli
- Type: statusLineSettings
Statusline settings for Claude CLI.
Default value
{
"enabled": true,
"customCommand": "",
"useCtrlyokeStyle": true,
"format": [
{
"type": "field",
"field": "model"
},
{
"type": "literal",
"text": "·"
},
{
"type": "field",
"field": "context"
},
{
"type": "literal",
"text": "·"
},
{
"type": "field",
"field": "usage"
},
{
"type": "literal",
"text": "·"
},
{
"type": "literal",
"text": "edit in ctrlyoke",
"color": "gray"
}
]
}statusLine.byHarness.copilot-cli
- Type: statusLineSettings
Statusline settings for Copilot CLI.
Default value
{
"enabled": true,
"customCommand": "",
"useCtrlyokeStyle": true,
"format": [
{
"type": "field",
"field": "model"
},
{
"type": "literal",
"text": "·"
},
{
"type": "field",
"field": "context"
},
{
"type": "literal",
"text": "·"
},
{
"type": "field",
"field": "usage"
},
{
"type": "literal",
"text": "·"
},
{
"type": "literal",
"text": "edit in ctrlyoke",
"color": "gray"
}
]
}statusLine.byHarness.qwen-cli
- Type: statusLineSettings
Statusline settings for Qwen Code.
Default value
{
"enabled": true,
"customCommand": "",
"useCtrlyokeStyle": true,
"format": [
{
"type": "field",
"field": "model"
},
{
"type": "literal",
"text": "·"
},
{
"type": "field",
"field": "context"
},
{
"type": "literal",
"text": "·"
},
{
"type": "field",
"field": "usage"
},
{
"type": "literal",
"text": "·"
},
{
"type": "literal",
"text": "edit in ctrlyoke",
"color": "gray"
}
]
}statusLine.byHarness.antigravity-cli
- Type: statusLineSettings
Statusline settings for Antigravity CLI.
Default value
{
"enabled": true,
"customCommand": "",
"useCtrlyokeStyle": true,
"format": [
{
"type": "field",
"field": "model"
},
{
"type": "literal",
"text": "·"
},
{
"type": "field",
"field": "context"
},
{
"type": "literal",
"text": "·"
},
{
"type": "field",
"field": "usage"
},
{
"type": "literal",
"text": "·"
},
{
"type": "literal",
"text": "edit in ctrlyoke",
"color": "gray"
}
]
}diagnostics
Logging and diagnostic output settings.
diagnostics.verboseLogging
- Type:
boolean - Default:
false
Enable verbose diagnostic logging for troubleshooting.
diagnostics.logRawCliOutput
- Type:
boolean - Default:
false
Log raw CLI output to the extension output channel.
Top-level settings
$schema
- Type:
string
Schema URL used by JSON-aware editors for validation and completion.
schemaVersion
- Type:
integer - Default:
1 - Constraints: minimum 1
Settings format version. Absent means format 1. ctrlyoke stamps this field when it writes settings; an older host reads newer settings best-effort but refuses to write them.
modelPricing
- Type: map of map of
{ inputPerMTok, outputPerMTok, cachedInputPerMTok?, … } - Default:
{}
Optional per-harness/per-model USD pricing overrides. User and workspace scopes merge per model, with workspace rates taking precedence for the same model. Rates are USD per one million tokens.
Fields:
inputPerMTok·number· requiredoutputPerMTok·number· requiredcachedInputPerMTok·numbercacheWritePerMTok·numberreasoningPerMTok·number
Shared types
languageServerDefinition
- Type:
{ command, languages, extensions, … }
Command, supported languages, and root markers for one managed language server.
languageServerDefinition.command
- Type:
string[] - Required: yes
- Constraints: at least 1 item(s)
Executable followed by its arguments. For example: ["pyright-langserver", "--stdio"].
languageServerDefinition.languages
- Type:
string[] - Required: yes
LSP language ids served by this definition.
languageServerDefinition.extensions
- Type:
string[] - Required: yes
File extensions served, without a leading dot.
languageServerDefinition.rootMarkers
- Type:
string[] - Required: yes
Files or directories used to find the project root.
languageServerDefinition.env
- Type: map of
string
Environment variables passed to the server process.
statusLineFormat
- Type: array of (
{ type: "field", field, label?, … }or{ type: "literal", text, color? })
Ordered statusline segments. Used both for a provider's own 'format' and for the shared 'sharedFormat' that applies to every harness when 'useDifferentFormatPerHarness' is false.
When type is "field":
Fields:
field·"brand" | "model" | "context" | "usage" | "usage1" | "usage2" | "version" | "cwd" | "sessionId" | "branch" | "date" | "time"· requiredlabel·stringcolor·"default" | "red" | "yellow" | "green" | "cyan" | "blue" | "magenta" | "white" | "gray"
When type is "literal":
Fields:
text·string· requiredcolor·"default" | "red" | "yellow" | "green" | "cyan" | "blue" | "magenta" | "white" | "gray"
statusLineSettings
- Type:
{ enabled?, customCommand?, useCtrlyokeStyle?, … }
Statusline settings for one harness.
statusLineSettings.enabled
- Type:
boolean - Default:
true
Install ctrlyoke's statusline command for this harness.
statusLineSettings.customCommand
- Type:
string - Default:
""
Command to run for the provider's statusline output.
statusLineSettings.useCtrlyokeStyle
- Type:
boolean - Default:
true
Show ctrlyoke's branded statusline instead of custom-command output.
statusLineSettings.format
- Type: statusLineFormat
Statusline format for this harness, used only while 'useDifferentFormatPerHarness' is true.