.nika file, you review it, the runtime enforces it, and it
runs again next week without re-prompting.
Two commands wire any agent:
@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:
--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:
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):
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: anyNIKA-XXXerror 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
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.
Read next
Agent authoring protocol
Templates
nika compile --list names.