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 the VS Code Marketplace (VSCE_PAT) and the listing goes live at the next tagged release; until then, two channels already cover every VS Code fork:

Open VSX — VSCodium, Cursor, Windsurf and most forks search it by default; the same traitome.oxo-flow id 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#

Open VSX (recommended for forks)Offline VSIX (works in any VS Code)

VSCodium / Cursor / Windsurf and most VS Code forks search Open VSX by default — install the extension from the Extensions view like any other, or:

codium --install-extension traitome.oxo-flow

Download oxo-flow-vscode-v<version>.vsix (with a .sha256 checksum) from the release page and install it directly:

code --install-extension oxo-flow-vscode-v0.23.2.vsix

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 51 [[rules]] properties, with hover documentation for each
enum values where the schema constrains them (rule checksum, cluster backend, config type, …)
depends_on / extends complete rule names defined in the current file
env_group completes [env_groups.*] groups from the current file
environment backend keys (conda, docker, singularity, modules, conda_prefix, …) inside environment = { … }

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 to type for debounced live diagnostics or off to disable

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 -t for 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 .oxoflow pipeline 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 with oxo-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…	`oxo-flow template "<description>" --ai -o <file>`
Show AI Provider Status	`oxo-flow ai`
Export JSON Schema	`oxo-flow schema > oxo-flow-schema.json`
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)

Pipeline commands surface in the command palette only while an .oxoflow editor is active, so the palette stays quiet in other files. 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.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.