AI Coding Agent Orchestrator — loops until done.
Give it a spec. It writes tests, implements code, verifies quality, and retries until everything passes.
nax is an orchestrator, not an agent — it doesn't write code itself. It drives whatever coding agent you choose through a disciplined loop until your tests pass.
- Agent-agnostic — use Claude Code, Codex, Gemini CLI, or any ACP-compatible agent
- TDD-enforced — acceptance tests must fail before implementation starts
- Loop until done — verify, retry, escalate, and regression-check automatically
- Monorepo-ready — per-package config and per-story working directories
- Extensible — plugin system for routing, review, reporting, and post-run actions
- Language-aware — auto-detects Go, Rust, Python, TypeScript from manifest files; adapts commands, test structure, and mocking patterns per language
- Semantic review — LLM-based behavioral review against story acceptance criteria; catches stubs, placeholders, and out-of-scope changes
npm install -g @nathapp/nax
# or
bun install -g @nathapp/naxRequires: Node 18+ or Bun 1.0+. Git must be initialized.
cd your-project
nax init # Create .nax/ structure
nax features create my-feature # Scaffold a feature
# Write your spec, then plan + run
nax plan -f my-feature --from spec.md
nax run -f my-feature
# Or in one shot (no interactive Q&A)
nax run -f my-feature --plan --from spec.mdSee docs/ for full guides on configuration, test strategies, monorepo setup, and more.
(plan →) acceptance setup → route → execute → verify → review → escalate → loop → regression gate → acceptance
- Plan (optional) — Generate
prd.jsonfrom a spec file using an LLM - Acceptance setup — Generate acceptance tests; assert RED before implementation
- Route — Classify story complexity and select model tier (fast → balanced → powerful)
- Context — Gather relevant code, tests, and project standards per story
- Execute — Run agent session (Claude Code, Codex, Gemini CLI, or ACP)
- Verify — Run scoped tests; rectify on failure before escalating
- Review — Run lint + typecheck; autofix before escalating
- Escalate — On repeated failure, retry with a higher model tier
- Loop — Repeat steps 3–8 per story until all pass or a cost/iteration limit is hit
- Regression gate — Run full test suite after all stories pass
- Acceptance — Run acceptance tests against the completed feature
| Command | Description |
|---|---|
nax init |
Initialize nax in your project |
nax features create |
Scaffold a new feature directory |
nax features list |
List all features and story status |
nax plan |
Generate prd.json from a spec file |
nax run |
Execute the orchestration loop |
nax precheck |
Validate project readiness |
nax status |
Show live run progress |
nax logs |
Stream or query run logs |
nax diagnose |
Analyze failures, suggest fixes |
nax generate |
Generate .nax/ files for all packages in a monorepo |
nax prompts |
Print prompt snapshots for debugging |
nax runs |
List recorded run metadata |
nax config |
Show/validate configuration |
For full flag details, see the CLI Reference.
.nax/config.json is the project-level config. Key fields:
{
"execution": {
"testStrategy": "three-session-tdd", // How to write tests (see Test Strategies)
"maxIterations": 5,
"modelTier": "balanced", // "fast" | "balanced" | "powerful"
"permissionProfile": "unrestricted" // "unrestricted" | "safe" | "scoped"
},
"quality": {
"commands": {
"test": "bun test", // Root test command
"lint": "bun lint", // Optional linter
"typecheck": "bun typecheck" // Optional type checker
}
},
"hooks": {
"onComplete": "npm run build" // Fire after a feature completes
}
}See Configuration Guide for the full schema.
nax supports four TDD strategies. Select per-feature in config.json:
| Strategy | Sessions | When to use |
|---|---|---|
three-session-tdd |
3 | Strict TDD — red/green/refactor in separate sessions |
three-session-tdd-lite |
3 | Flexible TDD — test-writer may add minimal stubs |
tdd-simple |
1 | Simple changes — single session, implementer writes tests |
test-after |
1 | Legacy / exploratory — implement first, add tests after |
no-test |
0 | Config-only, docs, CI, dependency bumps — requires justification |
See Test Strategies Guide for details.
Stories over a complexity threshold are auto-decomposed into smaller sub-stories. Triggered by story size or prd.json analysis. Sub-stories run sequentially within the feature.
See Story Decomposition Guide.
After all stories pass, nax runs the full test suite once. If it fails, it retries failed suites with a shorter timeout. If still failing after retries, the feature is marked as needing attention — nax does not block on a full-suite failure.
Stories are batched by compatibility (same model tier, similar complexity) and run in parallel within each batch. Use --parallel <n> to control concurrency. Sequential mode uses a deferred regression gate; parallel mode always runs regression at the end.
Per-package context files, per-package test commands, and per-story working directories are supported. Initialize with nax init --package packages/api. Package config files live at .nax/mono/packages/<pkg>/config.json.
See Monorepo Guide.
Lifecycle hooks fire at key points (onFeatureStart, onAllStoriesComplete, onComplete, onFinalRegressionFail). Use them to trigger deployments, send notifications, or integrate with external systems.
See Hooks Guide.
Extensible plugin architecture for prompt optimization, custom routing, code review, and reporting. Plugins live in .nax/plugins/ (project) or ~/.nax/plugins/ (global). Post-run action plugins (e.g. auto-PR creation) can implement IPostRunAction for results-aware post-completion workflows.
See Plugins Guide.
nax supports multiple agent backends:
| Agent | Protocol | Notes |
|---|---|---|
| ACP (recommended) | ACP | Works with Claude Code, Codex, Gemini CLI, and more. Supports multi-turn continuity |
| Claude Code | CLI | Direct claude invocation. --agent claude |
| Codex | CLI | opencode / Codex CLI. --agent opencode |
| Gemini CLI | CLI | --agent gemini |
| OpenCode | CLI | --agent opencode |
ACP is recommended — it provides structured JSON-RPC communication, token-cost tracking, and multi-session continuity.
See Agents Guide.
| Problem | Solution |
|---|---|
| "Working tree is dirty" | Commit or stash changes; nax will restore your working tree after the run |
| HOME env warning | Set HOME to an absolute path — nax warns if it contains ~ |
| ACP sessions leaking | Upgrade to nax v0.48+ and ensure .nax/acp-sessions.json is gitignored |
| Monorepo packages misclassified | Ensure .nax/mono/packages/<pkg>/config.json is set up per package |
| Acceptance tests regenerating every run | Check acceptance-meta.json — stale fingerprints indicate outdated story context |
See the Troubleshooting Guide for more.
nax is inspired by Relentless — the same "keep trying until done" philosophy, applied to AI agent orchestration.
ACP support is powered by acpx from the OpenClaw project.
MIT