{"id":45476640,"url":"https://github.com/supernovae-st/nika","last_synced_at":"2026-08-02T14:00:42.836Z","repository":{"id":334993316,"uuid":"1126625946","full_name":"supernovae-st/nika","owner":"supernovae-st","description":"Intent as Code | the workflow language for AI. One file, 4 verbs, one Rust binary. Local-first, any model, AGPL-3.0. 🦋","archived":false,"fork":false,"pushed_at":"2026-07-27T09:59:45.000Z","size":55552,"stargazers_count":37,"open_issues_count":13,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-27T11:09:51.054Z","etag":null,"topics":["agents","ai","ai-agents","ai-workflows","automation","cli","dag","developer-tools","devops","llm","local-ai","mcp","ollama","rust","self-hosted","structured-output","workflow","workflow-automation","workflow-engine","yaml"],"latest_commit_sha":null,"homepage":"https://nika.sh","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/supernovae-st.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"custom":["https://supernovae.studio"]}},"created_at":"2026-01-02T09:32:06.000Z","updated_at":"2026-07-27T10:01:09.000Z","dependencies_parsed_at":null,"dependency_job_id":"ee8af2ff-e629-4616-9ec3-6a4a51bc1cba","html_url":"https://github.com/supernovae-st/nika","commit_stats":null,"previous_names":["supernovae-st/nika"],"tags_count":255,"template":false,"template_full_name":null,"purl":"pkg:github/supernovae-st/nika","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supernovae-st%2Fnika","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supernovae-st%2Fnika/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supernovae-st%2Fnika/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supernovae-st%2Fnika/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/supernovae-st","download_url":"https://codeload.github.com/supernovae-st/nika/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supernovae-st%2Fnika/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36196144,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-08-02T02:00:06.915Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","ai-agents","ai-workflows","automation","cli","dag","developer-tools","devops","llm","local-ai","mcp","ollama","rust","self-hosted","structured-output","workflow","workflow-automation","workflow-engine","yaml"],"created_at":"2026-02-22T15:29:36.088Z","updated_at":"2026-08-02T14:00:42.810Z","avatar_url":"https://github.com/supernovae-st.png","language":"Rust","funding_links":["https://supernovae.studio"],"categories":["Workflow","Applications","Agentic security","Libraries and Frameworks","Dev-Utilities","MCP Servers","Software","Command Line Tools","NLP","🌟 Community Skills","Multi-Agent Systems"],"sub_categories":["Tools","AI \u0026 LLM Testing","Usage","🔧 DevOps \u0026 Deployment","Orchestration Platforms"],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://nika.sh\"\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://nika.sh/brand/nika-logo-dark.svg\"\u003e\n      \u003cimg src=\"https://nika.sh/brand/nika-logo-light.svg\" alt=\"Nika\" width=\"220\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# Nika\n\n\u003e **Intent as Code.** The workflow language for AI: one file, 4 verbs,\n\u003e one binary.\n\n[![License](https://img.shields.io/badge/engine-AGPL--3.0--or--later-blue.svg)](LICENSE)\n[![Spec](https://img.shields.io/badge/spec-Apache--2.0-brightgreen.svg)](https://github.com/supernovae-st/nika-spec)\n[![Rust](https://img.shields.io/badge/built_in-Rust-orange.svg)](Cargo.toml)\n[![CI](https://github.com/supernovae-st/nika/actions/workflows/diamond-ci.yml/badge.svg?branch=main)](https://github.com/supernovae-st/nika/actions/workflows/diamond-ci.yml)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/supernovae-st/nika/badge)](https://scorecard.dev/viewer/?uri=github.com/supernovae-st/nika)\n[![Release](https://img.shields.io/github/v/release/supernovae-st/nika?label=release)](https://github.com/supernovae-st/nika/releases/latest)\n[![SWH](https://archive.softwareheritage.org/badge/origin/https://github.com/supernovae-st/nika/)](https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/supernovae-st/nika)\n\nUseful AI work shouldn't disappear into chats. **Nika turns repeatable AI\nwork into files you can run, review, diff and share.** If you do the same\nAI task twice, make it a workflow.\n\n**The pipeline is a file.** A graph of model calls, tools and processes:\na shape you declare, not glue you program. Nika audits that file **before\na token is spent** (cost ceiling, permissions, secret flows, types), runs\nit on whichever LLM you choose, local first, no cloud required, and leaves\nevery run a verifiable receipt. The language is an open\n[Apache-2.0 spec](https://github.com/supernovae-st/nika-spec); this repo is\nthe reference engine, a single Rust binary (AGPL-3.0). The way SQL pairs\nwith PostgreSQL, or the Dockerfile with Docker.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/gifs/dag-execution.optimized.gif\" alt=\"A workflow is a graph, not a prompt: the YAML on the left, its real execution graph on the right lighting up wave by wave. Seven tasks, six waves, all four verbs in one file\" width=\"900\" /\u003e\n\u003c/p\u003e\n\n## Does it run today?\n\nYes.\n\n```sh\nbrew install supernovae-st/tap/nika    # or: curl -LsSf https://nika.sh/install.sh | sh\nnika try 01-hello                                # zero setup: no key, no model server\nnika try 01-hello --model ollama/llama3.2:3b     # got Ollama? the same run, real + local\n# (first run loads the model into memory; later runs are much faster)\n```\n\n![nika check audits the workflow (plan, cost, secrets, types), then nika run executes it locally](media/nika-hero.gif)\n\nNika audits a workflow **before a single token is spent** (plan, cost\nceiling, secret flows, types, tool args), then runs it:\n\nEvery line says what it looked at. A rung that covers less than its\nname suggests narrows itself rather than borrowing your trust — `TYPES`\nnames the shapes it could not see, `PERMITS` names what defers to the\nrun, `COST` names the half of the bill it prices.\n\n```text\n$ nika check brief.nika.yaml\n ✔ PLAN     2 waves · 2 tasks · max parallelism 1\n      wave 1 fetch_notes (invoke · nika:read)\n      wave 2 brief (infer · ollama/llama3.2:3b)\n ✔ MODELS   1 model resolves in this binary\n ⚠  COST     bounded portion $0.0000 no total ceiling · 1 uncapped task · prompts, exec + mcp unpriced · prices 2026-07-28\n   brief  ollama/llama3.2:3b  UNBOUNDED — no catalog price (local/unknown model)\n ⚠  ENERGY   no total energy ceiling · 0 of 1 tasks measured · 1 uncapped · never 0 Wh (NEP-0018)\n ✔ SECRETS  no declared secret reaches an effect · model echo untracked\n ✔ TYPES    deep references fit the shapes tasks declare · builtin output has none\n ✔ TOOLS    every named nika: tool is canonical · globs + mcp: not checked\n ✔ ARGS     every builtin invoke arg key is declared + required args present\n ✔ SCHEMA   no known-unsatisfiable form in an authored schema: · $ref opaque\n ✔ GATES    no task proven dead · status literals in vocabulary\n ✔ WRITES   no two unordered tasks write the same static path · computed paths at run\n ✔ PERMITS  literal + const: args fit the boundary · computed + symlinks at run\n ✔ TRIFECTA no lethal trifecta over the declared permits: without a human gate\n ✔ JOURNEY  internal · 1 source · 0 destinations · 2 model endpoints · no secret reaches a cloud destination\n ⚠ audited · 2 tasks · 2 waves · permits declared · est unbounded · 1 uncapped task · 0 hints · risk unbounded\n\n$ nika run brief.nika.yaml\n  🦋 nika · daily-brief · 2 tasks\n  ✔  fetch_notes  invoke · nika:read\n  ✔  brief        infer · ollama/llama3.2:3b\n  ── 2/2 done · $0.000 · elapsed 16.2s ───────────────────────────\n```\n\n## The loop: check → fix → run → receipt\n\nAn agent (or you, at 2am) writes a workflow. `nika check` audits the file\nstatically and **names every fix**; the run streams live; the trace is a\nhash-chained receipt `nika trace verify` re-proves. The whole loop, captured\nagainst the real binary:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/gifs/full-loop.optimized.gif\" alt=\"nika check catches a typo'd task reference and a typo'd tool, each with a did-you-mean fix; the two renames applied; the audit passes clean; the run executes offline on mock/echo and prints its trace path and chain head; nika trace verify confirms the same head\" width=\"900\" /\u003e\n\u003c/p\u003e\n\nWhat the audit catches before a single token is spent. Each finding\ncarries its `NIKA-XXXX` code, the exact source span, and the fix:\n\n| The mistake | What `nika check` says |\n|---|---|\n| A reference to a task that doesn't exist | `NIKA-VAR-001`: unresolved reference `tasks.digets`, *did you mean `tasks.digest`?* |\n| Reading another task from a verb body | `NIKA-VAR-021`: `tasks.stats` outside the boundary — *hoist it into `with:` and read `${{ with.stats }}`* |\n| A typo'd tool | TOOLS: `nika:wrte` is not a canonical builtin, *did you mean `nika:write`?* |\n| A task reaching beyond its `permits:` boundary | PERMITS: the escape, with the machine-applicable widening line |\n| A secret flowing where it shouldn't | SECRETS: the information-flow escape, statically |\n| Unbounded spend | COST: a hard ceiling when priceable, an honest `UNBOUNDED` floor when not (never a fake `$0`) |\n| An output used where its shape can't fit | TYPES: every deep reference checked against the declared schema |\n\nAfter the run, the receipt: every run journals to `.nika/traces/` as an\nappend-only, hash-chained record. The run prints its chain head;\n`nika trace verify` recomputes it. Tamper-evident, local, zero services.\n\nThe capture above is honesty-gated like every asset here: its\n[fixtures + tape](scripts/media/) are committed, and\n`scripts/media/validate-media.sh` keeps the broken half failing `nika check`\nand the fixed half clean.\n\n## What a workflow looks like\n\n```yaml\n# review.nika.yaml: read a PR diff, judge its risk, comment only when it's high.\nnika: v1\nworkflow:\n  id: pr-risk-review\nmodel: ollama/qwen3.5:9b             # local by default. swap to any provider\n\ntasks:\n  diff:                               # exec: a read-only shell command\n    exec:\n      command: [\"git\", \"diff\", \"origin/main...HEAD\"]\n      capture: structured\n\n  assess:                             # infer: structured LLM judgment\n    with:                             # the binding IS the edge — no separate wiring\n      patch: ${{ tasks.diff.output.stdout }}\n    infer:\n      prompt: \"Risk-assess this diff (secrets, breaking changes, missing tests). Be terse.\\n${{ with.patch }}\"\n      max_tokens: 300\n      schema:\n        type: object\n        required: [risk]\n        properties:\n          risk: { type: string, enum: [low, medium, high] }\n\n  comment:                            # invoke: the only write, gated on the verdict\n    with:\n      risk: ${{ tasks.assess.output.risk }}\n      verdict: ${{ tasks.assess.output }}\n    when: ${{ with.risk == 'high' }}\n    invoke:\n      tool: \"mcp:github/pr-comment\"\n      args:\n        body: ${{ with.verdict }}\n```\n\n## Check before it runs\n\n`nika check` is a static audit. It catches broken references, missing\ndependencies, schema and permission problems **before any model is called**,\nand when something is off, it points at the exact fix:\n\n![nika check catches a boundary violation and a typo'd task reference, shows the hoist fix, then the same audit passes clean](media/gifs/static-check-fix.optimized.gif)\n\nThe two fixtures behind this capture live in\n[`scripts/media/fixtures/`](scripts/media/fixtures/), gated in both\ndirections by `scripts/media/validate-media.sh`: the broken one must keep\nfailing `nika check`, the fixed one must stay clean.\n\nThe same audit holds the workflow's **declared blast radius**. A `permits:`\nblock makes the file itself the security boundary: hosts, paths, programs,\ntools, all default-deny once declared. A task that reaches beyond it is\ncaught statically, with the machine-applicable fix, before anything runs:\n\n![A permits block declares GitHub-only network access; one task fetches another host; nika check flags the escape with the exact fix line; the boundary widens on purpose in review and the audit passes clean](media/gifs/permits-audit.optimized.gif)\n\nAnd failure handling is part of the file, not an ops runbook. When a task\ndies, `on_error: recover:` degrades to a declared fallback: the run\ncompletes, and the output says what it is:\n\n![The live source is missing so the task fails; on_error recover degrades to the cached snapshot; the run exits 0 and the published file says stale: true](media/gifs/on-error-recover.optimized.gif)\n\n## Images are workflow citizens\n\n`nika:image_generate` renders through the same discipline as everything\nelse: a declared `permits:` boundary gates every save, the run ledger\nmeters real spend, and provenance is structural, not a promise:\n\n![One workflow renders a real image and speaks a real line: permits gate the saves, the ledger shows $0.02 exact, the gallery frame carries the actual renders and a waveform drawn from the real MP3 bytes, and the manifest panel shows the provenance nobody else keeps](media/gifs/image-pipeline.gif)\n\n- **Local-first**: `provider: local` speaks the OpenAI-images wire any\n  self-hosted server exposes (LocalAI · Ollama · stable-diffusion.cpp ·\n  SGLang · vLLM-Omni). The base URL is engine config, never workflow data.\n  Clouds when you choose: `openai` · `gemini` · `xai`, and `mock` renders\n  real, decodable PNG files offline for CI.\n- **Provenance survives `cp`**: every saved PNG carries a `nika` tEXt\n  chunk (tool · engine · provider · model · prompt · seed), the practice\n  ComfyUI and InvokeAI standardized and no other workflow engine ships.\n  The sidecar manifest adds sha256, resolved request and timing.\n- **Honesty is enforced**: magic bytes beat declared MIME types, lossy\n  provider mappings warn loudly, a provider returning fewer images than\n  asked is a visible `count_shortfall:`, result URLs are **never**\n  fetched, and base64 never rides workflow outputs: assets, not blobs.\n- **Real spend in the ledger**: a render's exact cost (xAI bills in\n  ticks) lands on the task line and the run total, the same honest-spend\n  channel `infer:` uses.\n\n## Daily commands\n\n```sh\nnika welcome                         # the mirror · what Nika is + what it sees here · offline\nnika welcome --deep --json           # the whole workspace, audited, one JSON (agents start here)\nnika inspect flow.nika.yaml          # anatomy · tasks · waves · cost floor\nnika check flow.nika.yaml            # the audit · exit 0 clean · 2 findings\nnika explain flow.nika.yaml          # the story · waves · cost BEFORE a token · what it touches\nnika explain NIKA-VAR-001            # any code · cause · category · fix-form\nnika run flow.nika.yaml --var topic=rust   # launch inputs · repeatable\nnika test flow.nika.yaml --update    # pin the golden · then `nika test` = offline CI (simulated · effects refused)\nnika run flow.nika.yaml --task hero    # regenerate ONE task + its upstream cone\nnika run flow.nika.yaml --resume .nika/traces/\u003crun\u003e.ndjson   # skip journaled successes\nnika run flow.nika.yaml --resume \u003ctrace\u003e --answer approve=true  # re-arm a paused gate\nnika trace show .nika/traces/\u003crun\u003e.ndjson   # re-render any past run\nnika catalog                         # the embedded provider/model catalog · capabilities · env vars\nnika catalog --tools                 # the nika:* builtin catalog · what invoke reaches without MCP\nnika model pull Qwen/Qwen3-0.6B-GGUF # a GGUF + its tokenizer land in ~/.nika/models\nnika model serve --model Qwen/Qwen3-0.6B-GGUF  # your own loopback OpenAI endpoint · no cloud, no daemon\nnika doctor --ping                   # are the local servers actually listening?\n```\n\nEvery run writes its own journal to `.nika/traces/` (opt out per run with\n`--no-trace-file`, globally with `NIKA_NO_TRACE_FILE`); `--resume` and\n`nika trace` read it directly. A paused run exits `4` (a blocking\n`nika:prompt` journals its question); cache hits on resume are always\nvisible: nothing is skipped silently.\n\n\u003c!-- city:map --\u003e\n## The city · where this repo sits\n\n```\n📜 nika-spec ──── the civil code · the law tables, the corpus, the exam\n    │ sync-pack: byte-gated mirror        │ projectors: drift-gated\n    ▼                                     ▼\n⚙️ nika ───────── the engine + the catalog (the yellow pages)   ◀── you are here\n    │ the release train                  🖥️ nika.sh · 📖 nika-docs\n    ▼                                     the showroom · the manual\n📦 homebrew-tap · npm · Docker ── the docks\n🔌 nika-client · 🎨 nika-vscode · 🤖 nika-agents · ⚡ gh-nika ── the doors\n🏭 nika-action · 🧪 nika-actions-starter ── the CI district\n🏪 nika-registry ── the market · 🏛 nika-estate ── the land registry\n```\n\n**This building** · THE ENGINE · checks before it spends, runs inside declared permits, leaves a signed trace. Carries the catalog: providers, models, prices pinned with provenance.\n\n**Root** · ENGINE facts, AGPL-3.0 · the crates, the tests, the hygiene vectors. Language facts arrive pinned from nika-spec and are never retyped here · the two roots never mix.\n\n**Consumes** · the spec (corpus vendored at a pin, integrity-tested) · upstream pricing (pinned, provenance recorded).\n\n**Serves** · the docks (brew · npm · Docker) · every door (CLI · LSP · MCP · serve).\n\n**Truth lives** · engine numbers come from the binary, never from prose · `crates/nika-pack/pack/` is a byte-gated MIRROR of the spec — editing it is a lost gesture.\n\nAll the buildings: [nika-spec](https://github.com/supernovae-st/nika-spec) · [nika](https://github.com/supernovae-st/nika) · [nika.sh](https://github.com/supernovae-st/nika.sh) · [nika-docs](https://github.com/supernovae-st/nika-docs) · [nika-client](https://github.com/supernovae-st/nika-client) · [nika-vscode](https://github.com/supernovae-st/nika-vscode) · [nika-agents](https://github.com/supernovae-st/nika-agents) · [gh-nika](https://github.com/supernovae-st/gh-nika) · [homebrew-tap](https://github.com/supernovae-st/homebrew-tap) · [nika-action](https://github.com/supernovae-st/nika-action) · [nika-actions-starter](https://github.com/supernovae-st/nika-actions-starter) · [nika-registry](https://github.com/supernovae-st/nika-registry) · [nika-estate](https://github.com/supernovae-st/nika-estate)\n\nEvery fact has one home · everything else is a gated projection.\nThe living map: [nika.sh/map](https://nika.sh/map).\n\u003c!-- /city:map --\u003e\n\n## Pick a workflow\n\nThe binary embeds a versioned pack of runnable examples. Browse with\nbare `nika try`, take one with `nika new \u003cslug\u003e` (the file is the read), preview any\nof them with `--model ollama/llama3.2:3b` (or offline with `--model mock/echo`):\n\n| I want to… | Run | For |\n|---|---|---|\n| Review a PR before merging | `nika try pr-review-fanout` | developers |\n| Turn meeting notes into owned actions | `nika try meeting-actions` | everyone |\n| Digest a week of standups | `nika try standup-digest` | teams |\n| Draft release notes from commits | `nika try release-notes` | maintainers |\n| Triage a support inbox | `nika try support-triage` | support · ops |\n| Chase unpaid invoices politely | `nika try invoice-chaser` | founders |\n| Track competitors weekly | `nika try competitor-radar` | founders |\n| Screen resumes against a role | `nika try resume-screener` | hiring |\n| Build a Monday operating brief | `nika try ceo-monday-brief` | founders |\n\nThe full gallery, every workflow sha256-pinned and proven in CI, lives in\n[`examples/`](examples/): foundation patterns, business showcases, and the\nskeletons `nika new \u003ctemplate\u003e` instantiates (bare `nika try` and\n`nika new '?'` list the live shelves).\n\nShared workflows live on [**nika-registry**](https://github.com/supernovae-st/nika-registry):\nevery entry pinned to a full commit + sha256 and re-proven by CI (the\nconformance oracle + this engine's static certificate: exec · tools ·\ncost, visible before anything runs). `nika add` is on the roadmap; today\nthe registry's `get.py` does resolve → verify → audit in one command.\n\n## The model\n\nFour verbs, and nothing else. A small core that composes into arbitrary\nreal-world workflows. The Unix and SQL discipline of \"small surface, large\ncomposition.\"\n\n| Verb | What it does |\n|---|---|\n| `infer` | Call an LLM. Any provider, local or hosted |\n| `exec` | Run a shell command |\n| `invoke` | Call a tool or MCP server (an HTTP fetch, GitHub, a builtin…) |\n| `agent` | Run an autonomous loop with tools, until the task is done |\n\nEverything sits under one frozen, versioned envelope, `nika: v1`, that won't\nbreak. Three properties hold across every workflow:\n\n- **Provider-agnostic, local-first.** Local Ollama or LM Studio, any API —\n  or no server at all: every release binary serves GGUFs itself\n  (`nika model pull` → `nika model serve`, loopback, 0.101+). Your\n  workflow doesn't change when the model does.\n- **Safe by construction.** A read-XOR-write capability model. A step that\n  reads cannot silently write; every effect is explicit and gated.\n- **Reproducible.** The file and its execution trace are an auditable,\n  re-runnable record.\n\n```mermaid\nflowchart LR\n    F[\"workflow.nika.yaml\u003cbr/\u003e\u003ci\u003eportable · readable · verifiable\u003c/i\u003e\"] --\u003e E[\"\u003cb\u003enika\u003c/b\u003e\u003cbr/\u003esingle Rust binary\"]\n    E --\u003e|infer| L[\"LLMs\u003cbr/\u003eOllama · LM Studio · any API\"]\n    E --\u003e|exec| S[\"shell\"]\n    E --\u003e|invoke| T[\"tools · MCP\"]\n    E --\u003e|agent| A[\"autonomous loop\"]\n```\n\nDependencies make every workflow a graph: independent tasks run in\nparallel, an `agent` step fans out, joins wait for every branch, and the\nwhole plan is known, costed and audited before execution starts (the\ncapture at the top of this page shows exactly that).\n\n## Why Nika\n\nThe closest analogues aren't products. They're **standards**. SQL. The\nDockerfile. A portable specification with a reference engine. The language is\nthe contribution, not a product to sell.\n\nThe language has been finding this shape for a while: an *exploration*\nera of private prototypes through summer 2025 · first git commit on\nJanuary 1, 2026 on the branch named `brouillon` · **79 versions in a\n103-day draft era** (public [crates.io trail](https://crates.io/crates/nika/versions)\nfrom March) · then **rewritten from scratch on April 13, 2026** — the\nDiamond era, an orphan branch, zero code inherited, the version line\ncontinuing because the language is the continuity. Every dated claim is machine-verified in the spec\nrepo's [timeline](https://github.com/supernovae-st/nika-spec/blob/main/timeline/timeline.yaml),\nrendered with the forward gates at [nika.sh/timeline](https://nika.sh/timeline).\n\nAs AI agents start acting on the real world, the interface where they act\ncan't be free text (too vague) or raw code (too risky). It has to be a\n**verifiable action language**: one an AI writes, a human reviews and approves,\nand a machine runs deterministically. Kept open and sovereign, not locked\ninside one vendor's cloud.\n\nWhat no existing workflow tool offers together: a single Rust binary · portable\ndeclarative YAML · local-first · read-XOR-write capability security · AGPL ·\nno cloud required · bring-your-own-LLM.\n\nComing from Airflow, Dagster, LangGraph, Temporal or plain GitHub Actions?\nThe docs keep an honest\n[how-Nika-compares](https://docs.nika.sh/concepts/how-nika-compares) page,\nincluding when *not* to use Nika.\n\n## Status\n\nNika is built in the open.\n\nThe **language** (the `nika: v1` envelope and its four verbs) is stable and\nwon't break. The **engine** is a strict, modular Rust workspace. The latest\ntagged public release is whatever the badge at the top of this page says:\nalways [the releases page](https://github.com/supernovae-st/nika/releases/latest),\nnever a number typed here (numbers in prose rot). `main` moves immediately\nto the next `-dev` version after each release so local contributor binaries\ncannot be confused with Homebrew assets. The 1.0.0 launch remains gated by the release\nchecklist, not by a date. The code, the\n[spec](https://github.com/supernovae-st/nika-spec), and the\n[example workflows](examples/) are all readable, and development happens on\n`main` in the open.\n\nThe `nika: v1` language envelope is frozen forever. It is a separate axis from the\nengine version. Every release is complete for its declared scope; no\nhalf-features parked behind a future version.\n\n## Get started\n\nInstall (macOS · Linux):\n\n```sh\n# Homebrew (macOS · Linux): on your PATH immediately\nbrew install supernovae-st/tap/nika\nnika welcome   # thirty seconds: what Nika is + what it sees on this machine · offline\n\n# …or, without Homebrew: the install script. It downloads the verified release\n# binary into ~/.nika/bin and prints the single PATH line to add to your shell\n# profile (then reopen the terminal, or `source` it, and `nika --version` works).\ncurl -LsSf https://nika.sh/install.sh | sh\n```\n\nPrefer a guided page? Every install path, step by step: [nika.sh/install](https://nika.sh/install).\n\n\u003e Fully manual / air-gapped? Download the platform tarball + `SHA256SUMS` from the\n\u003e [latest release](https://github.com/supernovae-st/nika/releases/latest), verify\n\u003e with `sha256sum -c SHA256SUMS --ignore-missing`, then move `nika` onto your `PATH`.\n\nAlready carrying a toolchain?\n\n```sh\n# cargo: fetches the PREBUILT release tarball (no compile); the binary lands\n# as `nika-cli` until the crates.io publish; symlink the public name once:\n#   ln -sf ~/.cargo/bin/nika-cli ~/.cargo/bin/nika\ncargo binstall --git https://github.com/supernovae-st/nika nika-cli\n\n# nix: builds the exact release source via the flake (first run compiles,\n# the store caches it); `nix profile install` for a durable install\nnix run github:supernovae-st/nika\n```\n\nDeploying to containers (Dokploy · Coolify · Railway · any PaaS)?\n\n```sh\n# docker: the official multi-arch image (ghcr · linux/amd64 + linux/arm64),\n# built on the release train from the same verified release binaries;\n# mount your workdir to check/run workflows\ndocker run --rm -v \"$PWD:/work\" -w /work ghcr.io/supernovae-st/nika check hello.nika.yaml\n\n# the MCP lane (stdio JSON-RPC): wire it into any MCP client config\ndocker run -i --rm ghcr.io/supernovae-st/nika mcp\n```\n\nEmbedding the checker in a page or a JS tool? Every release attaches the\nwasm half of `nika check` as an npm tarball — on the registry as\n[`@supernovae-st/nika-check-wasm`](https://github.com/supernovae-st/nika/tree/main/crates/nika-check-wasm)\n— the same rows, codes and character-exact spans as the binary, judged\nbefore a token is spent. It powers the live playground at\n[nika.sh/play](https://nika.sh/play).\n\nYour first workflow runs with **zero setup**: no model, no API key:\n\n```sh\ncat \u003e hello.nika.yaml \u003c\u003c'YAML'\nnika: v1\nworkflow:\n  id: hello\ntasks:\n  greet:\n    exec:\n      command: \"echo hello from nika\"\nYAML\n\nnika check hello.nika.yaml   # static audit, before a single token is spent\nnika run hello.nika.yaml     # execute locally\n```\n\nAdding an AI step? Point it at a local model and nothing leaves your machine:\n\n```yaml\nmodel: ollama/llama3.2:3b    # local · or mistral/..., anthropic/..., any provider\ntasks:\n  greet:\n    infer:\n      prompt: \"Say hello in one sentence.\"\n```\n\n(No model handy? The built-in `mock/echo` previews any workflow offline.)\n\nFor real inference, run a local model (Ollama / LM Studio) or set a provider\nkey, then see what's wired:\n\n```sh\nnika doctor                  # provider keys + local servers, with the exact fix\nnika init                    # schema wiring + AGENTS.md for this repo\nnika wire cursor             # explicit MCP wiring · also: vscode · windsurf · claude · codex · zed · all\nnika try                     # browse the embedded examples\nnika try 01-hello --model ollama/llama3.2:3b     # a real local run\n```\n\nFrom source (contributors): `git clone https://github.com/supernovae-st/nika.git \u0026\u0026 cd nika \u0026\u0026 cargo test --workspace --lib`. End-user docs: [docs.nika.sh](https://docs.nika.sh).\n\n## Work with your agents\n\nNika is built to be **written by agents and reviewed by you**. `nika init`\ndrops the schema wiring, `AGENTS.md`, the Cursor rule and a repo-level\n[agent skill](https://agentskills.io) into your repo so Claude Code, Cursor,\nCodex and friends author valid workflows on the first try. `nika wire\n\u003ccursor|vscode|windsurf|claude|codex|all\u003e` points each client's MCP config at\nthe engine: idempotent, and it preserves your other servers. `nika mcp`\nexposes a read-only oracle any MCP client can call: 9 tools, `nika_check` and\n`nika_inspect` through `nika_catalog` and `nika_tools`. `nika lsp` speaks LSP to every editor.\n\nThe full map of every door (install paths, IDEs, agents, skills, MCP, CI,\nSDKs) is one page: [docs.nika.sh/integrations/everywhere](https://docs.nika.sh/integrations/everywhere).\n\nWondering which model on your machine can actually drive a workflow? The\n[model bench](https://docs.nika.sh/examples/model-bench) is a workflow that\nbenches your models: same tasks, every local/cloud model you point it at,\nan honest scorecard out (unpriced never reads as free).\n\nOr install everything as a plugin: this repo hosts one plugin (the\nauthoring skill · the `nika-author` subagent · three commands · a\ncheck-on-edit hook · the read-only MCP oracle) for three ecosystems:\n\n```sh\ncodex plugin marketplace add supernovae-st/nika-agents \u0026\u0026 codex plugin add nika@nika\nclaude plugin marketplace add supernovae-st/nika-agents \u0026\u0026 claude plugin install nika@nika\n# Cursor: search \"nika\" in Settings → Plugins · one Add installs the bundle\n```\n\nAgents discover a working prompt chain once; Nika keeps it as a file your\nteam can check, run and replay.\n\n## Send us a workflow\n\nDo you repeat an AI task every week, in ChatGPT, Claude, Cursor, Codex, or\nscripts? That loop is exactly what a workflow keeps:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"media/gifs/chat-to-workflow.optimized.gif\" alt=\"A repeated chat prompt becomes meeting-actions.nika.yaml; nika check audits it, then a real local run (ollama/llama3.2:3b) writes typed action items\" width=\"900\" /\u003e\n\u003c/p\u003e\n\nDescribe yours at [nika.sh/convert](https://nika.sh/convert) or\n[open a \"convert my workflow\" issue](https://github.com/supernovae-st/nika/issues/new/choose).\nWe convert the best ones into runnable `.nika.yaml` examples, credited to you.\n\n## Editor support\n\nThis repo is the **engine**. It ships the language server (`nika lsp`, over stdio).\nThe VS Code / Cursor / Windsurf / VSCodium **extension** lives in its own repo and\nis published as [`supernovae.nika-lang`](https://marketplace.visualstudio.com/items?itemName=supernovae.nika-lang)\n(and on [Open VSX](https://open-vsx.org/extension/supernovae/nika-lang) for Cursor / Windsurf / VSCodium):\n\n- Install it from your editor's marketplace. It auto-downloads the matching `nika`\n  release binary on first use (or reuses the `nika` already on your `PATH`).\n- Source + issues: [supernovae-st/nika-vscode](https://github.com/supernovae-st/nika-vscode).\n- Any other editor: `nika lsp` speaks LSP over stdio. Wire it into any LSP client.\n\n## The constellation\n\nThis repo is the engine. Everything around it lives in its own repo,\neach with one job:\n\n| Repo | What it is |\n|---|---|\n| [nika](https://github.com/supernovae-st/nika) | **this engine**: the reference implementation (AGPL-3.0-or-later) |\n| [nika-spec](https://github.com/supernovae-st/nika-spec) | the open language spec + conformance corpus (Apache-2.0), the law the engine follows |\n| [nika-docs](https://github.com/supernovae-st/nika-docs) | the source of [docs.nika.sh](https://docs.nika.sh) |\n| [nika.sh](https://github.com/supernovae-st/nika.sh) | the source of [nika.sh](https://nika.sh) |\n| [nika-vscode](https://github.com/supernovae-st/nika-vscode) | the editor extension: VS Code, Cursor, Windsurf, VSCodium |\n| [nika-agents](https://github.com/supernovae-st/nika-agents) | the plugin marketplace: skill + subagent + commands + hooks + the read-only MCP oracle · Claude Code, Codex, Cursor |\n| [nika-registry](https://github.com/supernovae-st/nika-registry) | the verifiable workflow registry: every entry pinned and re-proven in CI |\n| [nika-client](https://github.com/supernovae-st/nika-client) | the TypeScript SDK (targets the `nika serve` HTTP surface) |\n| [homebrew-tap](https://github.com/supernovae-st/homebrew-tap) | the brew formula: `brew install supernovae-st/tap/nika` |\n| [nika-action](https://github.com/supernovae-st/nika-action) | the GitHub Action: check verdict, cost floor, permits and the DAG as a sticky PR comment |\n| [nika-actions-starter](https://github.com/supernovae-st/nika-actions-starter) | template repo: AI-workflow receipts in CI from the first push |\n| [gh-nika](https://github.com/supernovae-st/gh-nika) | the GitHub CLI extension: `gh nika check/run`, checksum-verified fetch |\n| [nika-estate](https://github.com/supernovae-st/nika-estate) | the estate law: every file is authored bytes or a proven derivation, sealed and anchored |\n\nExamples live right here: [`examples/`](examples/), the embedded\ngallery (bare `nika try` shows the same shelf from the binary).\n\n**Building Nika?** The engine is crafted under a strict workspace discipline:\ncontext-window-sized crates, a per-crate admission checklist, zero `.unwrap()`\nin `src/` (CI-enforced), downward-only layering. The design lives in\n[`docs/architecture/`](docs/architecture/) and the decisions in\n[`docs/adr/`](docs/adr/README.md); the roadmap is in [`ROADMAP.md`](ROADMAP.md).\n\n## License\n\nThe **engine** is AGPL-3.0-or-later (see [`LICENSE`](LICENSE)): modify it and\nrun it as a hosted service, and users of that service get the source. The\n**spec** is [Apache-2.0](https://github.com/supernovae-st/nika-spec), maximally\npermissive for a standard.\n\nA commercial license (Grafana model) is available for organizations that can't\naccept AGPL's network clause. Contact `contact@supernovae.studio`. Security\nreports: `security@supernovae.studio`.\n\n---\n\n© 2024–2026 [SuperNovae Studio](https://supernovae.studio) · 🦋 Nika, the\nbutterfly on the SuperNovae flag. *Prompt once. Run forever.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupernovae-st%2Fnika","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupernovae-st%2Fnika","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupernovae-st%2Fnika/lists"}