nervx

A codebase brain for AI coding assistants. Pre-indexed navigation, blast radius analysis, dead code detection, and architectural pattern recognition — all from a single pip install.

Install

pip install nervx

Quick Start

# Build the brain for your project
nervx build .

# Ask questions in natural language
nervx nav "how does authentication work"

# 50-token preview of a symbol — signature, callees, caller count, no source
nervx peek validate_token

# Structural overview of a file — ~150 tokens instead of 4000
nervx tree src/auth.py

# Read a function's source + everything it calls
nervx read validate_token --context 1

# Quick yes/no: does A call B?
nervx ask calls login validate_token

# Confirm a call path with BFS (up to 6 hops)
nervx verify "login calls validate_token"

# Shortest call path between two symbols
nervx trace login validate_token

# Find where a string literal appears across all languages
nervx string-refs "user_id"

# Check blast radius before refactoring
nervx blast-radius validate_token

# Find dead code (framework-aware — skips decorated handlers)
nervx find --dead

# Run pytest with compact output (~80 tokens vs 8000 of traceback)
nervx run pytest tests/

# Open interactive visualization
nervx viz .

Benchmarks

Tested on FastAPI — 3 identical questions asked with and without nervx:

nervx replaces dozens of blind grep/read cycles with pre-indexed lookups. Fewer tool calls, less token waste, faster answers.

What It Does

nervx parses your codebase with tree-sitter, builds a graph of every function, class, and method, then pre-computes:

• Edges: who calls what, who imports what, who inherits from what, and — new in 0.2.2 — which base-class methods dispatch to which concrete overrides (dispatches_to), so trace can follow polymorphic calls that static resolution misses
• Importance scores: weighted per edge type (calls×2, inherits×1.5, imports×0.5) with a 0–100 percentile rank
• Path categories: every node tagged category:{vendor,generated,test,example,doc,script,core} so find/nav/blast-radius can drop noise with --exclude-category — new in 0.2.4, script catches scripts/, ci/, build_scripts/, .github/ paths that otherwise pollute importance rankings
• Architectural patterns: factories, singletons, event buses, strategy patterns, repositories
• Concept paths: end-to-end call chains and domain clusters
• Git intelligence: hotspots, temporal coupling, churn analysis — cochange --why exposes the actual commit hashes behind each coupling
• Contract analysis: callers that disagree on error handling
• Warning provenance: every warning carries its methodology, confidence, and evidence (visible via nav --verbose-warnings or --json)
• Dead code: unreferenced functions and classes

All stored in a single SQLite database (.nervx/brain.db), queryable in milliseconds.

Commands

Build

Exploration

Reading

Quick Answers (5–30 tokens each)

Analysis

Diagnostics

Testing

Visualization & Stats

All output commands support --json for machine-parseable output.

Excluding Files

Create a .nervxignore in the repo root (gitignore syntax) to exclude files from indexing. Defaults already skip __pycache__/, node_modules/, dist/, build/, .venv/, minified bundles, lockfiles, and vendor directories.

Claude Code Integration

When you run nervx build, it automatically adds instructions to your project's CLAUDE.md that teach Claude Code to use nervx commands. Claude will use nervx nav before exploring code, nervx peek/nervx tree instead of reading full files, nervx ask/nervx verify for quick verification, and nervx blast-radius before refactoring — saving tokens and tool calls.

Supported Languages

Python, JavaScript/TypeScript, Java, Go, Rust, C/C++, C#, Ruby

Watch Mode (Optional)

pip install nervx[watch]
nervx watch .

Auto-updates the brain when files change.

Changelog

0.2.6

• Instance-method dispatch — the Python parser now infers a receiver type for sp.verify() style calls by scanning local assignments (sp = SamplingParams()), annotations (sp: SamplingParams), parameter hints, and self.foo = Foo() in __init__. The linker uses the hint to pick the correct class when a method name is shared. When a receiver type is unknown, the linker fans out to every plausible candidate and marks the edge with confidence="low" so coverage and caller counts still see the call. Strict consumers (ask calls, verify, trace) filter out the low-confidence edges.
• Full import index — every import/use/using/require now persists to a new raw_imports table, including external modules (numpy, torch, std, java.util.List, System.Text, ...). ask imports <file> returns the full picture instead of only intra-project resolutions.
• nervx uses <identifier> — new command. Scans source lines for bare-token occurrences of an identifier (attribute access, assignments, type hints, destructuring, match arms). Complements string-refs, which remains the quoted-literal-only lookup.

0.2.5

• Scale-invariant fuzzy symbol resolution and coverage-tier navigation ranking — consistent behavior from 50-file prototypes to 50k-file monorepos.

License

MIT