NavGator

Architecture Connection Tracker for Claude Code and Codex

Know your stack before you change it

NavGator tracks architecture connections across your entire stack—packages, services, databases, queues, and infrastructure—so your coding agent knows what else needs to change when you modify one part of the system.

Features

• Component Detection: Packages (npm, pip), frameworks, databases, queues, infrastructure
• Connection Mapping: API → Database, Frontend → API, Queue → Handler, Service calls
• Impact Analysis: "What's affected if I change X?"
• Change Detection: SHA-256 file hashing tracks what changed since last scan
• Mermaid Diagrams: Visual architecture diagrams
• Claude Code Integration: Hooks, skills, agents, and slash commands
• Codex Integration: Skills, MCP tools, and native marketplace metadata

Installation

As a CLI Tool

# Install globally
npm install -g @tyroneross/navgator

# Or use with npx
npx @tyroneross/navgator scan

As a Claude Code Plugin

Install the Claude surface directly from this repo:

# Install for all projects (user scope)
bash scripts/install-plugin.sh --global

# Install for current project only
bash scripts/install-plugin.sh --project

Or link manually:

ln -s $(npm root -g)/@tyroneross/navgator ~/.claude/plugins/navgator

Restart Claude Code after installing. All /navgator:* commands will be available.

As a Codex Plugin

Install the Codex surface directly from this repo:

# Install for your Codex user account
bash scripts/install-codex-plugin.sh --user

# Or refresh repo-local workspace metadata only
bash scripts/install-codex-plugin.sh --workspace

This repo now includes native Codex metadata in:

• .codex-plugin/plugin.json
• .agents/plugins/marketplace.json

Claude remains the authoritative host for slash commands and agent wiring. Hooks are disabled by default. Codex uses the additive plugin surface for skills and MCP tools.

Quick Start

1. Set Up NavGator

navgator setup

This runs the initial scan and then you can install the Claude or Codex surface explicitly from the scripts above.

2. Scan Your Project

# Full scan (packages + connections)
navgator scan

# Quick scan (packages only, faster)
navgator scan --quick

# With AI prompt detection
navgator scan --prompts --verbose

# With infrastructure analysis
navgator scan --field-usage --typespec

3. Check Status

navgator status

Output:

NavGator - Architecture Status

========================================
Last scan: 1/26/2026, 12:44:09 PM (0h ago)
Total components: 15
Total connections: 23

COMPONENTS BY TYPE:
  npm: 8
  service: 4
  database: 2
  infra: 1

CONNECTIONS BY TYPE:
  service-call: 12
  api-calls-db: 8
  frontend-calls-api: 3

INFRASTRUCTURE:
  DB models: 12
  Env vars: 34
  Queues: 3
  Cron jobs: 2

4. Analyze Impact

Before changing a component, see what's affected:

navgator impact "Stripe"

Output:

NavGator - Impact Analysis: Stripe

========================================
Component: Stripe
Type: service
Layer: external
Purpose: Stripe payments

INCOMING CONNECTIONS (3):
These files/components USE this component:

  src/api/payments.ts:45
    Symbol: createPaymentIntent (function)
    Code: await stripe.paymentIntents.create({...})

  src/api/subscriptions.ts:23
    Symbol: createSubscription (function)
    Code: await stripe.subscriptions.create({...})

  src/webhooks/stripe.ts:12
    Symbol: handleWebhook (function)
    Code: stripe.webhooks.constructEvent(...)

========================================
Files that may need changes if you modify Stripe:
  - src/api/payments.ts
  - src/api/subscriptions.ts
  - src/webhooks/stripe.ts

5. View Connections

# All connections for a component
navgator connections "BullMQ"

# Only incoming connections
navgator connections "users" --incoming

# Only outgoing connections
navgator connections "users" --outgoing

6. Generate Diagrams

# Full architecture diagram
navgator diagram

# Summary (top connected components only)
navgator diagram --summary

# Focus on specific component
navgator diagram --focus "Stripe"

# Specific layer
navgator diagram --layer backend

# Save to file
navgator diagram --output architecture.md --markdown

Claude Code Slash Commands

When installed as a Claude Code plugin, all commands are available as /navgator:* slash commands:

| Command | Description | |---------|-------------| | /navgator:map | Map full architecture — components, connections, runtime topology, and LLM use cases | | /navgator:plan "<intent>" | Plan an architecture change or investigation. Delegates to the architecture-planner agent, which checks graph freshness, runs an incremental scan if stale, then dispatches the right read-only NavGator tools and aggregates findings | | /navgator:scan | Quick scan — refresh tracking data | | /navgator:trace <component> | Trace data flow through the system | | /navgator:impact <component> | Analyze what's affected by a change | | /navgator:test [instructions] | Run an end-to-end architecture test | | /navgator:review | Architectural integrity review (connections, flow, drift, lessons) | | /navgator:review --all | Review entire architecture, not just changes | | /navgator:review --validate | Validate lessons against current docs (internet research) | | /navgator:review learn "..." | Record a manual architectural lesson | | /navgator:llm-map | Map LLM use cases by purpose and provider | | /navgator:schema [model] | Show database readers and writers | | /navgator:dead | Find orphaned components and dead code | | /navgator:lessons | Manage project and global architecture lessons |

Hooks

NavGator does not enable automatic Claude Code hooks by default. Run /navgator:scan or the MCP scan tool explicitly when architecture data needs to be refreshed.

CLI Reference

navgator scan

Scan project and update architecture tracking.

| Option | Description | |--------|-------------| | -q, --quick | Packages only, skip code analysis | | -c, --connections | Focus on connection detection | | -p, --prompts | Enhanced AI prompt scanning with full content | | -v, --verbose | Detailed output | | --auto | Auto-pick scan mode (default — see Scan modes below) | | --full | Force a full scan (clear all and rebuild) | | --incremental | Force an incremental scan (walk only changed files + reverse-deps) | | --clear | Alias for --full (legacy) | | --ast | Use AST-based scanning (requires ts-morph) | | --field-usage | Analyze Prisma model field usage across codebase | | --typespec | Validate Prisma types against TypeScript interfaces | | --track-branch | Capture git branch/commit in scan output | | --json | Output scan results as JSON | | --agent | Wrap output in agent envelope (implies --json) |

Scan modes

NavGator supports three scan modes. By default (--auto), the scanner picks one based on what changed since the last scan and how stale the cached graph is.

| Mode | When it runs | Behavior | |------|--------------|----------| | full | first scan, or any of: --full/--clear, manifest or build-config changed (e.g. package.json, prisma/schema.prisma, tsconfig.json, vercel.json, fly.toml, railway.json, .gitignore), a new source file was added, last_full_scan > 7 days ago, or incrementals_since_full ≥ 20 | Clears .navgator/architecture/ and rebuilds the entire graph | | incremental | a code file changed and none of the full-scan triggers fire | Walks only changed files plus their reverse-dependencies, merges results into the existing graph by stable_id, runs an integrity check | | noop | nothing changed since the last scan | Updates last_scan, writes a noop timeline entry, leaves the graph untouched |

If an incremental scan fails its integrity check, NavGator automatically promotes it to a full scan and records scan_type: 'incremental→full' in the timeline. Atomic file writes ensure that a crashed scan leaves the prior .navgator/architecture/ intact.

The mode used for any given scan appears in .navgator/architecture/timeline.json under scan_type.

Audit (Run 2 — SQC self-measurement)

After every scan, NavGator runs a statistical-quality-control audit on its own output. The audit samples a fraction of the just-stored components and connections, runs five deterministic verifiers, optionally requests an LLM-judge spot-check, and tracks defect-rate drift across runs via an EWMA control chart. Audit failures never fail the scan — they only update per-stratum EWMA state. The next scan auto-promotes to a tighter inspection if any stratum breaches its control limits.

| Plan | When picked | What it does | |------|-------------|--------------| | AQL (default) | first three audits, or via --audit-plan=aql | MIL-STD-105E single-sampling table at AQL=2.5%. Sample size scales with population (e.g. n=80 c=5 for ~1k facts). | | SPRT | history ≥ 3 audits | Wald 1945 sequential probability ratio test with α=β=0.05, p₀=1%, p₁=5%. Continues sampling until logLR escapes the bounds A=19 / B=0.0526. | | Cochran | prior run breached EWMA, or --audit-plan=cochran | Cochran's formula with FPC at 95% CI, ±5% margin. Tightest inspection. |

Six defect classes:

| Class | Verifier | LLM? | |-------|----------|------| | HALLUCINATED_COMPONENT | filesystem + symbol existence on source.config_files | no | | HALLUCINATED_EDGE | both endpoint component_ids resolve in graph | no | | WRONG_ENDPOINT | grep target name/symbol in connection's source file | no | | STALE_REFERENCE | re-hash file vs hashes.json | no | | DEDUP_COLLISION | scan all components for duplicate (type, name, primary-config) triples (regression check on Run 1.7 fix) | no | | MISSED_EDGE | "list all outgoing edges, set-diff against graph" — emits a structured payload an MCP-side LLM judge can consume | yes (CLI-mode skips) |

In CLI mode the LLM-judge verifier is skipped and audit.llm_skipped: true is set. In MCP mode the audit emits a structured payload (audit.defect_evidence carries up to 20 sample failures) for the running model.

Per-stratum strata: package, infra, connection-imports, connection-services, connection-llm, connection-prisma, __other. Stratified sample selection uses Neyman optimal allocation (more samples → higher-variance strata).

EWMA control chart (Hawkins-Wu defaults λ=0.2, L=2.7) tracks defect-rate drift per stratum across runs. On breach, pending_drift_breach is set on the index, and the next --auto scan promotes to mode='full' + audit-plan='cochran'.

Flags:

| Flag | Purpose | |------|---------| | --no-audit | Skip the audit pass entirely | | --audit-plan <plan> | Override plan auto-pick: aql | sprt | cochran |

Audit output appears on the timeline entry under audit:

{
  "plan": "AQL",
  "n": 80, "c": 5, "sampled": 156, "defects": 0,
  "defect_rate": 0,
  "by_class": { "HALLUCINATED_COMPONENT": { "sampled": 40, "defects": 0 }, ... },
  "by_stratum": { "package": { "sampled": 18, "defects": 0, "defect_rate": 0 }, ... },
  "verdict": "accept",
  "llm_skipped": true
}

navgator status

Show architecture summary.

| Option | Description | |--------|-------------| | --json | Output as JSON |

navgator impact <component>

Show what's affected by changing a component.

| Option | Description | |--------|-------------| | --json | Output as JSON |

navgator connections <component>

Show all connections for a component.

| Option | Description | |--------|-------------| | --incoming | Only incoming connections | | --outgoing | Only outgoing connections | | --json | Output as JSON |

navgator list

List all tracked components.

| Option | Description | |--------|-------------| | -t, --type <type> | Filter by type (npm, service, database, etc.) | | -l, --layer <layer> | Filter by layer (frontend, backend, etc.) | | --json | Output as JSON |

navgator diagram

Generate Mermaid architecture diagram.

| Option | Description | |--------|-------------| | -f, --focus <component> | Center on specific component | | -l, --layer <layer> | Show specific layer only | | -s, --summary | Top connected components only | | -d, --direction <dir> | TB, BT, LR, or RL (default: TB) | | --no-styles | Disable color styling | | --no-labels | Hide connection labels | | -o, --output <file> | Save to file | | -m, --max-nodes <n> | Max nodes to show (default: 50) | | --markdown | Wrap in markdown code block |

navgator prompts

Scan and analyze AI prompts in the codebase.

| Option | Description | |--------|-------------| | -v, --verbose | Show full prompt content | | --json | Output as JSON | | --detail <name> | Show detailed view of specific prompt |

navgator coverage

Analyze database field usage and type alignment.

# Field usage analysis (requires Prisma schema)
navgator coverage --fields

# TypeSpec validation (Prisma vs TypeScript types)
navgator coverage --typespec

| Option | Description | |--------|-------------| | --fields | Report unused, read-only, and write-only Prisma model fields | | --typespec | Compare Prisma model types against TypeScript interface definitions | | --json | Output as JSON |

navgator trace <component>

Trace dataflow paths forward and backward through the system.

| Option | Description | |--------|-------------| | --direction <dir> | forward, backward, or both (default: both) | | --depth <n> | Max trace depth (default: 5) | | --json | Output as JSON |

navgator rules

Check architecture rules and report violations.

| Option | Description | |--------|-------------| | --json | Output as JSON |

Built-in rules: orphan components, database isolation, frontend-direct-db, circular dependencies, hotspot modules, high fan-out, layer violations.

navgator subgraph <component>

Extract a focused subgraph around a specific component.

| Option | Description | |--------|-------------| | --depth <n> | Include connections up to N hops away (default: 2) | | --json | Output as JSON |

What Gets Detected

Components

| Type | Examples | |------|----------| | Packages | npm, pip, cargo, go, gem, composer | | Frameworks | Next.js, React, Django, FastAPI, Express | | Databases | PostgreSQL, MongoDB, Redis, Supabase, Prisma | | Queues | BullMQ, Celery, SQS, RabbitMQ | | Infrastructure | Railway, Vercel, Docker, Kubernetes, GitHub Actions | | Services | Stripe, OpenAI, Anthropic, Twilio, SendGrid, AWS S3 | | AI Prompts | Claude/OpenAI prompts with full content, variables, purpose |

Connections

| Type | Description | |------|-------------| | service-call | Code → External service (Stripe, OpenAI, etc.) | | api-calls-db | API endpoint → Database table | | frontend-calls-api | Frontend component → API endpoint | | queue-triggers | Queue job → Handler function | | prompt-location | AI prompt definition location | | prompt-usage | Code that uses an AI prompt | | env-dependency | Component → environment variable it depends on | | schema-relation | Database model → related model (FK/relation) | | cron-triggers | Cron job → API route handler | | queue-produces | Producer → queue | | queue-consumes | Queue → consumer worker | | field-reference | Database model field → file that references it | | runtime-binding | Component → its runtime service/resource | | queue-uses-cache | Queue system → Redis/cache instance |

Runtime Topology

NavGator annotates architecture components with runtime identity information extracted from code and config:

• Database connections: Parses DATABASE_URL and Prisma datasource to identify database engine (postgres, mysql, etc.), host, and port
• Redis/cache connections: Extracts Redis URLs from BullMQ queue configurations and env vars
• Queue identity: Maps queue names to their Redis backing store and producer/consumer relationships
• Deploy services: Extracts service names from Railway, Vercel, Heroku (Procfile), and Nixpacks configs
• Cron handlers: Links scheduled jobs to their handler functions and deployment platform

Use navgator status to see the RUNTIME TOPOLOGY section showing all detected runtime bindings.

Storage

Data is stored in .navgator/architecture/ within your project:

.navgator/architecture/
├── NAVSUMMARY.md           ← Hot context (read first)
├── NAVSUMMARY_FULL.md      ← Full version if compressed
├── components/           # Individual component JSON files
│   ├── COMP_npm_react_a1b2.json
│   └── COMP_service_stripe_c3d4.json
├── connections/          # Connection records
│   └── CONN_service_call_e5f6.json
├── index.json           # Quick lookup index
├── graph.json           # Full connection graph
├── file_map.json        # File path → component ID lookup
├── prompts.json         # AI prompt content + associations
├── hashes.json          # File hashes for change detection
└── snapshots/           # Point-in-time backups

AI Prompt Tracking

NavGator includes comprehensive AI prompt detection and tracking. Use --prompts flag or the dedicated prompts command.

What Gets Tracked

| Field | Description | |-------|-------------| | Location | File path, line numbers, containing function | | Content | Full prompt content (up to 2000 chars per message) | | Provider | Anthropic (Claude), OpenAI, Azure, Google | | Variables | Template variables ({var}, {{var}}, ${var}) | | Purpose | Extracted from nearby comments | | Category | summarization, classification, extraction, chat, etc. | | Usage | Where the prompt is called (file, line, function) |

Prompt Categories

NavGator automatically categorizes prompts:

• chat - Conversational prompts
• summarization - Content summarization
• extraction - Data extraction
• classification - Categorization tasks
• code-generation - Writing code
• code-review - Reviewing code
• agent - Tool/function use
• translation - Language translation

AST-Based Scanning

For more accurate connection detection, install ts-morph:

npm install ts-morph

Then use the --ast flag:

navgator scan --ast

AST scanning provides:

• Accurate import tracking
• Method chain following (stripe.customers.create())
• Higher confidence scores

Without ts-morph, NavGator uses regex-based scanning which is faster but may miss some patterns.

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | NAVGATOR_MODE | Storage mode: local or shared | local | | NAVGATOR_PATH | Custom storage path | .navgator/architecture | | NAVGATOR_AUTO_SCAN | Auto-scan on session start | false | | NAVGATOR_HEALTH_CHECK | Enable health checks | false | | NAVGATOR_SCAN_DEPTH | shallow or deep | shallow | | NAVGATOR_CONFIDENCE | Confidence threshold (0-1) | 0.6 | | NAVGATOR_MAX_RESULTS | Max results per query | 20 |

Example Workflows

Adding a New Integration

# 1. Check current architecture
navgator status

# 2. Install package
npm install stripe

# 3. Update architecture
navgator scan --quick

# 4. Implement integration
# ... write code ...

# 5. Full rescan to detect new connections
navgator scan

Before Database Migration

# 1. Check what uses the table
navgator impact "users"

# 2. Review affected files
navgator connections "users" --incoming

# 3. Generate diagram for documentation
navgator diagram --focus "users" --output migration-plan.md --markdown

# 4. Make changes to each affected file
# 5. Rescan to verify
navgator scan

Understanding a New Codebase

# 1. Full scan
navgator scan --verbose

# 2. See overall architecture
navgator diagram --summary

# 3. List all services
navgator list --type service

# 4. Understand a specific component
navgator impact "Supabase"

Dependencies

Required:

• commander - CLI framework
• glob - File pattern matching

Optional:

• ts-morph - AST-based scanning (install separately)

License

MIT

Contributing

Contributions welcome! Please read the contributing guidelines first.

Links

• GitHub Repository
• Issue Tracker
• Claude Code

Codex

This package now ships an additive Codex plugin surface alongside the existing Claude Code package. Claude remains the authoritative runtime for slash commands and agents. Hooks are disabled by default. Codex support is explicit and parallel rather than inferred from the Claude surface.

Package root for Codex installs:

• the repository root (.)

Primary Codex surface:

• manifest: ./.codex-plugin/plugin.json
• workspace marketplace metadata: ./.agents/plugins/marketplace.json
• skills from ./skills
• MCP config from ./.mcp.json

Recommended Codex flows:

# user-wide install
bash scripts/install-codex-plugin.sh --user

# repo-local workspace metadata
bash scripts/install-codex-plugin.sh --workspace

The Codex package is additive only: Claude-specific slash commands and agent wiring remain unchanged for Claude Code.