.gitignore for ndx projects

ndx writes two kinds of files: durable state that belongs in version control, and transient runtime artifacts that don't. This page explains the difference and provides a copy-pasteable snippet you can drop into any project.

Reference template

A ready-to-use template file lives at packages/core/assistant-assets/ndx.gitignore in the ndx repo. Copy its contents into your project's .gitignore.

What to commit vs. what to ignore

Path	Commit?	Why
.rex/prd_tree/	✅ Always	Canonical PRD storage — slug-named folder tree, one index.md per item
.rex/config.json	✅	Project-level rex configuration
.hench/config.json	✅	Agent configuration (model, max turns, guard policy)
CLAUDE.md / AGENTS.md	✅	Assistant instruction files generated by ndx init
.n-dx.json	⚠️ Optional	Project config overrides; safe to commit if it contains no secrets
.sourcevision/	⚠️ Optional	Analysis output — regenerated by ndx analyze. Commit it so teammates skip a re-analysis pass; gitignore it if you prefer to regenerate locally
.codex/config.toml	⚠️ Optional	MCP server definitions for Codex; commit if your team uses Codex
Everything else listed below	❌	Ephemeral runtime artifacts, caches, locks, personal settings

Rule of thumb: algorithmic outputs and shared config belong in version control; runtime artifacts, caches, locks, and per-developer settings don't.

Copy-pasteable snippet

Add this block to your project's .gitignore:

# n-dx — runtime artifacts and ephemeral state
# Keep: .rex/prd_tree/ .rex/config.json .hench/config.json CLAUDE.md AGENTS.md
# Optional: .sourcevision/ (shared analysis baseline) .n-dx.json (project config)

# Analysis output (regenerated by `ndx analyze`)
.sourcevision/

# Agent runs, locks, and session state
.hench/runs/
.hench/locks/
.hench-commit-msg.txt

# Rex ephemeral state
.rex/.backups/
.rex/.cache/
.rex/prd.json.lock
.rex/pending-proposals.json
.rex/acknowledged-findings.json
.rex/execution-log*.jsonl
.rex/adapters.json
.rex/n-dx_workflow.md

# Server runtime
.n-dx-web.pid
.n-dx-web.port

# Run logs
.run-logs/

# Local config overrides (may contain secrets or API keys)
.n-dx.local.json
*.local.json

# Assistant local settings (personal, not shared)
.claude/settings.local.json

If you want to commit .sourcevision/ as a shared analysis baseline, remove that line from the snippet.

Why each path is transient

Pattern	What it contains	Why ignore
.sourcevision/	File inventory, import graph, zone data, findings	Fully regenerated by ndx analyze; large binary-adjacent JSON files create noisy diffs
.hench/runs/	LLM conversation transcripts, tool call logs	Per-run artifacts; large, not useful to teammates
.hench/locks/	Concurrency lock files	Transient; leftover locks cause hench to stall
.hench-commit-msg.txt	Proposed commit message from last agent run	Temporary scratch file
.rex/.backups/	Timestamped snapshots of prd_tree before reshape/add	Safety net only; 10 most-recent retained automatically
.rex/.cache/	prd.json derived from the folder tree (web server only)	Ephemeral; regenerated on ndx start
.rex/prd.json.lock	File lock for JSON cache writes	Transient
.rex/pending-proposals.json	Unreviewed proposals from ndx plan	Per-session interactive state
.rex/acknowledged-findings.json	Findings you've chosen to suppress	Personal triage notes; per-developer
.rex/execution-log*.jsonl	Append-only structured activity log	Grows unboundedly; not useful in git
.rex/adapters.json	Remote sync adapter state	Local-only integration state
.rex/n-dx_workflow.md	Human-readable workflow state snapshot	Derived display artifact
.n-dx-web.pid / .n-dx-web.port	Web server PID and port files	Auto-managed by ndx start/stop
.run-logs/	External run log output	CI/debug artifacts
*.local.json	Local environment overrides	May contain API keys or personal paths
.claude/settings.local.json	Claude Code permission overrides	Personal MCP approvals — not shared

Related guides

• Existing Project Onboarding — full onboarding flow that shows when to add the .gitignore block (Step 4, before any ndx commit)
• PRD Storage Layout — why .rex/prd_tree/ is the only ndx directory that always belongs in git
• Getting Started — initialize ndx and configure your LLM
• Skills Reference — the skill files ndx init writes to .claude/skills/ and .agents/skills/ (committed to version control)