Quickstart

Get from zero to a working PRD in under 5 minutes.

Onboarding an existing repo?

This guide assumes a new or empty project. If you're adding ndx to a codebase that already has real history, see Existing project onboarding — it adds a pre-flight cleanup pass and .gitignore setup.

Prerequisites

• Node.js ≥ 22 (22 LTS)
• pnpm ≥ 10 — install pnpm

1. Install

Recommended: install @n-dx/core globally with npm.

npm install -g @n-dx/core

Other package managers

# pnpm (equivalent; preferred if you already use pnpm)
pnpm add -g @n-dx/core

# yarn (best-effort — not part of our tested path)
yarn global add @n-dx/core

Prefer not to install globally? Run one-off with npx -p @n-dx/core ndx <command> (the -p @n-dx/core ndx form is required — bare npx @n-dx/core does not work).

2. Initialize

Navigate to your project and run:

ndx init

You'll first be asked to choose an LLM provider (Claude or Codex):

Then you'll pick a model for that provider, after which init runs to completion:

The init command sets up everything — analysis metadata, PRD storage, agent configuration, and assistant-specific artifacts:

• Claude: CLAUDE.md, .claude/skills/, .claude/settings.local.json, MCP server registration
• Codex: AGENTS.md, .agents/skills/, .codex/config.toml

By default both surfaces are provisioned. Use --claude-only or --codex-only to limit to one assistant.

Starting from an empty folder?

ndx init offers to run git init for you when the folder is not inside a repository — n-dx records autonomous work as commits, so without one, auto-commit, pair programming, and the hench run loop stay disabled. Answer the prompt, or pass --git / --no-git to answer it ahead of time (required for scripted runs, which have no prompt).

You can also skip the terminal entirely: ndx start in an empty folder serves a setup page with an Initialize project button, which asks the same questions — assistants, LLM provider, and whether to create the git repository — and then opens the dashboard.

Already initialized?

Running ndx init again is safe. It detects existing assistant surfaces and reuses them. If only one assistant's artifacts exist, re-init skips the other unless you explicitly request it.

Set up .gitignore before your first commit

ndx init only gitignores .n-dx.local.json automatically. Before committing anything else, add the recommended ignore patterns so ephemeral runs, caches, and PID files stay out of version control.

3. Add to the PRD

The PRD is your product's requirements (the product layer: areas and capabilities) plus the changes being made to them (the change layer). Everything new enters as a change. See The PRD for the model.

ndx add "<describe what you want to create>"

ndx add creates one change per description in the Inbox, under .ndx/rex/changes/, and prints its id with a suggested placement: the capabilities it could add to, amend or touch. Record the placement with rex change place <change> --target=<node>, or leave it in the Inbox for later. See Changes and apply.

v1 projects

ndx init creates a v2 project. On a v1 project, one that has not yet run ndx migrate, ndx add behaves as these screenshots show: the configured LLM drafts a proposal of epics, features and tasks, and you accept it into .rex/prd_tree/.

accept proposals? (y=all / n=none / b#=break down / c=consolidate / 1,2,…=select)

Press y to accept everything, or pick specific items.

4. Work on the PRD

ndx work --auto

The agent picks the highest-priority pending task, builds a brief with codebase context, runs an LLM tool-use loop to implement it, and records the results.

5. Check progress

See the requirements, each capability with its computed status (proposed, changing, met, revised) and health:

rex product show

v1 projects

A v1 project has no product layer, so rex product show refuses it. Use ndx status, which shows the item tree with completion stats:

ndx status

ndx status reads the v1 layout only; it does not read a v2 PRD yet.

6. Analyze your changes (optional)

Check how your PRD has been implemented:

ndx analyze

Analyze writes only to .sourcevision/ — file inventory, import graph, zones, findings. No PRD changes yet. Then read what it found:

ndx recommend --actionable-only

Skim .sourcevision/CONTEXT.md for the AI-readable summary, and use the recommend output to see what ndx thinks needs work. The goal here is a mental model — you don't need to act on anything yet.

7. Start the dashboard

ndx start

Opens a web dashboard at http://localhost:3117 with interactive views of your codebase analysis, your PRD, and agent runs.

What's next?

• Open your assistant: claude or codex — your assistant reads its instruction file and discovers skills automatically
• Add your own ideas: ndx add "Add SSO support with Google" .
• Run multiple tasks: ndx work --auto --iterations=4 .
• Self-healing loop: ndx self-heal 3 . (analyze → recommend → work, repeated)
• Submit feedback: /ndx-feedback "description" — files a GitHub issue with context
• Assistant surfaces: Getting Started — Assistant Surfaces
• Full command reference: Commands
• Workflow guide: Workflow
• .gitignore setup: .gitignore for ndx projects

Skills installed by ndx init

ndx init writes workflow skills into your assistant's skill directory. They are available as slash commands in your next Claude Code or Codex session:

Skill	Role in this guide
/ndx-work	Step 4: executes PRD tasks with codebase context and workflow discipline
/ndx-status	Step 5: shows PRD progress and codebase health together
/ndx-capture	Step 3 alternative: adds a freeform idea to the PRD without leaving the chat
/ndx-feedback	What's next: files a GitHub issue with your environment details automatically included

For the full skill inventory and customization guidance, see the Skills Reference.