{"id":45476640,"url":"https://github.com/supernovae-st/nika","last_synced_at":"2026-07-05T04:01:06.991Z","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-02T07:29:51.000Z","size":6117,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-02T09:23:07.820Z","etag":null,"topics":["agents","ai","ai-agents","ai-workflows","automation","cli","dag","developer-tools","devops","llm","local-ai","lsp","mcp","ollama","rust","structured-output","supernovae","workflow","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":"CITATIONS.md","codeowners":null,"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-02T07:29:56.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":240,"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":35142824,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"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","lsp","mcp","ollama","rust","structured-output","supernovae","workflow","workflow-engine","yaml"],"created_at":"2026-02-22T15:29:36.088Z","updated_at":"2026-07-05T04:01:06.943Z","avatar_url":"https://github.com/supernovae-st.png","language":"Rust","funding_links":["https://supernovae.studio"],"categories":["Workflow","Libraries and Frameworks","MCP Servers","Software","Command Line Tools","NLP"],"sub_categories":["AI \u0026 LLM Testing","Usage"],"readme":"# 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\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\nA Nika workflow is just a file: readable, portable, verifiable. It runs\nlocally, on whichever LLM you choose, with no cloud required. The language\nis an open [Apache-2.0 spec](https://github.com/supernovae-st/nika-spec);\nthis repo is the reference engine, a single Rust binary (AGPL-3.0). The\nway SQL pairs with PostgreSQL, or the Dockerfile with Docker.\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\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 examples run 01-hello --model mock/echo            # zero setup: no key, no model server\nnika examples run 01-hello --model ollama/qwen3.5:4b    # got Ollama? the same run, real + local\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\n```text\n$ nika check brief.nika.yaml\n ✔ PLAN     2 wave(s) · 2 task(s) · max parallelism 1\n ✔ SECRETS  no information-flow escapes\n ✔ TYPES    every deep output reference fits its declared shape\n ✔ TOOLS    every nika: tool names a canonical builtin\n ✔ ARGS     every invoke arg key is declared + every required arg is present\n ✔ SCHEMA   every authored schema: is satisfiable\n ✔ clean — audited before a single token was spent\n\n$ nika run brief.nika.yaml\n  🦋 nika · daily-brief · 2 tasks\n  ✔  fetch_notes  exec · cat\n  ✔  brief        infer · ollama/llama3.2:3b\n  ── 2/2 done · $0.000 · elapsed 16.2s ───────────────────────────\n```\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: pr-risk-review\nmodel: ollama/qwen3.5:9b             # local by default. swap to any provider\n\ntasks:\n  - id: diff                          # exec: a read-only shell command\n    exec:\n      command: \"git diff origin/main...HEAD\"\n      capture: structured\n\n  - id: assess                        # infer: structured LLM judgment\n    with: { patch: ${{ tasks.diff.output.stdout }} }\n    infer:\n      prompt: \"Risk-assess this diff (secrets, breaking changes, missing tests). Be terse.\\n${{ with.patch }}\"\n      schema:\n        type: object\n        required: [risk]\n        properties:\n          risk: { type: string, enum: [low, medium, high] }\n\n  - id: comment                       # invoke: the only write, gated on the verdict\n    when: ${{ tasks.assess.output.risk == 'high' }}\n    invoke:\n      tool: \"mcp:github/pr-comment\"\n      args: { body: ${{ tasks.assess.output }} }\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**\n— and when something is off, it points at the exact fix:\n\n![nika check catches a missing depends_on and a typo'd task reference, shows the three-line 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## Daily commands\n\n```sh\nnika inspect flow.nika.yaml          # anatomy · tasks · waves · cost floor\nnika check flow.nika.yaml            # the audit · exit 0 clean · 2 findings\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\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\n```\n\nA paused run exits `4` (a blocking `nika:prompt` journals its question);\ncache hits on resume are always visible — nothing is skipped silently.\n\n## Pick a workflow\n\nThe binary embeds a versioned pack of runnable examples. Browse with\n`nika examples list`, read one with `nika examples show \u003cslug\u003e`, preview any\nof them with `--model ollama/qwen3.5:4b` (or offline with `--model mock/echo`):\n\n| I want to… | Run | For |\n|---|---|---|\n| Review a PR before merging | [`examples/pr-risk-review.nika.yaml`](examples/pr-risk-review.nika.yaml) | developers |\n| Turn meeting notes into owned actions | `nika examples run showcase/t1-meeting-actions` | everyone |\n| Digest a week of standups | `nika examples run showcase/t1-standup-digest` | teams |\n| Draft release notes from commits | `nika examples run showcase/t2-release-notes` | maintainers |\n| Triage a support inbox | `nika examples run showcase/t2-support-triage` | support · ops |\n| Chase unpaid invoices politely | `nika examples run showcase/t2-invoice-chaser` | founders |\n| Track competitors weekly | `nika examples run showcase/t3-competitor-radar` | founders |\n| Screen resumes against a role | `nika examples run showcase/t3-resume-screener` | hiring |\n| Build a Monday operating brief | `nika examples run showcase/t4-ceo-monday-brief` | founders |\n\nThe full gallery (27 workflows + 6 templates) lives in\n[`examples/`](examples/): foundation patterns, business showcases, and the\nskeletons `nika new --from \u003ctemplate\u003e` instantiates.\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, or any API.\n  Your 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:\n\n![The embedded pr-review-fanout workflow as its real execution graph: seven tasks, six waves, all four verbs in one file](media/gifs/dag-execution.optimized.gif)\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\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\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 **v0.91.0**; `main` moves immediately to the next\n`-dev` version after each release so local contributor binaries cannot be\nconfused 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 --version\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\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: hello\ntasks:\n  - id: 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  - id: 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 · all\nnika examples list           # browse the embedded examples\nnika examples run 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 (`nika_check` + `nika_explain`) any MCP client can\ncall. `nika lsp` speaks LSP to every editor.\n\nOr install everything as a plugin — this repo hosts one plugin (the\n`nika-authoring` skill + the MCP oracle) for both 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```\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? Describe it 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## Documentation\n\n- **Language spec**: [supernovae-st/nika-spec](https://github.com/supernovae-st/nika-spec) (Apache-2.0), the runtime-agnostic Nika language.\n- **End-user docs**: [docs.nika.sh](https://docs.nika.sh).\n- **Website**: [nika.sh](https://nika.sh).\n- **Examples**: [`examples/`](examples/), the embedded gallery (also `nika examples list`).\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"}