Nimai Cli

Nimai — a New Idea in Mind, built by AI. Named for the saint born under a neem tree — the tree whose bitterness purifies. This Nimai washes the ambiguity out of your ideas so an agent can build what you actually meant.

Ideas in your head don't come with specs — and without a clearly defined spec, agents can't build your vision. Anyone can ask a model to generate a spec; Nimai grades it: an adversarial review gate, a machine-parseable verdict, and a convergence contract that says, provably, nothing is missing.

---

How it works

Nimai is a protocol your AI host runs, plus the gates that keep it honest:

1. Interview — nimai_spec returns a protocol prompt. Your host model explores the repo with its own tools, then asks you 5–8 questions specific to your idea — the decisions you didn't know you hadn't made.
2. Draft — the host fills a lean spec template (one page for small ideas; the full tier for risky ones).
3. Gate — nimai_validate runs deterministic structural lint. No impurities, no pass.
4. Grade — nimai_review --target spec produces an adversarial reviewer prompt for a fresh session (the drafter never grades its own draft). The verdict is machine-parseable JSON; zero HARD_FAILs or no build.
5. Build elsewhere — the converged spec is the contract you hand to any builder agent.
6. Grade the build — nimai_review --target implementation checks the built thing against the spec's acceptance criteria.

Nimai makes no internal LLM calls and needs no API keys. Your host model does all generation; Nimai supplies the rubric, the state machine, and the verdict contract.

---

Install

npm install -g nimai

Or add the MCP server to your AI host (Claude Code, Codex, Cursor):

npm install -g nimai-mcp

---

Commands

# Scaffold a new spec file from a tier template
nimai new my-feature.md

# Generate the spec protocol prompt (interview → draft → gate)
nimai spec "add JWT authentication" --repo .

# Lint a spec — structural gate
nimai validate my-feature.md

# Generate the adversarial spec reviewer prompt (run it in a fresh session)
nimai review my-feature.md --target spec

# Generate the implementation reviewer prompt (after the build)
nimai review my-feature.md --target implementation

---

MCP Server

Nimai exposes three tools to any MCP-compatible host:

Tool	What it does
nimai_spec	Returns the spec protocol prompt — explore, interview, draft, gate
nimai_validate	Lints a spec — returns impurities and pass/fail
nimai_review	Returns a reviewer prompt — target: "spec" before building, target: "implementation" after

See docs/mcp-setup.md for setup instructions for Claude Code, Codex, Gemini CLI, OpenCode, and Cursor.

---

Spec tiers

Every spec carries a tier marker as its final line:

• <!-- nimai-spec tier=lite --> — one page: Deliverable, Scope, Acceptance Criteria, Mechanism Decisions, Spec Convergence. For small, low-risk ideas.
• <!-- nimai-spec tier=full --> — adds Task Decomposition, Architecture Lock, Change Surface, and Edge Cases. For anything that touches existing code or carries real risk.

Every section in both templates is enforced by a lint rule or a reviewer dimension. If nothing checks it, it isn't in the template.

---

Intent Boundary

Nimai defines and enforces spec-quality contracts; runtime orchestrators (like ChatMasala) execute agent workflows against those contracts; context platforms provide the execution substrate.

Nimai owns: spec structure and template discipline, deterministic lint gates, review/verdict contracts (reviewer prompts + verdict schema). Nimai does not own: runtime orchestration (agent routing, retries, session control, execution loops) or context/code operations.

Once a spec is approved, Nimai's job is done — until the build is finished, when it grades the result.

---

Status

v0.5.0 — protocol-driven rewrite. Spec creation is an interview run by your host model; lint is structural-only; semantic judgment lives in the adversarial review.

• nimai spec — protocol prompt (interview-driven, host-run)
• nimai validate — deterministic structural lint, tier-aware
• nimai review — spec and implementation reviewer prompts
• nimai new — spec scaffolding from tier templates
• MCP server — three tools
• nimai run — execute a spec end-to-end (planned, pending usage data)

---

Packages

Package	Description
nimai-core	Template loader, lint engine, prompt builders, verdict parser — no LLM deps
nimai-mcp	MCP server
nimai	CLI binary

---

License

MIT © Balagopalaji 2026