Skip to main content
Nika’s editor story has two tiers: (1) generic JSON-Schema validation that works with any yaml-language-server-compatible editor, and (2) the nika lsp server plus the VS Code/Cursor extension for deeper workflow intelligence.
v state: the binary ships nika spec --schema, nika lsp, nika mcp, and nika wire. Use nika init for repo-local schema/rules, or nika wire <client> for explicit MCP client setup.

​
Tier 1: JSON schema validation (today)

Any editor with yaml-language-server can validate .nika.yaml against the workflow schema.
Install the YAML extension (Red Hat). It picks up the schema via the # yaml-language-server directive at the top of .nika.yaml, or via settings.json:
settings.json
Or let nika init write this wiring for the current repo.

​
In-file schema hint

Add one comment at the top of any .nika.yaml 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: the extension (VS Code · Cursor · Windsurf · VSCodium)

One extension, 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 — a GitHub lens above nika:, Check · DAG · Run above workflow:, Explain above description:, and the audit verdict with its cost ceiling above tasks:. model: lines open the provider picker (local-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.
Every run hash-chains its journal (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.

​
File and folder icons

*.nika.yaml 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.

​
Roadmap

​
Next

Schema reference

.nika.yaml top-level keys + workflow envelope.

YAML syntax

Full grammar for every verb step.

First workflow

Preview of the target first-run experience.

Constellation

When each crate admits.