Core concepts
Harness
Each CLI coding agent you run through ctrlyoke is a harness. ctrlyoke handles each one's invocation, sessions, permissions, MCP servers, and hooks, so the same workflow runs on any of them.
ctrlyoke currently supports:
antigravity-cliclaude-clicodex-clicopilot-cliopencode-cliqwen-cli
Workflow
A workflow is a .ctrlyoke.yaml (or .yml), .ctrlyoke.json, or .prompt.md file that describes work to run. YAML and JSON support multi-step automation. Markdown prompt files are the simplest one-step format.
Durable workflows and generated files
Dashboard work is ephemeral. By default, run history is user-scoped at ~/.ctrlyoke/projects/<slug>-<hash12>/.runs/ (or under $CTRLYOKE_HOME when that environment variable is set), keyed from the workspace path; it is outside the workspace and harness sandbox because only ctrlyoke reads it. Setting storage.runHistoryLocation: "workspace" keeps it beside the repo at .ctrlyoke/.runs/ for locality or durability, but workspace mode still ignores .runs/ and neither mode makes runs shareable. storage is a user-only setting: set it in ~/.ctrlyoke/settings.json or the dashboard's Settings page, not in a workspace settings file. User-level, project-keyed session history is also the familiar pattern used by Claude and Codex.
attachments/ and prompts/ stay ephemeral and workspace-scoped under .ctrlyoke/. Harnesses read those files through @ references, so they must remain inside the workspace sandbox.
Use the dashboard's Save button when a workflow is worth keeping: it writes the workflow plus its dependencies, copying inline attachments into a sibling <workflow>.assets/ directory and inlining lone prompt-file bodies. A workflow you hand-author anywhere in the repo or promote to a template is also durable; templates are the reusable form of a workflow you run often, while saving produces a copy. The workflow file and its sibling assets directory can be moved or copied together to another directory or repository and still resolve. This carries generated dependencies only; references such as @src/foo.ts, committed prompt files, and .ctrlyoke/scripts/** still require the repository they operate on.
The generated .ctrlyoke/.gitignore ignores workspace runtime entries such as .runs/, attachments/, prompts/, logs/, and temp/, and it ignores itself. While that last .gitignore line is present, ctrlyoke treats the file as generated and restores any default entry you delete on the next activation. To take ownership of the file, delete its .gitignore line first; ctrlyoke then leaves it untouched. Sharing an individual run is not supported yet. Managed-worktree landing permits runtime files you deliberately track, including prompts and attachments, but blocks non-ignored untracked runtime output. It always blocks certs/, notifications/, temp/, and logs/, even if tracked, because those directories can contain secrets or ephemeral transport data. settings.json is tracked by default; the server.tls.certPath and server.tls.keyPath settings are machine-local paths.
Managed worktree runs keep the initiating checkout's run history. Opening a worktree directory directly as its own VS Code workspace gives that directory its own history. Home directories under OneDrive or Dropbox sync user-scoped history, but simultaneous runs of the same project on two synced machines are unsupported because PIDs and file locks are machine-local.
Step
A workflow steps array can contain two kinds of step:
| Type | Purpose |
|---|---|
| Prompt step | Sends a prompt to a harness |
| Script step | Runs a shell command without any AI interaction |
See Script steps for how scripts run and pass. Prompt steps default to type prompt, so the type field is optional unless you want to be explicit.
Each step's replies, commands, file changes and verdicts appear in the output pane, where you can also hide individual steps' output. See The output pane.
Parallel groups
A parallel queue item forks a flat group of prompt or script steps and joins before the next queue item. The group width is bounded by queue.maxParallelSteps; setting it to 1 keeps the same workflow sequential. Members are for independent work and share one workspace, one run timeline, and one managed or named worktree per run. There is no per-member isolation or automatic merge in v1. Terminal controller arbitration is per workflow, not per session. Use the following step after the join to synthesize the members' settled output. See Parallel steps.
Final step
finalStep runs after the queue completes. It is useful for review passes, post-processing, or dynamic workflows that append their own follow-up steps.
If the final step has mcpServers: ["ctrlyoke"] and appends more prompts, ctrlyoke runs the new queue items and then executes the final step again.
Session
A session is the underlying conversation or thread maintained by a harness. ctrlyoke can:
- continue the previous step's session, which is the default (
resumeSession: true) - start a new session with
resumeSession: false - resume a specific earlier step with
sessionId: 1 - resume an exact harness session ID string
- resume the most recent final step's session with
sessionId: finalStep
Session reuse is provider-aware. ctrlyoke does not try to resume a Claude session in Copilot or the other way around.
Context references
Prompts can include structured references that the prompt editor understands:
| Syntax | Purpose |
|---|---|
@path/to/file.ts | Attach a full file |
@path/to/dir/ | Attach a directory tree |
@./path/to/file.ts, @../path/to/file.ts | Attach a file relative to the workflow file |
#selection:path/to/file.ts:10-25 | Attach a line range |
#selection:./path/to/file.ts:10-25 | Attach a line range relative to the workflow file |
#sym.<kind>:path/to/file.ts:SymbolName:42-60 | Attach a symbol definition; ctrlyoke inserts the kind, while #sym:path:SymbolName:42-60 remains valid and generic |
~diff, ~staged, ~stash:0, ~<commit> | Attach git change context |
$previous, $previous:3, $all, $step:1 | Inject prior ctrlyoke output |
For @, #selection:, and #sym: references, a leading ./ or ../ resolves from the workflow file's directory. Standalone prompt-file paths follow the separate rules in Prompt step fields, including which values count as paths and where ctrlyoke looks for them. Saving a workflow inlines such a prompt file's body, while inline context references may be copied into the sibling assets directory.
You don't have to type references by hand. In VS Code, right-click a file, folder, selection, symbol, commit or Output panel text and choose Add … to ctrlyoke to insert the matching reference into the prompt editor, or right-click a workflow file and use the Run with ctrlyoke submenu to load, run or queue it. See Adding context to the prompt editor and Run with ctrlyoke submenu.
End conditions and pre-conditions
These are script-based gates:
- Pre-condition runs before a prompt and can continue, skip, or stop
- End condition runs after a prompt and can continue, retry, or stop
Use them when a workflow should react to actual project state instead of trusting the model's self-report.
Script failures and validation failures
onFail handles a script that ran and returned a comparison result that did not match. errorBehavior handles a script that could not run, timed out, or was terminated externally. For script steps, errorBehavior.onError: continue continues the workflow while leaving that step marked failed. A missing shell command is treated as a run error; shell exit codes 126 and 127 are used for this detection, so a shell script that intentionally returns either code is also classified as a run error.