# nika.sh · llms.txt
# https://llmstxt.org/

> Nika is the checked workflow language for AI: an agent writes its plan as a
> readable file (steps, tools, permissions, outputs), nika check reads it back
> before a token is spent, the runtime enforces it, then it runs (traced and
> replayable). An open workflow language plus its reference engine in Rust.
> Apache-2.0 spec · AGPL-3.0-or-later engine. Paris. SuperNovae Studio.

## What

Nika reads `.nika` files and executes them as AI workflows.
Four verbs, locked forever: `infer` (LLM call), `exec` (subprocess),
`invoke` (builtin/tool; HTTP fetch is the `nika:fetch` builtin here),
`agent` (agent loop). Everything callable is a tool under `invoke`;
a verb is a distinct native execution model.

The envelope has nine top-level keys: `nika:` (the mark AND the file's
name, kebab-case · never a version marker) · model · inputs · const ·
secrets · permits · run · tasks · outputs. Values come from three
authorities: inputs (caller-supplied, with defaults), const (baked in),
secrets (vault-backed references). A file names no version; the binary
that runs it is the version. The engine versions on real semver toward
a 1.0 launch; currently v0.120.3.

Stdlib v0.1: 28 builtins · 17 providers (Ollama, LM Studio, llama.cpp,
LocalAI, vLLM, Mistral, Hugging Face, OpenAI, xAI, Anthropic, Gemini,
Groq, DeepSeek, OpenRouter, NVIDIA, Moonshot, mock) · 10 extract modes.
Bring your own keys. Every key stays yours. Local-first. Runs on your
laptop, no daemon.

## The contract

Every workflow declares its blast radius. The permits: block is a
default-deny allowlist by family: fs (read/write globs), net.http
(hosts), exec (argv-sound programs), tools. A step that reaches outside
it is refused before anything runs (NIKA-SEC-004); link-local and
metadata endpoints stay refused regardless (NIKA-SEC-005, the always-on
floor); secrets stay masked references with scoped egress. Every run
leaves a hash-chained NDJSON trace: `nika trace verify` walks the chain
and names the first broken link. `nika check` prices the plan's cost
floor before a token is spent; `--max-cost-usd` is a hard ceiling.
`nika check --infer-permits` writes the tightest boundary a file can
prove.

The boundary's laws were proposed as numbered public documents
(NEP-0002..0009: the lethal-trifecta human gate · absent permits declare
zero authority · untrusted values re-gate at the effect · the environment
permit · the data-as-code sink · the trace witness and differential oracle
· the egress proxy as the permit's exact projection · path grants
re-judged at dispatch) and folded into the specification chapters on
2026-08-13; the fold table names where each law lives now:
https://github.com/supernovae-st/nika-spec/tree/main/governance
Provenance: the public repos ship estate manifests (estate.yaml): every
tracked file declared authored or generated, hashed, checkable.

## Examples (canonical · conformance-gated)

Every spec version ships a versioned examples pack: foundation
workflows teaching the constructs plus tiered showcase real jobs
(T1 starter → T4 epic), each a complete validated file. The manifest
(pack_version · constructs · sha256 per file) makes the pack
verifiable end-to-end; docs and site render projections of the same
files.
Every served library file (e.g. https://nika.sh/library/daily-brief.nika) carries its SPDX line (Apache-2.0).

- Templates (instantiate, never invent: SLOT-marked skeletons): https://docs.nika.sh/guides/templates · machine catalog: https://nika.sh/templates/catalog.json · source: https://github.com/supernovae-st/nika-spec/tree/main/templates
- Agent authoring protocol: https://docs.nika.sh/guides/agent-authoring
- Pack manifest: https://github.com/supernovae-st/nika-spec/blob/main/examples/manifest.yaml
- Showcase source: https://github.com/supernovae-st/nika-spec/tree/main/examples/showcase
- Walkthroughs: https://docs.nika.sh/examples/overview
- Interactive explorer: https://nika.sh/#use-cases
- Blog (markdown source: content/blog in the site repo): https://nika.sh/blog · feed https://nika.sh/rss.xml · full text https://nika.sh/llms-full.txt · every post serves its markdown twin beside the page (append .md, e.g. https://nika.sh/blog/intent-as-code.md) · one citable register per tag (e.g. https://nika.sh/blog/tags/engine)

## TypeScript SDK

Published npm package: `@supernovae-st/nika@0.120.3` (bundles engine 0.120.3).
Standalone CLI GitHub release: `nika 0.120.3`. Do not merge those clocks.

```js
import { Nika, isNikaRunSucceeded } from '@supernovae-st/nika'
const nika = new Nika()
const run = await nika.run('hello.nika', { maxCostUsd: 0 })
const result = await run.result()
if (!isNikaRunSucceeded(result)) throw new Error(result.status)
```

`mock/echo` rehearses offline. `traceVerify` checks an existing journal; it
does not seal one or rerun the model. Create a fresh `run()` before consuming
`run.events()`.

- Marketing SDK door: https://nika.sh/sdk
- Full SDK manual: https://docs.nika.sh/sdk/overview
- Quickstart: https://docs.nika.sh/sdk/start/quickstart
- Client source: https://github.com/supernovae-st/nika-client

## Design system (machine-readable)

Every Nika verb, builtin, feature and run-state has a canonical icon,
color role and motion pattern, declared once in an ontology and served
as data. Verb hues (infer blue · exec orange · invoke cyan · agent
violet) appear ONLY on live-run surfaces; static UI keeps the text ink.

- Icon ontology (JSON · 79 entities · labels, semantics, hue tokens, links): https://nika.sh/brand/icons.json
- RDF projection (Turtle · SPARQL-ready · namespace https://nika.sh/ontology/design#): https://nika.sh/brand/icons.ttl
- Served icon catalog: https://nika.sh/brand/icons/<namespace>-<name>.svg (e.g. verb-infer, builtin-fetch, state-recovered)
- Brand kit + usage rules: https://nika.sh/brand · https://github.com/supernovae-st/nika.sh/blob/main/BRAND.md

## How to write Nika (the 12 patterns)

Deterministic core, model at the edges · parallelism is the default ·
type the boundaries · fan out with a leash · plan-then-execute · three
gates (when=skip, assert=fail, prompt=human) · sovereignty is a model:
line · agents get budgets · evidence always lands (a cleanup task on an
`unwind` edge) · one
data language (jq) · workflows are callable · mock-first.

- Patterns guide: https://docs.nika.sh/guides/patterns

## Links

- How the standard CHANGES: https://github.com/supernovae-st/nika-spec/tree/main/governance · YAML reference: https://docs.nika.sh/reference/yaml-syntax
- Language spec (Apache-2.0): https://github.com/supernovae-st/nika-spec
- Standard library: https://docs.nika.sh/reference/builtins · one tool page (e.g. https://docs.nika.sh/reference/tools/fetch) · machine catalog: https://nika.sh/tools/catalog.json
- The four verbs: https://docs.nika.sh/concepts/verbs
- Language words (e.g. https://docs.nika.sh/reference/language/words/with) · the contract: https://nika.sh/schema/workflow.json
- Error catalog: https://docs.nika.sh/reference/error-codes · machine catalog: https://nika.sh/errors/catalog.json
- Providers: https://docs.nika.sh/reference/providers-catalog · MCP catalog: https://docs.nika.sh/reference/mcp-catalog · machine catalog: https://nika.sh/providers/catalog.json
- Engine source (AGPL): https://github.com/supernovae-st/nika
- Architecture decisions: https://docs.nika.sh/architecture/adrs · machine surfaces: https://nika.sh/engine/adr/index.json and https://nika.sh/engine/adr/bodies.json
- Agent lane (MCP oracle): https://github.com/supernovae-st/nika-plugins
- Editor lane: https://github.com/supernovae-st/nika-vscode · schema: https://nika.sh/spec/v1/workflow.schema.json
- Install: https://nika.sh/install (or `brew install supernovae-st/tap/nika`) · ARM64: https://nika.sh/install/arm64 · servers: https://nika.sh/install/servers · local models: https://nika.sh/install/local-models
- Workflow Sprint by SuperNovae Studio: https://nika.sh/automate
- Docs: https://docs.nika.sh
- Registry: https://github.com/supernovae-st/nika-registry · machine index: https://raw.githubusercontent.com/supernovae-st/nika-registry/main/index.json
- Release record: https://nika.sh/releases/catalog.json · notes: https://github.com/supernovae-st/nika/releases
- Changelog: https://nika.sh/changelog
- Crawler twin: https://nika.sh/sitemap.xml · lens twin: https://nika.sh/ontology/language.json
- Timeline: https://docs.nika.sh/reference/timeline
- Integrations: https://docs.nika.sh/integrations/everywhere · Claude Code: https://docs.nika.sh/integrations/clients/claude-code · Codex: https://docs.nika.sh/integrations/clients/codex · Cursor: https://docs.nika.sh/integrations/clients/cursor · VS Code: https://docs.nika.sh/integrations/clients/vscode · Hermes: https://docs.nika.sh/integrations/hermes · MCP clients: https://docs.nika.sh/integrations/mcp-clients
- Examples: https://docs.nika.sh/examples/overview
- Getting started: https://docs.nika.sh/getting-started/first-workflow
- Catalog machine twin: https://nika.sh/nika-graph.json

## Status

Shipping in the open (v0.120.3, real semver toward 1.0). The engine is admitted crate by crate (the repo README carries the live count). Each passes
a 12-gate admission (TDD, mutation testing ≥90%, zero `.unwrap()` in src).
Language v0.1 public spec is live; 1.0 is readiness-gated: the timeline carries the gates (conditions, never dates).
Building in public.

Next engine release (not published yet): bare `nika` in a terminal becomes a
conversation that ends in a reviewable workflow file. You describe the
outcome, Nika asks for values it cannot settle, and it proposes a `.nika`
file with its steps, reach and check result. `yes` saves exactly those bytes
and runs nothing; `run it` is a separate request under an announced spending
ceiling; the result names what the run produced and read, beside its trace.
The current release does not include this path. Its qualified scope is a
bounded set of synthetic journeys on one macOS installation, not a general
reliability claim:
https://github.com/supernovae-st/nika/blob/8e1683d2237e1bbfa7401b7ed853ab91a2e2e6c9/docs/qa/delivery-a-2026-09.md

## License

Spec: Apache-2.0 (adopt freely, patent grant). Engine: AGPL-3.0-or-later.
Full copyleft. No SaaS loophole.