nika

What is Nika?

Nika turns repeatable AI work into a small file you keep. Say what you want done, like "every Monday, pull the action items out of my meeting notes", and Nika writes it as a readable .nika workflow. Before anything runs, its check shows what the workflow will do, which models and tools it uses, what it is allowed to touch and what it can cost, without calling a model. You run it when you decide, with the model you choose, local or cloud, and every run leaves a tamper-evident record you can verify. One Rust binary, local-first, open source (AGPL-3.0).

1 · Say it	2 · Check it	3 · Run it	4 · Prove it
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

See it in four steps

1 · Say it

Describe the job in plain words. Nika writes it as a .nika file, shows you what it will do and what it can touch, and saves it only when you say yes. Nothing runs until you ask.

2 · Check it

Before anything runs, nika check reads the file and reports what it will do, what it may touch and what it can cost. It calls no model and spends nothing.

3 · Run it

You run it when you decide, with the model you choose. Here a local model, through Ollama, writes a meeting's action items as typed JSON.

4 · Prove it

Every run leaves a hash-chained record. nika trace verify reads it back, and when a single byte changes it names the line where the chain breaks.

You stay in control

It tells you the cost before the first token

nika check prices a workflow from its model's catalog price and the output limit each step declares. Set a budget below that ceiling and the run refuses to start: no model is called and nothing is spent.

It asks before it acts

A step can wait for a person. At your terminal it asks; in CI, where nobody can answer, the run pauses safely with exit 4 and prints the one line that resumes it.

Try it in two minutes

1 · Install

curl -LsSf https://nika.sh/install.sh | sh

• Homebrew: brew install supernovae-st/tap/nika
• npm, the binary plus a TypeScript client: npm install @supernovae-st/nika (the nika command lands in node_modules/.bin). The npm package can trail the latest release: check nika --version.
• A release archive: download one from the latest release; every release ships SLSA provenance you can verify. The install guide shows how.
• Nix: the repository has a flake. It builds the default branch, which can be ahead of the latest release.
• Windows: use WSL2. Native Windows binaries are not shipped yet.

2 · Say what you want

This first job needs no AI account: Nika's deterministic compiler settles it without calling a model. Make a folder with a small spreadsheet and open the Session:

mkdir -p orders-demo/data && cd orders-demo
cat > data/orders.csv <<'EOF'
order_id,customer,status,amount
1001,Juniper Books,paid,18.00
1002,Kestrel Cafe,pending,9.50
1003,Linden Studio,paid,13.50
1004,Moss Supply,refunded,6.00
EOF
nika

At the prompt, type:

Read ./data/orders.csv, keep only the rows whose status is paid, and write them to ./out/paid.csv.

Nika proposes a .nika file and shows what it will do, what it can touch and the result of its check. Nothing has run yet. Type yes to save the file, then run it. out/paid.csv gets the header and the two paid rows, and /proof shows what the run's record proves, and what it does not.

[!TIP] Nika works only inside the folder you start it in. /show prints the proposal's exact bytes, /meaning maps your request clause by clause, and no discards it. Ctrl+T switches the view to full screen and back, and nika --plain gives the same Session as plain lines. The Session guide covers questions, changes, spending ceilings and /restore.

3 · Add a model

Most open-ended requests need a model to write the workflow, and workflows such as summaries call a model each time they run. Nika reads provider keys from your environment, so keep yours in your shell startup file. For DeepSeek:

# in ~/.zshrc or ~/.bashrc, then open a new terminal
export DEEPSEEK_API_KEY='your-key'

The first request that needs a model shows a numbered choice: answer 2 deepseek/deepseek-flash. Nika keeps the choice for later Sessions, and /intelligence changes it. Other API providers and local engines (Ollama, llama.cpp, LM Studio, vLLM) work too: nika catalog lists them. Your provider meters and bills these calls; Nika's cost figures are catalog estimates, not invoices.

4 · Use the file directly

A workflow is an ordinary file. The command line compiles, checks, runs and verifies it. This offline lesson needs no provider:

nika compile hello hello.nika
nika check hello.nika
nika run hello.nika
nika trace verify

▶ Watch these four commands run, exactly as captured from the CLI.

hello always uses mock/echo, a stand-in model that echoes the prompt, even when provider keys are present. It proves that the workflow runs, not that a model answered. Each run records its trace under .nika/traces/, and creating the file adds that directory to .gitignore. nika trace verify checks the latest trace's integrity, not the truth of an AI answer.

What you can hand to Nika

You say	Nika keeps	Watch
"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
"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
"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
"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

Why a file, and not a chat?

A chat answer is gone when the conversation ends, and the next one can differ. A .nika file stays: you read it, check it, run it again and review its changes like any other file in your project.

• Say it once. The request you would retype in a chat every week is kept as a file that runs again. ▶ Watch a weekly request become a file
• Read it before it runs. Every workflow has the same shape: nine sections and four kinds of step, in a file you can open and review. ▶ Watch one taken apart
• It touches only what it declares. The file lists what it may read, write and reach. The check refuses the step that reaches past it. ▶ Watch the check catch an escape
• Failures are planned for. A step can name its fallback: the run finishes, the output says it is stale, and the record keeps the failure. ▶ Watch a missing feed absorbed
• Parallel where it can be. Steps that do not depend on each other run side by side, in waves the check plans before the run. ▶ Watch a workflow run in waves

Apart from the film at the top, an illustration with fixture data, every clip on this page shows real files and terminal lines captured from the binary, and names what it illustrates. The media index lists them all and how they are made.

Works where you already work

Nika comes to the tools you already use. Your coding agent can write the file for you, and the check keeps it honest:

Where	What you get	Watch
Your coding agent · nika-plugins	Claude Code, Codex, Cursor and others learn to write a workflow, check it and repair what the check finds.	▶ above
Your editor · nika-vscode	Errors as you type, and your workflow as a live graph.	▶ The audit, as you type
Your pull requests · nika-action	One comment with the verdict, before anyone spends a token.	▶ Every pull request gets a verdict
Your app · nika-client	Run a workflow from TypeScript (the package), get a typed result and verify its receipt.	▶ Run it from your app, prove what ran

Know the limits

• Nika is pre-1.0. The Session was qualified on six synthetic tasks with one macOS installation of an identified development build, not the released binary (qualification note). That is not a general reliability claim.
• Some requests cannot be expressed yet. Nika then says what stopped it and writes nothing.
• A clean check is not a true answer. It describes a file's structure and boundary; it does not prove that model output is right.
• Public releases do not include a knowledge snapshot. Without one, authoring uses the language card built into the binary.
• This README follows the source tree. An older installed release may lack what it describes: compare nika --version with the changelog. What main carries beyond the latest release is described one file per change in changelog.d/.

Verb	What it does
infer	Ask a model to produce an answer
invoke	Call a native tool, MCP tool or another workflow
exec	Run a command
agent	Let a model use allowed tools for a bounded number of turns

A workflow uses only the verbs its job needs. The film uses invoke and infer; it does not add a shell or an agent loop to fill the diagram.

nika compile --list lists exact skeletons. Preview one with nika compile <slug> --json, then answer its stable questions with repeatable --answer KEY=JSON_LITERAL. An incomplete result includes its candidate and questions; it does not write a file. Only a Ready candidate plus an explicit destination writes. Existing destinations require --force.

For an accepted source, a conservative constant edit uses the same core:

nika compile --base workflow.nika --change 'Set const.topic to "new topic"' --json

Add --output edited.nika to materialize a Ready edit. The base source remains explicit. Unresolved intent stays incomplete without a substitute workflow. --authoring-model explicitly enables bounded model-assisted authoring and text revisions. It sends one authoring request unless --authoring-max-calls N authorizes more (an ACP harness counts one invocation, its own requests unknown). --authoring-strategy selects escalate, only, sketch or off; escalation, repairs and samples stay within the authorized requests. The compiler checks the proposed source and its fidelity to the request. This is not a guarantee of arbitrary-language understanding, and Graph editing is not implemented by this CLI.

Compile's Check preview judges source only. nika check and nika run judge the actual environment separately. For a real model, choose the provider and access explicitly; the model setup documentation explains local, API and supported harness choices.

Share the workflow, not credentials or private data. Review file paths and tool access. Keep secrets out of source control.

Run journals can contain the data and outputs the workflow processed. The .nika/traces/ directory is a data-at-rest surface: it inherits the sensitivity of everything the run read. Exclude it from Git unless you deliberately intend to publish those records, and treat them with the same care as their source data.

After a run, nika trace verify verifies the latest journal. Compare its head with the one printed by the run. This checks the record, not the AI's judgement.

🦋 The Nika family

	Repository	What it gives you
🦋	nika	The engine and CLI: write, check, run and verify AI workflows
📖	nika-docs	The documentation, live at docs.nika.sh
📜	nika-spec	The language specification and the suite that proves an engine follows it
🧩	nika-vscode	The editor extension: your workflow as a live graph, errors as you type
🟦	nika-client	Run and verify workflows from TypeScript
✅	nika-action	A GitHub Action that posts a nika check verdict on your pull requests
🚀	nika-actions-starter	A ready template: workflows, editor setup and CI from the first push
📦	nika-registry	Shareable workflows, pinned and re-verified
🤖	nika-plugins	Teaches your coding agent (Claude Code, Codex, Cursor…) to write Nika
🍺	homebrew-tap	brew install supernovae-st/tap/nika
🐙	gh-nika	The Nika CLI as a GitHub CLI extension
🏛️	nika-estate	Where each file in Nika's core repositories comes from, declared and re-checkable

This repository is the one executable: it parses, checks, runs and traces every workflow. The language is defined by the specification, and the other repositories drive this engine without adding to its authority.

Go further

Session guide · Examples · Documentation · TypeScript SDK · Editor extension · Open specification · Registry · Planning archive · Website

Nika is usable today and pre-1.0. The engine is AGPL-3.0-or-later; the specification is Apache-2.0.