VS Code Extension#
oxo-flow ships a first-party VS Code extension (publisher
traitome,
extension id traitome.oxo-flow) that turns VS Code into a full editor for
.oxoflow pipelines: smart syntax, schema-driven completion, background
diagnostics, canonical formatting, and one-click access to the CLI lifecycle.
The extension lives in editors/vscode/
and is released in lockstep with the engine: every oxo-flow release attaches
the same version as a VSIX (with a .sha256 checksum) to the GitHub release
and publishes it to Open VSX.
About the VS Code Marketplace
CI publishes the extension to both marketplaces — the VS Code
Marketplace
(VSCE_PAT, live since v0.31.0) and Open VSX
(OVSX_PAT) — so every VS Code variant is covered:
- VS Code Marketplace — stock VS Code searches it by default.
- Open VSX — VSCodium, Cursor, Windsurf and most forks search it by
default; the same
traitome.oxo-flowid is there. - Offline VSIX — download the release artifact and install it with one command (below); this works in stock VS Code and any fork.
Install#
VSCodium / Cursor / Windsurf and most VS Code forks search Open VSX by default — install the extension from the Extensions view like any other, or:
Language support#
.oxoflow files get a dedicated language (oxoflow), not a TOML alias:
- Syntax highlighting — full TOML grammar plus oxo-flow specifics:
[[rules]]headers,{sample}-style wildcards, and{input[0]}/{output}template placeholders inside shell commands; invalid string escapes are flagged. - Folding — each
[table]/[[rules]]section folds independently. - Snippets — type
pipeline,rule,wildcard-rule,conda-rule,when-rule,config,cluster-slurm, … (see the snippet suggestions).
Smart completion and hover docs#
Completion data is generated from the canonical oxoflow-v1 JSON Schema
(docs/schema/oxoflow-v1.schema.json, the same artifact oxo-flow schema
exports) at build time, so the editor can never drift from the engine. It
covers:
- top-level tables and their properties (
[workflow],[ai],[wildcard_constraints],[cluster], …) - all 53
[[rules]]properties, with hover documentation for each - enum values where the schema constrains them (rule
checksum, clusterbackend, configtype, …) depends_on/extendscomplete rule names defined in the current fileenv_groupcompletes[env_groups.*]groups from the current file- environment backend keys (
conda,docker,singularity,modules,conda_prefix, …) insideenvironment = { … }
Diagnostics#
When the oxo-flow CLI is available, the extension runs validate --json
(and lint --json, optional) in the background and surfaces the findings as
Problems-panel diagnostics:
- findings are anchored to the failing rule's
name = "..."line when the CLI reports a rule - validate errors, lint warnings/best-practice hints, and missing-input warnings are deduplicated across the two commands
- trigger on save by default (
oxo-flow.diagnosticMode: save); switch totypefor debounced live diagnostics oroffto disable
Unsaved buffers are diagnosed as they are shown. The CLI reads workflows
from a path, so a dirty buffer is staged as a temporary hidden .oxoflow
file beside the document before validate/lint run on it — relative
[[include]] and sample-pattern resolution are unchanged, and the snapshot is
always deleted. Diagnostics therefore describe the editor content, never the
stale saved file; the Validate/Lint commands use the same snapshot path when
the buffer is dirty. If the snapshot cannot be created (read-only directory,
disk error), the extension refuses with an UNSAVED warning telling you to
save — it does not quietly report the saved file's findings.
AI pipeline generation#
oxo-flow: Generate Pipeline with AI… picks a backend from
oxo-flow.ai.backend (auto prefers a configured CLI provider, otherwise an
editor language model). The CLI backend runs
oxo-flow template "<description>" --ai -o <file> as a task, where the
engine's own generation loop owns validation.
The editor-model backend is validate-before-apply: the model's draft is
staged as a temporary sibling .oxoflow snapshot and grounded through
oxo-flow validate (the same CLI path diagnostics use). On failure the
CLI's structured findings — code, message, rule and hint, parsed from the
--json report — go back to the model for exactly one repair round, and the
repaired draft is validated again. Only a passing pipeline is written to the
chosen destination — an invalid generation (including a failed repair) is
surfaced as an error, the findings and the rejected draft appear in the
oxo-flow output channel, and the destination file is left untouched.
Infrastructure failures are reported as such, not as validation failures: if
oxo-flow cannot be launched (check oxo-flow.executablePath), the check
times out, or the draft cannot be staged (read-only directory), generation
names that cause, writes nothing, and does not spend the single repair round
on a condition the model cannot fix.
Formatting#
oxo-flow: Format Document (and the standard Format Document action) runs
the engine's canonical TOML formatter (oxo-flow format) on the current
buffer — unsaved changes included.
To format automatically on save, enable oxo-flow.formatOnSave (off by
default). It is an independent opt-in: it formats .oxoflow documents on
save even when the global Editor: Format On Save is off for other
languages, and stays out of the way when that toggle is already on (VS Code
then invokes the same formatter through the standard pathway).
Run CodeLens#
Every [[rules]] header shows two CodeLens buttons when you open a
.oxoflow file:
- ▶ Run this rule — runs
oxo-flow run -t <name>, which the CLI resolves to that rule plus its upstream closure. - ▶ Run to here — repeats
-tfor every rule at or before this one in file order, so the pipeline runs up to (and including) this rule.
Both honor oxo-flow.runArgs and reuse the cached run task. Editors who
prefer the keyboard can pass the same targets by hand:
Run Pipeline accepts target in its task definition, or list several
rules via repeated -t in extraArgs.
Onboarding walkthrough#
First launch surfaces a Get Started with oxo-flow walkthrough
(Help → Welcome → Walkthroughs, or "Walkthroughs…" from the
command palette): four checklist steps that light up as you go —
- Welcome to oxo-flow — what a
.oxoflowpipeline is and what the editor adds. - Connect the extension to the CLI — install the binary or set
oxo-flow.executablePath; completes when the setting changes or settings open. - Open or create a pipeline — open a
.oxoflow, scaffold withoxo-flow init, or generate with AI. - Validate, then run — the static-gates-first habit; completes on the first Validate or Run.
CLI lifecycle commands#
All commands are prefixed oxo-flow: in the command palette; the status bar
item shows the detected CLI version and opens a quick pick of all of them.
.oxoflow editors also get Run and Validate buttons in the editor
title bar.
| Command | CLI equivalent |
|---|---|
| Run Pipeline (Cmd/Ctrl+Alt+R) | oxo-flow run <file> + oxo-flow.runArgs |
| Run Rule Targets… (CodeLens) | oxo-flow run <file> -t <name>… (▶ Run this rule / ▶ Run to here above each [[rules]]) |
| Dry Run (plan only) | oxo-flow dry-run <file> |
| Validate Pipeline (Cmd/Ctrl+Alt+V) | oxo-flow validate <file> --json |
| Lint Pipeline (Cmd/Ctrl+Alt+L) | oxo-flow lint <file> --json |
| Format Document | oxo-flow format <file> |
| Show DAG Graph (Cmd/Ctrl+Alt+G) | oxo-flow graph <file> [-f <format>] — quick pick over ascii, mermaid, dot, dot-clustered, tree, metro (last choice remembered) |
| Resume from Checkpoint | oxo-flow resume <checkpoint> (quick pick over **/.oxo-flow/checkpoint.json) |
| Show Run Status | oxo-flow status <checkpoint> --timing (quick pick over checkpoint files) |
| Clean Outputs… | oxo-flow clean <file> -n preview → confirmation → --force (optionally --orphans) |
| Generate Pipeline with AI… | CLI backend: oxo-flow template "<description>" --ai -o <file> as a task; editor-model backend: oxo-flow validate gate before writing (see AI pipeline generation) |
| Show AI Provider Status | oxo-flow ai |
| Export JSON Schema | oxo-flow schema > oxo-flow-schema.json |
| Open Documentation | opens the guide in the system browser |
| Open Settings | jumps to oxo-flow.executablePath in VS Code settings |
| Report Issue / Suggest Improvement | opens a pre-filled GitHub issue with sanitized diagnostics (versions, platform, remote, settings, output tail — home paths masked; pipeline content is never attached) |
The core pipeline commands (Run, Run At Target…, Dry Run, Validate, Lint,
Format Document, View DAG) surface in the command palette only while an
.oxoflow editor is active, so the palette stays quiet in other files; the
remaining commands (Resume, Generate with AI, Clean, Status, AI Status,
Export Schema, Open Docs/Settings, Report Issue, command picker) are always
available. Long-running operations (validate, lint, clean preview, status,
AI status) show a progress notification. Error toasts carry a Report Issue button that opens the
report with the error pre-attached.
Run / Dry Run / Graph execute as tasks (type: "oxo-flow"), so they get
a dedicated terminal panel, re-run support, and tasks.json customization:
{
"type": "oxo-flow",
"workflow": "pipeline.oxoflow",
"kind": "run",
"jobs": 8,
"keepGoing": true,
"target": "results/all",
"extraArgs": ["--profile", "slurm"]
}
kind selects the lifecycle: run (default), dry-run, graph,
resume, or generate. For resume, workflow holds the checkpoint path
(e.g. .oxo-flow/checkpoint.json); for generate, the task runs
oxo-flow template "<description>" --ai -o <file> with extraArgs[0] as
the description.
Settings#
| Setting | Default | Description |
|---|---|---|
oxo-flow.executablePath |
oxo-flow |
Path to the CLI binary (machine-overridable, e.g. for SSH remotes) |
oxo-flow.diagnosticMode |
save |
off, save, or type |
oxo-flow.enableLintDiagnostics |
true |
Merge lint findings into the Problems panel |
oxo-flow.runArgs |
[] |
Extra arguments for Run Pipeline |
oxo-flow.formatOnSave |
false |
Format the document with oxo-flow format on every save |
oxo-flow.autoOpenGraph |
false |
Open the DAG graph after a successful run (last picked format, default ASCII) |
oxo-flow.ai.backend |
auto |
Backend for Generate Pipeline with AI: auto uses the CLI provider when configured, else the editor language model; cli / ide force one path (the ide path validates every draft, re-validates the one repair round, and only then writes the file) |
oxo-flow.trace |
false |
Log CLI invocations to the oxo-flow output channel |
Remote and untrusted workspaces#
The extension declares extensionKind: workspace, so in SSH / dev-container
sessions it runs on the remote where the pipelines and the CLI live. It
refuses to activate in untrusted workspaces because it shells out to the
local binary.
See also#
- Editor Setup — other editors (Zed, Helix, Neovim, JetBrains, …) and Even Better TOML schema association
- Workflow Format — the full
.oxoflowreference