Skip to main content
Your agent already does the work: a PR review in Claude Code, a research brief in Codex, a triage pass in Cursor. Then the chat scrolls away and the procedure is gone. Nika’s job is to keep it: the agent writes the workflow as a .nika file, you review it, the runtime enforces it, and it runs again next week without re-prompting. Two commands wire any agent:
Driving Nika from an app instead of an editor? Install @supernovae-st/nika@0.124.4, write hello.nika, call run(), then run.result() — TypeScript quickstart. The agent loop below is for the editor/CLI door.

nika init: teach the repo

nika init founds a repository for agents and editors. Existing files are skipped (.gitignore is the one file it updates in place, adding its ignore lines); --force overwrites. On a terminal it asks a few questions; --yes accepts every default, and pipes and CI never prompt. In an empty folder, nika init --yes writes these files:
The hooks are shell scripts that Claude Code and Cursor run inside your repository: session-context.sh at session start, check-on-edit.sh after an edit, and guard-run.sh before the agent runs a shell command (it asks nika guard to judge the command). Read them before you commit them, as you would any script an agent executes. The project MCP files make those clients start nika mcp in this repository.
Flags shape the scaffold: --recipe agentic|starter|ship|content|minimal chooses a workflow set, --example <slug> founds the project from one embedded example (any slug from bare nika try) together with what its lesson reads: the fixtures under examples/fixtures/ and the children it invokes, beside it in workflows/, each listed as a created row and never written over an existing file. --wire <clients> also runs nika wire for those clients afterwards.

Or: install the plugin (Codex · Claude Code)

Codex and Claude Code users can skip per-repo setup entirely: the nika-plugins repository publishes one plugin (version 0.124.3) for both ecosystems: 4 skills, 3 subagents, 2 rules, 6 slash commands (check · compile · doctor · explain · permits · trace), 3 hooks (one dialect: Codex speaks Claude Code’s hook contract) and the read-only MCP oracle:
One install: the nika-authoring skill lands (invoke it explicitly, or let it auto-trigger on .nika work), and the read-only oracle is wired (9 tools: nika_check + nika_explain + the authoring surface). The plugin expects the nika binary on your PATH (brew install supernovae-st/tap/nika).

nika wire: give the agent the real oracle

nika wire patches your client’s MCP config to add Nika’s read-only oracle: the agent can check and explain, never execute (nika run stays in your hands): Whatever the harness, the payloads an agent parses are the same versioned wires — envelopes, exit codes, and evolution rules are documented in Machine surfaces. Any other MCP client takes the same stanza — a stdio server, command: nika, args: ["mcp"]. Gemini CLI also accepts gemini mcp add nika nika mcp. Per-client files: MCP clients. The server exposes two tool families — validate and learn:
  • nika_check: the full static audit (plan · cost ceiling · secret flows · types · tool args · schema) as structured JSON. The agent fixes its own file before you ever see it.
  • nika_explain: any NIKA-XXX error code, explained.
  • nika_schema · nika_examples · nika_template · nika_canon · nika_catalog · nika_tools · nika_inspect: the authoring surface — the JSON Schema, the runnable examples, the skeletons, the canon SSOT, the provider + builtin catalogs, and the typed DAG, as versioned machine projections, so the agent follows the template→fill→check→repair path instead of guessing structure. All read-only, all served from the embedded pack.
nika wire codex patches ~/.codex/config.toml ([mcp_servers.nika] · command = "nika" · args = ["mcp"], comments preserved). Codex also reads AGENTS.md natively, so nika init alone already teaches it the authoring loop.

The loop

The model extracts facts. nika:jq or nika:decide is the law — do not pay a second infer to pick a level. Numeric facts are type: integer. The teaching file is nika try 13-extract-then-law. The division of labor is the point: the agent authors, the file is the contract, the human approves, the runtime enforces.

The loop, once through. Asked to turn CHANGELOG.md into release notes, the agent drafts a workflow that calls nika:read_file. nika check --native-strict refuses it (NIKA-BUILTIN-001), the agent repairs it to nika:read, and the re-check says run ready. A mock/echo rehearsal then writes release-notes.md. The checks and the run are captured from the real CLI on nika 0.121.0; the agent session is an illustration.

Editor surface

nika lsp, the language server built into the binary, gives any editor check-as-you-type diagnostics and quick fixes. The VS Code extension adds a DAG view and trace replay on top. The editor extension, frozen at 0.120 and not qualified with 0.124: use nika lsp and the JSON Schema; if you keep it, set its nika.server.path to your installed nika and trust nika check if the two disagree. See Editors.

Agent authoring protocol

The deterministic path: template → fill → check → repair.

Templates

The valid skeletons nika compile --list names.