Nika

June 25, 2026 · View on GitHub

Intent as Code. An open language for AI workflows — one portable file, any model, no cloud.

Nika is an open language for describing and running AI workflows — a YAML specification (Apache-2.0) and a reference engine, a single Rust binary (AGPL-3.0). The way SQL pairs with PostgreSQL, or the Dockerfile with Docker: a portable standard, plus an engine that runs it.

A Nika workflow is just a file — readable, portable, verifiable. It runs locally, on whichever LLM you choose, with no cloud required.

# review.nika.yaml — read a PR diff, judge its risk, comment only when it's high.
nika: v1
workflow: pr-risk-review
model: ollama/llama3.1               # local by default — swap to any provider

tasks:
  - id: diff                          # exec — a read-only shell command
    exec:
      command: "git diff origin/main...HEAD"
      capture: structured

  - id: assess                        # infer — structured LLM judgment
    with: { patch: ${{ tasks.diff.output.stdout }} }
    infer:
      prompt: "Risk-assess this diff (secrets, breaking changes, missing tests). Be terse.\n${{ with.patch }}"
      schema:
        type: object
        required: [risk]
        properties:
          risk: { type: string, enum: [low, medium, high] }

  - id: comment                       # invoke — the only write, gated on the verdict
    when: ${{ tasks.assess.output.risk == 'high' }}
    invoke:
      tool: "mcp:github/pr-comment"
      args: { body: ${{ tasks.assess.output }} }

The model

Four verbs, and nothing else. A small core that composes into arbitrary real-world workflows — the Unix and SQL discipline of "small surface, large composition."

Verb	What it does
`infer`	Call an LLM — any provider, local or hosted
`exec`	Run a shell command
`invoke`	Call a tool or MCP server (an HTTP fetch, GitHub, a builtin…)
`agent`	Run an autonomous loop with tools, until the task is done

Everything sits under one frozen, versioned envelope — nika: v1 — that won't break. Three properties hold across every workflow:

Provider-agnostic, local-first — local Ollama or LM Studio, or any API. Your workflow doesn't change when the model does.
Safe by construction — a read-XOR-write capability model. A step that reads cannot silently write; every effect is explicit and gated.
Reproducible — the file and its execution trace are an auditable, re-runnable record.

flowchart LR
    F["workflow.nika.yaml<br/><i>portable · readable · verifiable</i>"] --> E["<b>nika</b><br/>single Rust binary"]
    E -->|infer| L["LLMs<br/>Ollama · LM Studio · any API"]
    E -->|exec| S["shell"]
    E -->|invoke| T["tools · MCP"]
    E -->|agent| A["autonomous loop"]

Why Nika

The closest analogues aren't products — they're standards. SQL. The Dockerfile. A portable specification with a reference engine. The language is the contribution, not a product to sell.

As AI agents start acting on the real world, the interface where they act can't be free text (too vague) or raw code (too risky). It has to be a verifiable action language — one an AI writes, a human reviews and approves, and a machine runs deterministically. Kept open and sovereign, not locked inside one vendor's cloud.

What no existing workflow tool offers together: a single Rust binary · portable declarative YAML · local-first · read-XOR-write capability security · AGPL · no cloud required · bring-your-own-LLM.

Status

Nika is built in the open.

The language — the nika: v1 envelope and its four verbs — is stable and won't break. The engine is a strict, modular Rust workspace. The latest tagged public release is v0.91.0; main moves immediately to the next -dev version after each release so local contributor binaries cannot be confused with Homebrew assets. The 1.0.0 launch remains gated by the release checklist, not by a date. The code, the spec, and the example workflows are all readable, and development happens on main in the open.

The nika: v1 language envelope is frozen forever — a separate axis from the engine version. Every release is complete for its declared scope; no half-features parked behind a future version.

Get started

Install (macOS · Linux):

# Homebrew (macOS · Linux) — on your PATH immediately
brew install supernovae-st/tap/nika
nika --version

# …or, without Homebrew: the install script. It downloads the verified release
# binary into ~/.nika/bin and prints the single PATH line to add to your shell
# profile (then reopen the terminal, or `source` it, and `nika --version` works).
curl -LsSf https://nika.sh/install.sh | sh

Fully manual / air-gapped? Download the platform tarball + SHA256SUMS from the latest release, verify with sha256sum -c SHA256SUMS --ignore-missing, then move nika onto your PATH.

Your first workflow runs with zero setup — no model, no API key:

cat > hello.nika.yaml <<'YAML'
nika: v1
workflow: hello
tasks:
  - id: greet
    exec:
      command: "echo hello from nika"
YAML

nika check hello.nika.yaml   # static audit — before a single token is spent
nika run hello.nika.yaml     # execute locally

Adding an AI step? With no provider handy, the built-in mock/echo model lets you see the shape offline — swap it for a real model when ready:

model: mock/echo             # → ollama/llama3.1, anthropic/…, openai/… when ready
tasks:
  - id: greet
    infer:
      prompt: "Say hello in one sentence."

For real inference, run a local model (Ollama / LM Studio) or set a provider key, then see what's wired:

nika doctor                  # provider keys + local servers, with the exact fix
nika init                    # schema wiring + AGENTS.md + Cursor rule for this repo
nika wire cursor             # optional · explicit MCP wiring for Cursor agents
nika examples list           # browse the embedded examples
nika examples run 01-hello   # runs on ollama/llama3.1 by default

From source (contributors): git clone https://github.com/supernovae-st/nika.git && cd nika && cargo test --workspace --lib. End-user docs: docs.nika.sh.

Editor support

This repo is the engine — it ships the language server (nika lsp, over stdio). The VS Code / Cursor / Windsurf / VSCodium extension lives in its own repo and is published as supernovae.nika-lang (and on Open VSX for Cursor / Windsurf / VSCodium):

Install it from your editor's marketplace — it auto-downloads the matching nika release binary on first use (or reuses the nika already on your PATH).
Source + issues: supernovae-st/nika-vscode.
Any other editor: nika lsp speaks LSP over stdio — wire it into any LSP client.

Documentation

Language spec — supernovae-st/nika-spec (Apache-2.0), the runtime-agnostic Nika language.
End-user docs — docs.nika.sh.
Website — nika.sh.
Example workflow — examples/pr-risk-review.nika.yaml, a readable four-verb workflow, local-first.

Building Nika? The engine is crafted under a strict workspace discipline — context-window-sized crates, a per-crate admission checklist, zero .unwrap() in src/ (CI-enforced), downward-only layering. The design lives in docs/architecture/ and the decisions in docs/adr/; the roadmap is in ROADMAP.md.

License

The engine is AGPL-3.0-or-later (see LICENSE) — modify it and run it as a hosted service, and users of that service get the source. The spec is Apache-2.0, maximally permissive for a standard.

A commercial license (Grafana model) is available for organizations that can't accept AGPL's network clause. Contact contact@supernovae.studio. Security reports: security@supernovae.studio.