yaml-language-server, and (2) the nika lsp
language server built into the binary, plus the VS Code extension built on
it.
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 withyaml-language-server can validate .nika against
the workflow schema.
- VS Code
- Neovim
- Helix
- Zed / Cursor / JetBrains
.nika to YAML and point the
schema at it in 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
Inline errors
Hover docs
Format on save
prettier-plugin-yaml or LSP-driven formatting.Tier 2: nika lsp and the VS Code extension
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.
Install = everything on
Install = everything on
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.Check-as-you-type — the full audit
Check-as-you-type — the full audit
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.Lens doors — the file completes itself
Lens doors — the file completes itself
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 DAG canvas — content-first
The DAG canvas — content-first
$ 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.Run · resume · replay
Run · resume · replay
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.Debug (F5) — time-travel a recorded run
Debug (F5) — time-travel a recorded run
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.Prove it ran — chain · verify · reproduce
Prove it ran — chain · verify · reproduce
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.Preflight · lineage · the run understood
Preflight · lineage · the run understood
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.Golden testing, one command
Golden testing, one command
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.Schema-derived intelligence
Schema-derived intelligence
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.Agent-native
Agent-native
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.Capability-gated by construction
Capability-gated by construction
--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:
- Material Icon Theme
- vscode-icons
.nika/ to the existing flow folder icon today:Status in 0.123
Next
Schema reference
.nika top-level keys + workflow envelope.