Skip to content
Back to search

nika

Intent as Code | the workflow language for AI. One file, 4 verbs, one Rust binary. Local-first, any model, AGPL-3.0. 🦋

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/supernovae-st/nika with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/supernovae-st/nika'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/supernovae-st--nika/badge.svg)](/listings/supernovae-st--nika)

HTML

<a href="/listings/supernovae-st--nika"><img src="/api/listings/supernovae-st--nika/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 22 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "nika",
  4. "description": "Nika · the workflow language for AI. Author AI workflows as checkable .nika files.",
  5. "owner": {
  6. "name": "SuperNovae Studio",
  7. "email": "nika@supernovae.studio"
  8. },
  9. "plugins": [
  10. {
  11. "name": "nika",
  12. "description": "Author AI workflows as checkable .nika files. Bundles the nika-authoring skill, the nika-author subagent, the language rule, three commands, a check-on-edit hook and the read-only Nika MCP oracle (9 tools). Requires the nika binary: brew install supernovae-st/tap/nika",
  13. "version": "0.3.0",
  14. "author": {
  15. "name": "SuperNovae Studio",
  16. "url": "https://nika.sh"
  17. },
  18. "source": "./.agents/plugins/nika",
  19. "category": "development"
  20. }
  21. ]
  22. }
README.md · README · 635 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <a href="https://nika.sh">
  3. <picture>
  4. <source media="(prefers-color-scheme: dark)" srcset="https://nika.sh/brand/nika-logo-dark.svg">
  5. <img src="https://nika.sh/brand/nika-logo-light.svg" alt="Nika" width="220">
  6. </picture>
  7. </a>
  8. </p>
  9. <h1 align="center">Say it once.<br>Keep it as a file.</h1>
  10. <p align="center">
  11. <b>Checked before it runs. Run with the model you choose. Proven afterwards.</b><br>
  12. Nika turns the AI work you repeat into a readable workflow that stays yours. Fully open source.
  13. </p>
  14. <p align="center">
  15. <a href="https://github.com/supernovae-st/nika/releases/latest"><img src="https://img.shields.io/github/v/release/supernovae-st/nika?label=release" alt="Latest release"></a>
  16. <a href="https://github.com/supernovae-st/nika/actions/workflows/diamond-ci.yml"><img src="https://github.com/supernovae-st/nika/actions/workflows/diamond-ci.yml/badge.svg?branch=main" alt="CI status"></a>
  17. <a href="https://www.npmjs.com/package/@supernovae-st/nika"><img src="https://img.shields.io/npm/v/@supernovae-st/nika?label=npm" alt="npm package"></a>
  18. <a href="https://docs.nika.sh"><img src="https://img.shields.io/badge/docs-docs.nika.sh-8b8cf8.svg" alt="Documentation"></a>
  19. <a href="https://github.com/supernovae-st/nika-spec"><img src="https://img.shields.io/badge/spec-open-8b8cf8.svg" alt="Open specification"></a>
  20. </p>
  21. <p align="center">
  22. <a href="https://scorecard.dev/viewer/?uri=github.com/supernovae-st/nika"><img src="https://api.scorecard.dev/projects/github.com/supernovae-st/nika/badge" alt="OpenSSF Scorecard"></a>
  23. <a href="https://github.com/supernovae-st/nika/actions/workflows/codeql.yml"><img src="https://github.com/supernovae-st/nika/actions/workflows/codeql.yml/badge.svg?branch=main" alt="CodeQL"></a>
  24. <a href="https://github.com/supernovae-st/nika/releases/latest"><img src="https://slsa.dev/images/gh-badge-level3.svg" alt="SLSA 3 provenance on every release"></a>
  25. <a href="https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/supernovae-st/nika"><img src="https://archive.softwareheritage.org/badge/origin/https://github.com/supernovae-st/nika/" alt="Archived by Software Heritage"></a>
  26. <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg" alt="AGPL-3.0-or-later"></a>
  27. </p>
  28. <p align="center">
  29. <a href="media/gifs/first-session.optimized.gif">
  30. <img src="media/gifs/first-session.optimized.gif" alt="Nika's Session in four moments: a sentence typed in plain words, a checked workflow file saved only after yes, one run under a $0.25 ceiling that keeps the two paid rows, and /proof with its chain, permit checks and what it does not prove" width="960">
  31. </a>
  32. </p>
  33. <p align="center"><sub>
  34. “Read ./data/orders.csv, keep only the rows whose status is paid, and write them to ./out/paid.csv.”<br>
  35. One sentence becomes a checked file; <code>yes</code> saves it, <code>run it</code> keeps the two paid rows, and
  36. <code>/proof</code> shows what the run recorded. The real Session of nika 0.123.0, restyled; no AI model is involved.
  37. </sub></p>
  38. ## What is Nika?
  39. Nika turns repeatable AI work into a small file you keep. Say what you
  40. want done, like *"every Monday, pull the action items out of my meeting
  41. notes"*, and Nika writes it as a readable `.nika` workflow. Before
  42. anything runs, its check shows what the workflow will do, which models
  43. and tools it uses, what it is allowed to touch and what it can cost,
  44. without calling a model. A workflow that could read your private data,
  45. take in untrusted content and send data out is refused until it asks a
  46. person first. You run it when you decide, with the model you choose, on
  47. your machine or through a provider's API, and every run leaves a
  48. tamper-evident record you can verify. One Rust binary with a terminal
  49. Session and a command line, plus a TypeScript SDK for your applications;
  50. local-first and fully open source (AGPL-3.0).
  51. | 1 · Say it | 2 · Check it | 3 · Run it | 4 · Prove it |
  52. |:---:|:---:|:---:|:---:|
  53. | Describe the job; Nika writes a `.nika` file (or `nika compile` from a skeleton) | `nika check` audits it before any model is called | `nika run` with the model you choose | `nika trace verify` checks the run's record |
  54. <p align="center">
  55. <a href="#see-it-in-four-steps"><b>See it</b></a> ·
  56. <a href="#you-stay-in-control"><b>Control</b></a> ·
  57. <a href="#it-refuses-the-lethal-trifecta-before-a-token-is-spent"><b>Trifecta</b></a> ·
  58. <a href="#try-it-in-two-minutes"><b>Try it</b></a> ·
  59. <a href="#what-you-can-hand-to-nika"><b>Examples</b></a> ·
  60. <a href="#why-a-file-and-not-a-chat"><b>Why a file</b></a> ·
  61. <a href="#works-where-you-already-work"><b>Where it works</b></a> ·
  62. <a href="#know-the-limits"><b>Limits</b></a> ·
  63. <a href="https://docs.nika.sh"><b>Docs</b></a>
  64. </p>
  65. ## See it in four steps
  66. ### 1 · Say it
  67. Describe the job in plain words. Nika writes it as a `.nika` file, shows
  68. you what it will do and what it can touch, and saves it only when you say
  69. `yes`. Nothing runs until you ask. The clip at the top is that Session;
  70. this is its first answer, as the plain view prints it:
  71. ```text
  72. nika › Read ./data/orders.csv, keep only the rows whose status is paid, and write them to ./out/paid.csv.
  73. ✓ recorded 3 requirements
  74. Nika proposes `compiled-workflow.nika`:
  75. Does
  76. 1. read_source · reads a file
  77. …
  78. 8. write_output · writes a file
  79. Runs
  80. when you ask (« run it ») · no schedule was asked
  81. Can touch
  82. external effects · none
  83. human approval at run · none
  84. Changes
  85. + `compiled-workflow.nika` · 97 lines · new
  86. Needs
  87. nothing more from you
  88. Nothing has run yet · `yes` saves these exact bytes and checks them · running is its own line (« run it »)
  89. ```
  90. ### 2 · Check it
  91. Before anything runs, `nika check` reads the file and reports what it
  92. will do, what it may touch and what it can cost. It calls no model and
  93. spends nothing.
  94. <p align="center">
  95. <a href="media/gifs/static-check-fix.optimized.gif">
  96. <img src="media/gifs/static-check-fix.optimized.gif" alt="nika check finds two defects in a pull-request review workflow, the fix is applied, and the re-check comes back clean; nothing runs and no token is spent" width="860">
  97. </a>
  98. </p>
  99. <p align="center"><sub>Two mistakes caught before anything runs, the fix, and the clean re-check. Every line is captured from the real CLI.</sub></p>
  100. ### 3 · Run it
  101. You run it when you decide, with the model you choose. Here a local
  102. model, through Ollama, writes a meeting's action items as typed JSON.
  103. <p align="center">
  104. <a href="media/gifs/nika-hero.optimized.gif">
  105. <img src="media/gifs/nika-hero.optimized.gif" alt="nika check audits a meeting-actions workflow, then nika run executes it on a local model through Ollama and writes the meeting's action items to a typed JSON file" width="860">
  106. </a>
  107. </p>
  108. <p align="center"><sub>The audit first, then a real run on a local model (<code>ollama/llama3.2:3b</code>); the clip names the release each part was captured with. Nothing leaves the machine.</sub></p>
  109. ### 4 · Prove it
  110. Every run leaves a hash-chained record. `nika trace verify` reads it
  111. back, and when a single byte changes it names the line where the chain
  112. breaks.
  113. Runs are also signed once this machine has a run-signing key. Mint it once
  114. with `NIKA_KEYCHAIN=off nika key init`: the key lands in `~/.nika/keys/`
  115. (mode `0600`), where terminal runs, scripts, CI, the TypeScript SDK and
  116. `nika serve` all read it, and later runs report `SEALED` in
  117. `nika trace verify` and `/proof`. Without the variable, a terminal on a Linux
  118. desktop can keep the key in the Secret Service, which only terminal runs open
  119. (`nika key align` copies it to the files), and on a Mac whose keychain holds a
  120. key from Nika 0.122 or older, `nika key init` refuses: 0.123.0 and later never
  121. open the macOS keychain.
  122. <p align="center">
  123. <a href="media/gifs/trace-proof.optimized.gif">
  124. <img src="media/gifs/trace-proof.optimized.gif" alt="A run's trace drawn as five hash-linked blocks: nika trace verify reports the chain intact, then one byte of line 4 changes in a copy and verify stops at line 5: BROKEN, exit 2" width="860">
  125. </a>
  126. </p>
  127. <p align="center"><sub>The chain read back intact, then one changed byte refused at the next line. A <code>mock/echo</code> rehearsal captured from the real CLI; the scan is an illustration.</sub></p>
  128. ## You stay in control
  129. ### It refuses the lethal trifecta before a token is spent
  130. A workflow that can read your private data, take in content nobody vetted
  131. (a web page, a tool's answer, a command's output) and send data out is one
  132. injected instruction away from a leak. Simon Willison named this the
  133. [lethal trifecta](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/).
  134. `nika check` reads it from the permits, then follows the untrusted content
  135. from step to step, through a model's answer and into child workflows. When
  136. all three meet, it refuses the file until a person must say yes first.
  137. This workflow reads a note, fetches a public page, asks a local model for a
  138. digest and posts it to Slack:
  139. ```yaml
  140. nika: page-digest
  141. model: ollama/llama3.2:3b
  142. permits:
  143. fs: { read: ["./notes/today.md"] }
  144. net: { http: ["news.ycombinator.com", "hooks.slack.com"] }
  145. tools: ["nika:fetch", "nika:read", "nika:notify"]
  146. tasks:
  147. page:
  148. invoke:
  149. tool: "nika:fetch"
  150. args: { url: "https://news.ycombinator.com/" }
  151. notes:
  152. invoke:
  153. tool: "nika:read"
  154. args: { path: "./notes/today.md" }
  155. digest:
  156. with: { page: "${{ tasks.page.output }}", notes: "${{ tasks.notes.output }}" }
  157. infer:
  158. prompt: "Pick the three stories that matter for my notes.\nNotes: ${{ with.notes }}\nPage: ${{ with.page }}"
  159. max_tokens: 400
  160. post:
  161. with: { digest: "${{ tasks.digest.output }}" }
  162. invoke:
  163. tool: "nika:notify"
  164. args: { target: "https://hooks.slack.com/services/T000/B000/XXXX", message: "${{ with.digest }}" }
  165. ```
  166. The page never reaches Slack directly, only through the model's digest. The
  167. check follows it anyway and refuses the file with exit code 2:
  168. ```text
  169. nika check · page-digest.nika
  170. ✔ PLAN 3 waves · 4 tasks · max parallelism 2
  171. …
  172. ✖ TRIFECTA [NIKA-SEC-009] lethal trifecta complete · human gate required — untrusted content from `page` reaches egress task `post` while private read + untrusted ingress + external egress are all permitted …
  173. ```
  174. Drop any one of the three and there is nothing to refuse. To keep all three,
  175. put a question in front of them: a `nika:prompt` with no default, whose
  176. answer the fetch, the read and the post each require.
  177. ```yaml
  178. approve:
  179. invoke:
  180. tool: "nika:prompt"
  181. args: { message: "Read my notes, fetch Hacker News and post a digest to Slack?" }
  182. page:
  183. with: { go: "${{ tasks.approve.output }}" }
  184. when: ${{ with.go == true }}
  185. invoke:
  186. tool: "nika:fetch"
  187. args: { url: "https://news.ycombinator.com/" }
  188. ```
  189. With `nika:prompt` added to `permits.tools`, and the same `go` binding and
  190. `when:` line on `notes` and `post`, the check passes with exit code 0:
  191. ```text
  192. ✔ TRIFECTA no lethal trifecta over the declared permits: without a human gate
  193. layers · valid ✔ · access ready ✔ · capacity fit ✔ · run ready ✔
  194. ```
  195. A gate that only looks like one is refused too: a prompt with a `default:`
  196. answers itself and guards nothing (`NIKA-SEC-009` stays), and a step that
  197. still runs after a "no" fails `NIKA-SEC-014`. At a terminal the run asks; in
  198. CI it pauses with exit 4, as [shown below](#it-asks-before-it-acts). Every
  199. verdict here was captured from nika 0.124.0.
  200. [NIKA-SEC-009](https://nika.sh/language/errors/NIKA-SEC-009) explains the
  201. rule; Meta's [Agents Rule of Two](https://ai.meta.com/blog/practical-ai-agent-security/)
  202. states the same principle for agents.
  203. ### It tells you the cost before the first token
  204. `nika check` prices a workflow from its model's catalog price and the
  205. output limit each step declares. Set a budget below that ceiling and the
  206. run refuses to start: no model is called and nothing is spent.
  207. <p align="center">
  208. <a href="media/gifs/cost-ceiling.optimized.gif">
  209. <img src="media/gifs/cost-ceiling.optimized.gif" alt="nika check caps a Claude Sonnet workflow at ≤ $0.0614 once max_tokens is declared, and nika run with a $0.05 budget refuses to start: the ceiling past the budget line, a REFUSED TO START stamp, $0 spent" width="860">
  210. </a>
  211. </p>
  212. <p align="center"><sub>Unbounded until one line declares <code>max_tokens</code>, then a hard ceiling of $0.0614; a $0.05 budget refuses the run (exit 2). Prices are catalog estimates, not invoices; no model was called.</sub></p>
  213. ### It asks before it acts
  214. A step can wait for a person. At your terminal it asks; in CI, where
  215. nobody can answer, the run pauses safely with exit 4 and prints the one
  216. line that resumes it.
  217. <p align="center">
  218. <a href="media/gifs/approval-gate.optimized.gif">
  219. <img src="media/gifs/approval-gate.optimized.gif" alt="A workflow of build, a human gate drawn as a door, then ship: at a terminal Nika asks Ship this build to production? [y/N] and y opens the door; in CI the run pauses with exit 4 and prints a line that, pasted and run, reuses the build and ships" width="860">
  220. </a>
  221. </p>
  222. <p align="center"><sub>Nothing ships without a yes: asked at a terminal, paused in CI, resumed by the printed line with the finished build reused. Every terminal line is captured from the real CLI; the door is an illustration.</sub></p>
  223. ## Try it in two minutes
  224. ### 1 · Install
  225. ```sh
  226. curl -LsSf https://nika.sh/install.sh | sh
  227. ```
  228. <details>
  229. <summary>Homebrew, npm, a container, a release archive, Nix or Windows</summary>
  230. - **Homebrew:** `brew install supernovae-st/tap/nika`
  231. - **npm**, the binary plus the TypeScript SDK:
  232. `npm install @supernovae-st/nika` (the `nika` command lands in
  233. `node_modules/.bin`). The package bundles the engine of its own version:
  234. check `nika --version`.
  235. - **A container** (Linux, amd64 and arm64), built from the same release
  236. binaries: `docker run --rm ghcr.io/supernovae-st/nika:0.124.4 --version`.
  237. Mount a project to check or run its files, for example
  238. `docker run --rm -v "$PWD:/work" -w /work ghcr.io/supernovae-st/nika:0.124.4 check hello.nika`.
  239. - **A release archive:** download one from the
  240. [latest release](https://github.com/supernovae-st/nika/releases/latest).
  241. Every release ships a checksum manifest, a GitHub attestation and SLSA
  242. provenance; [RELEASING.md](RELEASING.md#what-a-user-can-prove) gives the
  243. three verification commands, for example
  244. `gh attestation verify nika-macos-arm64-0.124.4.tar.gz --repo supernovae-st/nika`.
  245. - **Nix:** `nix profile install github:supernovae-st/nika/v0.124.4` builds
  246. the release from the repository's flake. Without the tag, the flake builds
  247. the default branch, which can be ahead of the latest release.
  248. - **Windows:** use WSL2 and the Linux binary. Native Windows binaries are
  249. not shipped.
  250. </details>
  251. ### 2 · Say what you want
  252. This first job needs no AI account: Nika's deterministic compiler settles
  253. it without calling a model. Make a folder with a small spreadsheet and
  254. open the Session:
  255. ```sh
  256. mkdir -p orders-demo/data && cd orders-demo
  257. cat > data/orders.csv <<'EOF'
  258. order_id,customer,status,amount
  259. 1001,Juniper Books,paid,18.00
  260. 1002,Kestrel Cafe,pending,9.50
  261. 1003,Linden Studio,paid,13.50
  262. 1004,Moss Supply,refunded,6.00
  263. EOF
  264. nika
  265. ```
  266. At the prompt, type:
  267. ```text
  268. Read ./data/orders.csv, keep only the rows whose status is paid, and write them to ./out/paid.csv.
  269. ```
  270. Nika proposes a `.nika` file and shows what it will do, what it can touch
  271. and the result of its check. **Nothing has run yet.** Type `yes` to save
  272. the file, then `run it`. `out/paid.csv` gets the header and the two paid
  273. rows, and `/proof` shows what the run's record proves, and what it does
  274. not.
  275. > [!TIP]
  276. > Nika works only inside the folder you start it in. `/show` prints the
  277. > proposal's exact bytes, `/meaning` maps your request clause by clause,
  278. > and `no` discards it. `Ctrl+T` switches the view to full screen and back,
  279. > and `nika --plain` gives the same Session as plain lines. The
  280. > [Session guide](docs/usage/conversational-session.md) covers questions,
  281. > changes, spending ceilings and `/restore`.
  282. >
  283. > In a Git repository, the Session leaves `.gitignore` alone: before you
  284. > commit, add `.nika/traces/` (run records can hold file contents and model
  285. > outputs) and the Session's own `.nika/*.ndjson` and
  286. > `.nika/session-state.json`. After a run, the Session reminds you when
  287. > traces are not ignored.
  288. ### 3 · Add a model
  289. Most open-ended requests need a model to write the workflow, and
  290. workflows such as summaries call a model each time they run. Nika reads
  291. provider keys from your environment, so keep yours in your shell startup
  292. file. For DeepSeek:
  293. ```sh
  294. # in ~/.zshrc or ~/.bashrc, then open a new terminal
  295. export DEEPSEEK_API_KEY='your-key'
  296. ```
  297. The first request that needs a model shows a numbered choice: answer
  298. `2 deepseek/deepseek-flash`. Nika keeps the choice for later Sessions, and
  299. `/intelligence` changes it. Other API providers and local engines
  300. (Ollama, llama.cpp, LM Studio, vLLM) work too: `nika catalog` lists them.
  301. Your provider meters and bills these calls; Nika's cost figures are
  302. catalog estimates, not invoices.
  303. ### 4 · Use the file directly
  304. A workflow is an ordinary file. The command line compiles, checks, runs
  305. and verifies it. This offline lesson needs no provider:
  306. ```sh
  307. nika compile hello hello.nika
  308. nika check hello.nika
  309. nika run hello.nika
  310. nika trace verify
  311. ```
  312. ▶ [Watch these four commands run](media/gifs/full-loop.optimized.gif), exactly as captured from the CLI.
  313. `hello` always uses `mock/echo`, a stand-in model that echoes the prompt,
  314. even when provider keys are present. It proves that the workflow runs, not
  315. that a model answered. Each run records its trace under `.nika/traces/`,
  316. and creating the file adds that directory to `.gitignore`.
  317. `nika trace verify` checks the latest trace's integrity, not the truth of
  318. an AI answer.
  319. ## What you can hand to Nika
  320. | You say | Nika keeps | Watch |
  321. |---|---|---|
  322. | *"Read `./data/orders.csv`, keep only the rows whose status is paid, and write them to `./out/paid.csv`."* | A workflow that reads one file and writes one file. No AI model is involved. | [▶ The Session](media/gifs/first-session.optimized.gif) |
  323. | *"Pull the action items out of my meeting notes."* | A workflow that asks a local model and writes the items as typed JSON. | [▶ A local run](media/gifs/nika-hero.optimized.gif) |
  324. | *"Every Friday, turn `CHANGELOG.md` into release notes."* | A workflow your coding agent writes with the Nika plugin; the check catches its mistake before anything runs. | [▶ With your agent](media/gifs/agent-plugin.optimized.gif) |
  325. | *"Rate the risk of each pull request."* | A workflow the Nika GitHub Action checks whenever a pull request changes it: one comment carries the verdict. | [▶ In your pull requests](media/gifs/pr-check-comment.optimized.gif) |
  326. ## Why a file, and not a chat?
  327. A chat answer is gone when the conversation ends, and the next one can
  328. differ. A `.nika` file stays: you read it, check it, run it again and
  329. review its changes like any other file in your project.
  330. - **Say it once.** The request you would retype in a chat every week is
  331. kept as a file that runs again.
  332. ▶ [Watch a weekly request become a file](media/gifs/chat-to-workflow.optimized.gif)
  333. - **Read it before it runs.** Every workflow has the same shape: nine
  334. sections and four kinds of step, in a file you can open and review.
  335. ▶ [Watch one taken apart](media/gifs/spec-anatomy.optimized.gif)
  336. - **It touches only what it declares.** The file lists what it may read,
  337. write and reach. The check refuses the step that reaches past it.
  338. ▶ [Watch the check catch an escape](media/gifs/permits-audit.optimized.gif)
  339. - **Failures are planned for.** A step can name its fallback: the run
  340. finishes, the output says it is stale, and the record keeps the failure.
  341. ▶ [Watch a missing feed absorbed](media/gifs/on-error-recover.optimized.gif)
  342. - **Parallel where it can be.** Steps that do not depend on each other
  343. run side by side, in waves the check plans before the run.
  344. ▶ [Watch a workflow run in waves](media/gifs/dag-execution.optimized.gif)
  345. Every clip on this page shows real files and terminal lines captured from
  346. the binary, names the release it was captured with, and says what it
  347. illustrates. The [media index](media/README.md#feature-clips) lists them
  348. all and how they are made.
  349. ## Works where you already work
  350. Nika comes to the tools you already use. Your coding agent can write the
  351. file for you, and the check keeps it honest:
  352. <p align="center">
  353. <a href="media/gifs/agent-plugin.optimized.gif">
  354. <img src="media/gifs/agent-plugin.optimized.gif" alt="A coding agent writes release-notes.nika from one request with the plugin's nika-authoring skill; nika check refuses nika:read_file (NIKA-BUILTIN-001), the agent repairs it to nika:read, the re-check says run ready, and a mock/echo rehearsal writes release-notes.md" width="860">
  355. </a>
  356. </p>
  357. <p align="center"><sub>Your agent writes it, Nika checks it, you keep it. The agent session is an illustration; the checks and the rehearsal run are captured from the real CLI.</sub></p>
  358. | Where | What you get | Watch |
  359. |---|---|---|
  360. | **Your coding agent** · [nika-plugins](https://github.com/supernovae-st/nika-plugins) | Claude Code, Codex, Cursor and others learn to write a workflow, check it and repair what the check finds. | ▶ [above](media/gifs/agent-plugin.optimized.gif) |
  361. | **Your editor** · `nika lsp` | The language server inside the binary: the check's findings as you type, in any LSP client. The VS Code extension ([nika-vscode](https://github.com/supernovae-st/nika-vscode)) stays at 0.120 and is not qualified with 0.124; point its `nika.server.path` at your 0.124 binary ([known limits](https://docs.nika.sh/changelog/known-limits#the-vs-code-extension-stays-at-0-120)). | ▶ [The audit, as you type](media/gifs/editor-diagnostics.optimized.gif) |
  362. | **Your pull requests** · [nika-action](https://github.com/supernovae-st/nika-action) | One comment with the verdict, before anyone spends a token. | ▶ [Every pull request gets a verdict](media/gifs/pr-check-comment.optimized.gif) |
  363. | **Your app** · [nika-client](https://github.com/supernovae-st/nika-client) | Run a workflow from TypeScript ([the package](https://www.npmjs.com/package/@supernovae-st/nika)), get a typed result and verify its receipt, with the engine the package bundles or against your `nika serve`. | ▶ [Run it from your app, prove what ran](media/gifs/typescript-client.optimized.gif) · ▶ [One client, two doors](media/gifs/sdk-doors.optimized.gif) |
  364. ### From your application
  365. `npm install @supernovae-st/nika` brings the TypeScript SDK and the engine of
  366. its own version (Node.js 22 or newer, on macOS or Linux with glibc). Run
  367. `NIKA_KEYCHAIN=off ./node_modules/.bin/nika key init` once, so the engine your
  368. app starts can seal each run's record. Then, beside a `hello.nika`, this is the
  369. package's quick start:
  370. ```ts
  371. import { Nika, isNikaRunSucceeded } from '@supernovae-st/nika';
  372. const nika = new Nika({ cwd: process.cwd() });
  373. // The engine checks the file first: a workflow it refuses throws here and never starts.
  374. const run = await nika.run<{ greeting: string }>('hello.nika', { maxCostUsd: 0 });
  375. const result = await run.result();
  376. // A failed run is data you read, not an exception.
  377. if (!isNikaRunSucceeded(result) || !result.receipt) {
  378. console.error(result.status, result.error?.code, result.error?.message);
  379. process.exit(1);
  380. }
  381. console.log(result.outputs?.greeting);
  382. // Ask the engine to verify the run's tamper-evident record.
  383. const proof = await nika.traceVerify(result.receipt);
  384. console.log(proof.verified ? 'receipt verified' : `not verified: ${proof.reason}`);
  385. ```
  386. Save it as `demo.mts` (top-level `await` needs a module) and run
  387. `node demo.mts`: Node.js 22.18 or newer runs the TypeScript as is. The
  388. [SDK quick start](https://docs.nika.sh/sdk/start/quickstart) gives the
  389. `hello.nika` this program runs.
  390. To reach a `nika serve` instead of the bundled engine, keep the methods and
  391. change the options of two lines:
  392. ```ts
  393. const nika = new Nika({ url, token, allowInsecureHttp: true });
  394. const run = await nika.run<{ greeting: string }>('hello.nika', { idempotencyKey });
  395. ```
  396. `url` and `token` name the server and its bearer token. Plain `http://` is
  397. accepted only to a loopback host, and only with `allowInsecureHttp: true`.
  398. Over HTTP, `run()` needs an `idempotencyKey` you own (a retry with the same
  399. key returns the same job) and refuses `maxCostUsd`: the server applies its
  400. own per-run ceiling, USD 1 by default. `hello.nika` is then a served name,
  401. the workflow's path from the server's project root.
  402. [nika-client](https://github.com/supernovae-st/nika-client) documents the
  403. whole API.
  404. <p align="center">
  405. <a href="media/gifs/sdk-doors.optimized.gif">
  406. <img src="media/gifs/sdk-doors.optimized.gif" alt="Animated diagram of the TypeScript SDK: in the quick start, new Nika() starts the engine bundled with @supernovae-st/nika 0.124.0 as a child process; for nika serve, line 3 takes url, token and allowInsecureHttp, and line 6 takes an idempotencyKey in place of maxCostUsd. A refused list-files.nika gets NIKA-SEC-004 and run() throws, hello.nika runs, its events stream back to the app, its six hash-chained journal lines end in run_sealed, and traceVerify() answers verified locally and sealed from the server" width="860">
  407. </a>
  408. </p>
  409. <p align="center"><sub>Your app asks, the engine decides, the receipt proves it. The code is the quick start above, which the capture ran, with lines 3 and 6 also shown as its server driver ran them against <code>nika serve</code>. Every event, verdict, hash and version on screen was captured from <code>@supernovae-st/nika</code> 0.124.0, the engine it bundles and <code>nika serve</code> in a <code>mock/echo</code> rehearsal; the cards, lanes, packets and pacing are illustration.</sub></p>
  410. ## Know the limits
  411. - **0.124 is the current release line.** Work stays focused on
  412. maintenance, security and the media capabilities workflows need; native
  413. video is planned for 0.125. The 0.123.x line is the previous one, and
  414. there is no hosted service. The known limits are listed in plain words,
  415. each with a way around it:
  416. [Known limits in 0.124](https://docs.nika.sh/changelog/known-limits).
  417. - **Some requests cannot be expressed.** Nika then says what stopped it
  418. and writes nothing.
  419. - **A clean check is not a true answer.** It describes a file's structure
  420. and boundary; it does not prove that model output is right.
  421. - **The trifecta check judges permits and flow, not words.** It does not
  422. read a page or a model's answer for injected instructions, and a person
  423. who answers yes approves what follows. On a harness seat, what `permits:`
  424. covers is listed per seat ([harness agents](docs/usage/harness-agents.md)).
  425. - **This README describes the released 0.124.4.** Compare `nika --version`
  426. with the [changelog](CHANGELOG.md), which lists what each release
  427. changed. Until the next release, each change merged after 0.124.4 is
  428. described in its own file under [`changelog.d/`](changelog.d/README.md),
  429. and the release folds those files into the changelog.
  430. <details>
  431. <summary><b>The four building blocks</b></summary>
  432. | Verb | What it does |
  433. |---|---|
  434. | `infer` | Ask a model to produce an answer |
  435. | `invoke` | Call a native tool, MCP tool or another workflow |
  436. | `exec` | Run a command |
  437. | `agent` | Let a model use allowed tools for a bounded number of turns |
  438. A workflow uses only the verbs its job needs. The orders workflow at the
  439. top uses `invoke` alone: eight steps over five builtin tools (`nika:read`,
  440. `nika:convert`, `nika:jq`, `nika:assert` and `nika:write`), with no model
  441. and no shell.
  442. </details>
  443. <details>
  444. <summary><b>Compile from the command line</b></summary>
  445. `nika compile --list` lists exact skeletons. Preview one with
  446. `nika compile <slug> --json`, then answer its stable questions with repeatable
  447. `--answer KEY=JSON_LITERAL`. An incomplete result includes its candidate and
  448. questions; it does not write a file. Only a Ready candidate plus an explicit
  449. destination writes. Existing destinations require `--force`.
  450. For an accepted source, a conservative constant edit uses the same core:
  451. ```sh
  452. nika compile --base workflow.nika --change 'Set const.topic to "new topic"' --json
  453. ```
  454. Add `--output edited.nika` to materialize a Ready edit. The base source
  455. remains explicit. Unresolved intent stays incomplete without a substitute
  456. workflow. `--authoring-model` seats a model to interpret free intent and
  457. revise text. No request count is imposed by default: creation ends on a
  458. result, a failure, no progress or a cancellation. `--authoring-max-calls N`
  459. sets an explicit ceiling (an ACP harness counts its invocations; its own
  460. requests are unknown), and typed repairs or samples that cannot fit under it
  461. are refused before any request. `--authoring-strategy` selects `escalate`,
  462. `only`, `sketch` or `off`. The compiler checks the proposed source and its
  463. fidelity to the request. This is not a guarantee of arbitrary-language
  464. understanding, and Graph editing is not implemented by this CLI.
  465. Compile's Check preview judges source only. `nika check` and `nika run` judge
  466. the actual environment separately. For a real model, choose the provider and
  467. access explicitly; the [model setup documentation](https://docs.nika.sh)
  468. explains local, API and supported harness choices. On a harness seat an
  469. `agent:` task runs the application's own tools:
  470. [what `permits:` covers there](docs/usage/harness-agents.md), and what it
  471. does not, is listed per seat and printed by `nika check`.
  472. </details>
  473. <details>
  474. <summary><b>Before sharing a workflow or a run</b></summary>
  475. Share the workflow, not credentials or private data. Review file paths and
  476. tool access. Keep secrets out of source control.
  477. Run journals can contain the data and outputs the workflow processed.
  478. The `.nika/traces/` directory is a data-at-rest surface: it inherits the sensitivity
  479. of everything the run read. Exclude it from Git unless you deliberately intend
  480. to publish those records, and treat them with the same care as their source
  481. data.
  482. After a run, `nika trace verify` verifies the latest journal. Compare its
  483. head with the one printed by the run. This checks the record, not the AI's
  484. judgement.
  485. </details>
  486. <!-- city:map -->
  487. ## 🦋 The Nika family
  488. | | Repository | What it gives you |
  489. |---|---|---|
  490. | 🦋 | **[nika](https://github.com/supernovae-st/nika)** | **The engine and CLI: write, check, run and verify AI workflows** |
  491. | 📖 | [nika-docs](https://github.com/supernovae-st/nika-docs) | The documentation, live at [docs.nika.sh](https://docs.nika.sh) |
  492. | 📜 | [nika-spec](https://github.com/supernovae-st/nika-spec) | The language specification and the suite that proves an engine follows it |
  493. | 🧩 | [nika-vscode](https://github.com/supernovae-st/nika-vscode) | The editor extension, frozen at 0.120 and not qualified with 0.124: use `nika lsp` and the JSON Schema |
  494. | 🟦 | [nika-client](https://github.com/supernovae-st/nika-client) | Run and verify workflows from TypeScript |
  495. | ✅ | [nika-action](https://github.com/supernovae-st/nika-action) | A GitHub Action that posts a `nika check` verdict on your pull requests |
  496. | 🚀 | [nika-actions-starter](https://github.com/supernovae-st/nika-actions-starter) | A ready template: workflows, editor setup and CI from the first push |
  497. | 📦 | [nika-registry](https://github.com/supernovae-st/nika-registry) | Shareable workflows, pinned and re-verified |
  498. | 🤖 | [nika-plugins](https://github.com/supernovae-st/nika-plugins) | Teaches your coding agent (Claude Code, Codex, Cursor…) to write Nika |
  499. | 🍺 | [homebrew-tap](https://github.com/supernovae-st/homebrew-tap) | `brew install supernovae-st/tap/nika` |
  500. | 🐙 | [gh-nika](https://github.com/supernovae-st/gh-nika) | The Nika CLI as a GitHub CLI extension |
  501. | 🏛️ | [nika-estate](https://github.com/supernovae-st/nika-estate) | Where each file in Nika's core repositories comes from, declared and re-checkable |
  502. <!-- /city:map -->
  503. This repository is the one executable: it parses, checks, runs and traces
  504. every workflow. The language is defined by the specification, and the other
  505. repositories drive this engine without adding to its authority.
  506. ## Go further
  507. [Session guide](docs/usage/conversational-session.md) ·
  508. [Examples](examples/README.md) ·
  509. [Documentation](https://docs.nika.sh) ·
  510. [TypeScript SDK](https://www.npmjs.com/package/@supernovae-st/nika) ·
  511. [Editor extension (0.120, not qualified with 0.124)](https://marketplace.visualstudio.com/items?itemName=supernovae.nika) ·
  512. [Open specification](https://github.com/supernovae-st/nika-spec) ·
  513. [Registry](https://github.com/supernovae-st/nika-registry) ·
  514. [Planning archive](https://github.com/orgs/supernovae-st/projects/3) ·
  515. [Website](https://nika.sh)
  516. Nika 0.124 is the current open-source release line, usable today and
  517. maintained. The engine is
  518. [AGPL-3.0-or-later](LICENSE); the specification and the TypeScript SDK are
  519. Apache-2.0.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.