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.120.2, 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 scaffolds the repo (idempotent: existing files are skipped, --force overwrites):
  • AGENTS.md, the agent operating guide: the four verbs, the authoring loop (nika compile <skeleton> --json → answer remaining questions → write a Ready dest → nika check → repair from the error), and the rules that keep generated workflows valid. Read natively by Codex, Claude Code, Cursor, Jules and every AGENTS.md-aware tool.
  • .vscode/settings.json: maps *.nika to the canonical JSON schema, so completions and validation work in any YAML-aware editor.
  • .cursor/rules/nika.mdc, the Cursor rules file (globs *.nika): the syntax floor + the check loop, auto-attached whenever the agent touches a workflow file.
  • Cursor, fully equipped (next release): the three kit subagents (.cursor/agents/nika-{author,debugger,migrator}.md), the delegation rule (.cursor/rules/nika-delegation.mdc) and the three seatbelt hooks (.cursor/hooks.json + .cursor/hooks-nika/ — session context · check-on-edit · a guard that audits before any nika run). Cursor’s local plugin loader consumes MCP + skills only, so the binary carries the rest project-side; every body is byte-identical to the kit.
  • .agents/skills/nika-authoring/SKILL.md (0.93+): a repo-level agent skill — Codex and every .agents-aware client discover it automatically and can invoke it as $nika-authoring. Same author → check → repair loop, packaged as a skill.

​
Or: install the plugin (Codex · Claude Code)

Codex and Claude Code users can skip per-repo setup entirely — the engine repo hosts one plugin for both ecosystems: 4 skills, 3 subagents, 5 slash commands, the three seatbelt hooks (one dialect, sniffed — Codex speaks Claude Code’s hook contract verbatim) and the 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.
The codex target is shipped (0.93+): 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; the agent session is an illustration.

​
Editor surface

The VS Code / Cursor / Windsurf extension adds check-as-you-type, cost inlay hints, DAG visualization and trace replay on top. See Editors.

Agent authoring protocol

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

Templates

The valid skeletons nika compile --list names.