how it works
Five commands, four subsystems, one file.
Nika is a loop you can hold in your head: see it work, make it yours, audit it, run it, read back what happened. Underneath sit four subsystems, and each one is explained here rather than assumed · how your words find a workflow, how tasks link, what a run may touch, and how anyone can verify what it did.
the loop
One arc, five doors
Captured from one real run, in one directory, in this order. Nothing below is illustrative: the cost warning is what an unpriced local model really earns, and the timing is what that machine really took.
- 01 · nika try
See it work before you own anything
The showroom. A canonical workflow runs offline against a mock model · no keys, no flags, nothing written to your disk. Bare, with no slug, it lists the shelf: thirteen teaching steps and twenty-six real jobs.
The rehearsal says it is a rehearsal. A mock model echoing your prompt is never dressed up as an answer.
nika trynika try 01-hello 🦋 nika · hello · 1 task permits ✓ declared boundary · default-deny ✔ greet infer · mock/echo 1ms ── 1/1 done · ≥ $0.00 (1 unpriced) · elapsed 0.0s ────────────── said "mock(echo) · Say hello in French, in one sh…" rehearsal · a mock model echoed the prompt — not a real answer
real output · nika 0.107.0 · nika try 01-hello · re-captured at every release
- 02 · nika new
One door to create
Describe the job in plain words and it routes; name a slug or a skeleton and it lands verbatim, ingredients included. Asking it with a lone question mark lists the skeletons the pack ships.
The door that creates the file also names the next two doors. The loop teaches itself.
nika newnika new 01-hello hello.nika.yamlhello.nika.yaml ← example `01-hello` · yours now — `nika check hello.nika.yaml` then `nika run hello.nika.yaml`
real output · nika 0.107.0 · nika new 01-hello hello.nika.yaml · re-captured at every release
- 03 · nika check
The audit runs before a token is spent
Twelve verdicts over the file as written: the cost ceiling, where secrets can flow, the types, the tools, the permits boundary. Every finding teaches its own fix.
A local model is unpriced, not free · it draws your watts, and the audit refuses to print a comfortable zero.
nika checknika check hello.nika.yaml ⚠ COST bounded portion $0.0000 no total ceiling · 1 unpriced task · prompts, exec + mcp unpriced · prices 2026-07-28 greet ollama/qwen3.5:4b UNBOUNDED — no catalog price (local/unknown model) ○ ENERGY unpriced — no sourced Wh figure for any task model · a local model draws your watts · never 0 Wh ✔ SECRETS no declared secret reaches an effect · model echo untracked ✔ TYPES deep references fit the shapes tasks declare ✔ PERMITS literal + const: args fit the boundary ✔ TRIFECTA no lethal trifecta over the declared permits: without a human gate ✔ JOURNEY internal · 0 sources · 0 destinations · 1 model endpoint · no secret reaches a cloud destination ⚠ audited · 1 task · 1 wave · permits declared · est unbounded · 1 unpriced task · 0 hints · risk unbounded
real output · nika 0.107.0 · nika check hello.nika.yaml · re-captured at every release
- 04 · nika run
The same audit runs first, then the work
A run is not a second, looser path: the audit runs again inside it. Then the real seat answers, the ceiling is enforced while it does, and a trace lands on disk.
The run hands back the trace path and its hash chain unasked. Evidence is the default, not a flag.
nika runnika run hello.nika.yaml 🦋 nika · hello · 1 task permits ✓ declared boundary · default-denystill running · greet · 10s · ollama/qwen3.5:4b ✔ greet infer · ollama/qwen3.5:4b 14.0s ── 1/1 done · ≥ $0.00 (1 unpriced) · elapsed 14.0s ───────────── said "Bonjour !" trace: .nika/traces/2026-08-01T23-15-06Z-de62.ndjson · 5 events · chain 0f8618ad1d3f…
real output · nika 0.107.0 · nika run hello.nika.yaml · re-captured at every release
- 05 · nika trace
The run explains itself, afterwards
The flight recorder. Show prints the final card, outputs browses what each task returned, peek opens one whole, flow draws which output fed which task, and replay re-renders a run without ever re-executing it.
Replay re-renders, it never re-executes. What you read afterwards is what happened, not a fresh guess at it.
nika tracenika trace shownika trace: reading .nika/traces/2026-08-01T23-15-06Z-de62.ndjson (the workspace latest) ╭─ nika ✓ hello ───────────────────────────────────────────╮ │ ◆ 1 task · 1 wave · 0 retries │ │ 14.0s · 163 tok · ≥ $0.00 (1 unpriced) · ollama/qwen3… │ │ said "Bonjour !" │ ╰──────────────────────────────────────────────────────────╯
real output · nika 0.107.0 · nika trace show · re-captured at every release
underneath
The four subsystems
- the routerYou describe the job. It finds the file.Plain words in, a real workflow out · ranked against the 49 workflows compiled into the binary, with published constants and an honest refusal. No model, no network.
- the flowTwo doors, one graph.How tasks link: with binds a value, after orders an effect. The engine reads those bindings and builds the run graph. Nothing else creates an edge.
- the boundaryThe blast radius, declared.What a run may touch before it touches it: the permit families, the secret sources, and the floor that holds even when nothing is written down.
- the proofVerifiable without trusting us.The run graph, the receipt, the hash-chained journal. Everything a third party needs to check what happened, without taking our word for any of it.