Getting Started

Prerequisites

• Node.js ≥ 22 (22 LTS) — nodejs.org
• pnpm ≥ 10 — pnpm.io/installation

Installation

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

One-off use without installing

npx -p @n-dx/core ndx init .

Use the -p @n-dx/core ndx form. Bare npx @n-dx/core does not work — the binary is named ndx, which differs from the package name, so npx cannot pick it automatically.

After installing, ndx (or n-dx) is available as the primary command. See the Quickstart for a 5-minute walkthrough. To build from source (contributors only), see Contributing. The install paths above were validated end-to-end — see Install Path Validation.

Initialize a Project

ndx init .

This creates .sourcevision/, .rex/, and .hench/ directories in the target project — plus assistant-specific artifacts for Claude and Codex. See Assistant Surfaces below for details on what is generated for each assistant.

Selecting Assistants

By default, ndx init provisions both Claude and Codex surfaces. Use flags to control which assistants are set up:

ndx init .                       # both Claude and Codex (default)
ndx init --claude-only .         # only Claude surfaces
ndx init --codex-only .          # only Codex surfaces
ndx init --assistants=claude .   # equivalent to --claude-only
ndx init --no-codex .            # skip Codex provisioning

Re-init is safe

Running ndx init again detects existing assistant surfaces and reuses them. If only Claude artifacts exist, re-init skips Codex (and vice versa) unless you explicitly pass an assistant flag.

Add .gitignore entries before your first commit

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

Configure Your LLM

Claude (recommended)

ndx config llm.vendor claude .

# API mode (recommended — best token accounting and reliability)
ndx config llm.claude.api_key sk-ant-... .
# or set the environment variable:
export ANTHROPIC_API_KEY=sk-ant-...

# Optionally pin a model (default: claude-sonnet-5-5)
ndx config llm.claude.model claude-opus-5-5 .

# CLI mode (no API key required)
ndx config llm.claude.cli_path claude .
claude login

Codex

ndx config llm.vendor codex .
ndx config llm.codex.cli_path codex .
codex login

Assistant Surfaces

ndx init generates assistant-specific artifacts so that each AI coding assistant can discover your project's workflow, skills, and MCP servers. Both assistants share the same underlying skills and MCP tools — the only difference is the file format each assistant expects.

Claude

Artifact	Path	Purpose
Instructions	CLAUDE.md	Project guidance, architecture docs, workflow rules
Skills	.claude/skills/{name}/SKILL.md	Slash-command skills (YAML frontmatter format)
Settings	.claude/settings.local.json	Auto-approved read-only MCP tool permissions
MCP servers	Tracked .mcp.json (or .codex/config.toml for Codex)	Rex and SourceVision stdio servers

To start working with Claude Code after init:

claude    # open Claude Code — it reads CLAUDE.md automatically

Claude discovers skills from .claude/skills/ and MCP servers from .mcp.json, with tool permissions from .claude/settings.local.json. For HTTP MCP transport — only safe with a single n-dx project running at a time until 0.7.0 — see MCP Integration.

Codex

Artifact	Path	Purpose
Instructions	AGENTS.md	Project guidance, workflow, available skills, MCP server docs
Skills	.agents/skills/{name}/SKILL.md	Task skills (plain markdown format)
MCP config	.codex/config.toml	MCP server definitions (stdio transport)

To start working with Codex after init:

codex     # open Codex — it reads AGENTS.md automatically

Codex discovers MCP servers from .codex/config.toml and skill documentation from AGENTS.md.

Shared Skills

Both assistants receive the same set of workflow skills, rendered in their respective formats:

Skill	Description
ndx-work	Execute PRD tasks with workflow discipline
ndx-plan	Analyze codebase and generate PRD proposals
ndx-status	Show PRD progress and task tree
ndx-capture	Capture ideas and add to PRD
ndx-zone	Explore architectural zones
ndx-config	View and edit project configuration
ndx-reshape	Restructure the PRD tree
ndx-feedback	File a GitHub issue with project context

For descriptions of each skill, trigger conditions, and customization guidance, see the Skills Reference.

Your First Run

# 1. Analyze your codebase
ndx analyze .

# 2. Turn findings into PRD tasks
ndx recommend --accept .

# 3. Execute the next task
ndx work --auto .

# 4. Check progress
ndx status .

That's it. See the Workflow page for the full development loop, or Commands for the complete reference.

Feedback

Found a bug or have a feature idea? Use the /ndx-feedback skill in your assistant to submit it directly:

/ndx-feedback ndx init keeps prompting for provider even though it's already configured

This creates a GitHub issue with your environment details automatically included.