Skip to main content
Nika’s editor support has two tiers: (1) JSON Schema validation, which works in any editor with yaml-language-server, and (2) the nika lsp language server built into the binary, plus the VS Code extension built on it.
v: the binary ships nika spec --schema, nika lsp, nika mcp and nika wire. nika init writes the repository’s schema wiring and agent rules; nika wire <client> adds the MCP server to one agent client. nika lsp is the editor path qualified with this release.

Tier 1: JSON schema validation (today)

Any editor with yaml-language-server can validate .nika against the workflow schema.
Install the YAML extension (Red Hat). It only reads YAML documents, so map .nika to YAML and point the schema at it in settings.json:
settings.json
nika init writes exactly this .vscode/settings.json for the current repository.

In-file schema hint

Add one comment at the top of any .nika so the schema works with zero editor configuration:

What tier 1 gets you

Field autocomplete

Verb keys, provider names, model identifiers, capability parameters.

Inline errors

Missing required fields, schema mismatches, wrong types.

Hover docs

Every field documented inline: descriptions come from the JSON Schema.

Format on save

Via prettier-plugin-yaml or LSP-driven formatting.

Tier 2: nika lsp and the VS Code extension

The editor extension, frozen at 0.120 and not qualified with 0.124: use nika lsp and the JSON Schema (the schema is Tier 1 above; the language server follows). If you keep the extension (supernovae.nika), set its nika.server.path setting to your installed nika, and if the editor and the command line disagree, trust nika check. Known limits.
The extension, frozen at 0.120, is published on both registries, the VS Code Marketplace and OpenVSX, so Cursor, Windsurf and VSCodium install it natively. It consumes the same binary the CLI runs: every verdict in the margin is real nika check output, never a client-side guess. Workflow files carry the language identity out of the box — the four verbs color distinctly in every theme (Nika: Apply Verb Colors writes the exact canonical hues), a 🦋 badge marks workflows in the Explorer without replacing your icon theme, and verbs, tools and permits: are ctrl-clickable to their reference pages.
First activation with the engine present silently wires MCP for the host (nika wire, idempotent) — install the extension, accept the one-click verified download (SHA256SUMS, mandatory), and MCP · LSP · diagnostics are live in the same window. The 🦋 status menu then opens on your next step, whichever it is: no binary → Finish Setup (one orchestrated gesture: download → wire → optional nika init, repo writes stay consented → recap) · repo not equipped → Init this project (agent rules · MCP · schema wiring, skip-if-exists) · fresh workspace → Run the 10-second proof (the offline hello, zero keys) · already working → the active file’s Run · Check · Graph. The sidebar’s welcome view says the same thing — one journey, every surface. nika.autoSetup: false opts out of all of it.
nika check --json painted as diagnostics while you type: DAG conformance, secret leaks and egresses, permits escapes, schema findings, unknown tools, typo’d or missing tool args (with the engine’s did-you-mean), provably dead when: gates, hints. The finding families mirror the engine’s is_clean list, so the editor’s verdict IS the binary’s exit code. Dirty buffers pipe over stdin (nika check -) — keystroke-fresh audits, nothing written to disk. Machine-applicable fixes (the add "X" to permits.<path> grammar) apply as quick fixes.
Every structural line grows its own door (0.100+): the envelope reads top-to-bottom — GitHub · Check · DAG · Run · Explain sit above nika: (the identity line · mark AND name · nine keys), and the audit verdict with its cost ceiling above tasks:. model: lines open the provider picker (local inference first, fed by the binary’s own catalog). And each of the four verb keys offers proven starters: invoke: lists every builtin this binary carries with an args skeleton derived from the tool’s own schema (required args as # SLOT lines), while infer: / exec: / agent: insert the spec’s canonical shapes — each starter validated against the conformance oracle before it ships (the spec’s verb-starters source of truth). Picking replaces the block surgically: one edit, one undo, and a moved line refuses a blind write.
The file as a graph: infer cards show their prompt, exec cards their $ command, invoke cards their tool + args — before any run. Model chips edit through a provider picker fed by the binary’s own catalog (nika catalog --json — exact models, capabilities), drag an out-port to wire an edge (a with: binding or an after: entry), cost badges and ⚠ audit chips ride the cards, and semantic zoom keeps 100-task graphs readable.
A ▶ Run / ▶ mock / ■ Stop pill drives the run without leaving the panel — ▶ mock streams run --model mock/echo (deterministic, zero keys, zero network). On a 0.93+ engine, ↻ re-runs only what changed (engine --resume: unchanged tasks cache-hit visibly). Every recorded run in .nika/traces/ replays as a scrubbable timeline — replay re-renders, never re-executes. And paused runs ask: a nika:prompt task pauses the run (ADR-099 · exit 4, a pause is not a failure) — the verdict goes amber ⏸ with the question itself, the answer control matches the mode (confirm · choice · input), and the resume rides the exact journal the engine wrote.
Press F5 on a workflow to launch the Nika debug adapter (the engine’s nika dap, a Debug Adapter Protocol server over stdio, so the debugger is the same one any DAP editor speaks). It debugs a recorded run, not a live one: set breakpoints on tasks, then step forward and backward through the journal the engine wrote — inspect each task’s output, cost and ADR-099 identity hashes at that point in time. Like replay, it re-executes nothing; it time-travels what already happened, so a breakpoint costs no tokens and hits no network.
Recorded runs hash-chain their journals (engine 0.97+), and the editor carries the proof end to end: the run’s verdict banner, the Runs-view tooltip and the run report all show the same chain head the engine printed. A journal that fails the walk gets a shield — its claims are unverified. Verify Journal (right-click a run) asks the engine itself (nika trace verify): intact with its head, BROKEN at its exact line, or unchained for pre-0.96 journals (nothing to verify, nothing to distrust). Reproduce Run compares two recorded runs and classifies every task — reproduced · NONDETERMINISTIC (the flaky task, named) · authored · environment — by reading two files: no re-run, no spend.
Nika: Preflight renders the flight plan before any token: cost (ceiling · an uncapped task stays a loud floor), every model resolved against the catalog’s key requirements (local providers marked sovereign), secrets/env checked against the actual environment, permits + capability escapes, and the wave-by-wave plan — missing requirements headline as blockers. On the canvas, lineage mode follows the data: click a card (or put the caret in ${{ tasks.x… }}) and the producer + every consumer stay lit while the rest fades. After a run, task rows grow artifact children (images · audio · manifests) with provenance, run diffs lead with the first divergence, and the replay says when the workflow’s definition changed under a recorded journal.
Nika: Golden Test runs nika test <file> (mock provider · offline · deterministic) against <file>.golden.json, and Update the Golden re-pins it — the offline CI gate without leaving the editor. The golden pins the workflow’s OUTPUT contract: schema drift and output renames go red with a precise diff; prompt wording alone does not.
Completions, hover and expression intel come FROM the binary (nika spec --schema · nika spec --canon · nika catalog --tools --json): task fields, per-verb bodies, the closed builtin set, provider-prefixed model: values, ${{ }} reference completion with go-to-definition, task rename across all syntactic homes. A new field in the engine lights up with zero extension update.
nika_check / nika_explain / nika_graph registered as editor LM tools — in-editor agents validate through the real oracle. One command wires MCP config + agent rules (nika wire under the hood), and VS Code 1.101+ discovers nika mcp natively.
The extension probes what the binary ACTUALLY ships (--help, never a hardcoded matrix): a dev build from engine main lights features up early, an older brew binary keeps its fallbacks — same extension, zero release needed.

nika lsp (any editor)

The engine’s own language server rides stdio for editors outside the VS Code family: hover, completion (. / [ triggers), go to definition, document symbols, push diagnostics — and quickfix code actions (engines after 0.99.0): the nika check --fix rename engine projected, so a typo’d tool, arg, field or task reference offers its did-you-mean as a one-click repair in any LSP editor. Wire it as a generic LSP command (nika lsp) in Zed, Neovim or Helix alongside the Tier-1 schema.

The audit, as you type. nika lsp underlines the problems in a workflow while you edit it. One keystroke fixes the misspelled task name it points to; the rest of the fix empties the problems list before anything runs. Diagnostics captured from the real language server, nika lsp 0.121.0; the editor window is an illustration.

GitHub display

GitHub Linguist does not register Nika or .nika. A repository .gitattributes line *.nika linguist-language=YAML is the supported highlighting mitigation. It affects display and classification only, not Nika semantics, and is not a claim of native GitHub language registration.

File and folder icons

*.nika files carry the butterfly mark out of the box wherever the icon theme honors language icons (Seti — VS Code’s default — does; the extension contributes it). Folder icons are the icon theme’s territory, not an extension’s, so .nika/ — the flight-recorder home — needs one line in your settings until the upstream icons land:
Map .nika/ to the existing flow folder icon today:
settings.json
Native butterfly icons (file + folder) are in review upstream — once merged, delete the association and both arrive with the theme.

Status in 0.123

Next

Schema reference

.nika top-level keys + workflow envelope.

YAML syntax

Full grammar for every verb step.

First workflow

Write, check and run a workflow by hand.

Agents

Brief your coding agent and give it the read-only oracle.