Every query is routed to the cheapest tier that can answer it:

 ┌──────────────────────────────────────────────────────────────┐
 │  TIER 0 — Cache hit        $0.000    exact match in 0.2ms    │
 │  TIER 1 — Deterministic    $0.000    graph traversal, no LLM │
 │  TIER 2 — Embedding        ~$0.00001 local BAAI model        │
 │  TIER 3 — LLM Subgraph     ~$0.0001  LLM on 2-hop graph      │
 └──────────────────────────────────────────────────────────────┘
         ↑ 70–82% of queries never reach Tier 3.

# 1. Install the Python package
pip install pruvalex-pruvagraph

# 2. Build the graph for your project
cd /your/project
pruvagraph .

# 3. Wire to your AI agent
pruvagraph install --claude   # Claude Code
pruvagraph install --cursor   # Cursor
pruvagraph install --vscode   # VS Code Copilot

code --install-extension pruvalex-pruvagraph-1.9.1.vsix

Ctrl+Shift+X  →  Search "PRUVALEX PruvaGraph"  →  Install

code --install-extension pruvalex.pruvagraph

pip install pruvalex-pruvagraph    # stable release
# or
pip install -e ./python            # from source

pruvagraph --help

# Build
pruvagraph .                       # full build, current dir
pruvagraph . --update              # incremental — changed files only
pruvagraph . --backend gemini      # extract docs with Gemini (cheap)
pruvagraph . --backend none        # code-only, zero API calls (default)
pruvagraph . --dry-run             # cost estimate, no API calls, no build

# Query
pruvagraph query "how does auth connect to the DB?"
pruvagraph query "top 5 god nodes in this repo"

# IDE wiring
pruvagraph install --claude        # Claude Code (CLAUDE.md + .mcp.json)
pruvagraph install --cursor        # Cursor (.cursor/mcp.json)
pruvagraph install --vscode        # VS Code (.vscode/mcp.json)
pruvagraph install                 # all three at once

# Export & reports
pruvagraph cost-report             # last build's cost analytics
pruvagraph benchmark-suite --root .  # run the truth machine (84 questions)
pruvagraph export --format html    # open interactive visualizer
pruvagraph export --format graphml # yEd / Gephi import
pruvagraph export --format cypher  # Neo4j import
pruvagraph export --format obsidian # Obsidian vault

# Automation
pruvagraph watch .                 # auto-rebuild on file save
pruvagraph hook install            # git commit hook → auto-update

  analyze_impact      What breaks if I delete AuthMiddleware?
  check_budget        Current session token spend vs. cap
  cost_report         How much did last build save?
  create_checkpoint   Save agent progress with git SHA
  find_callers        Who calls process_payment()?
  get_active_context  What's been injected into agent context?
  get_applicable_rules  Rules for the open file (AST-detected layer)
  get_dependencies    What does pipeline.py import?
  get_graph_diff      What changed in the graph since yesterday?
  get_summary         One-line summary of UserService
  get_task_progress   Checkpoint DAG for a task
  learn_from_accept   Record an accepted suggestion as a learned rule
  list_checkpoints    All checkpoints for a task
  list_communities    What are the architectural clusters?
  list_packages       All top-level packages in this graph
  measure_token_usage Token count of current context window
  query_graph         How does payment processing connect to auth?
  recall              Retrieve stored facts by key
  remember            Store a fact/decision in the context store
  rollback_to_checkpoint  Revert to a previous checkpoint state
  scan_suggestion     Pre-validate a code suggestion before applying
  trace_last_tool_calls  Recent tool call trace
  validate_import     Does this import actually exist in the graph?

// settings.json — toggle individually
{
  "pruvagraph.modules.driftguard.enabled": true,
  "pruvagraph.modules.contextlens.enabled": true,
  "pruvagraph.modules.taskweaver.enabled": true,
  "pruvagraph.modules.budgetgovernor.enabled": true,
  "pruvagraph.modules.rulesforge.enabled": true
}

# Reproduce on your own repo
pruvagraph benchmark-suite --root /path/to/your/project
# → pruvagraph-out/benchmark_results.jsonl

# Run all 508 tests from repo root
python -m pytest python/tests/ -q && npm test

Default mode (--backend none):
  ✓ No API keys required
  ✓ No code sent externally — ever
  ✓ Graph JSON stays in pruvagraph-out/ on your machine
  ✓ MCP server runs as a local subprocess — no network ports

Optional LLM extraction (--backend gemini / claude / openai):
  → Only docstrings and summaries are sent, not raw code
  → Only if you explicitly set a backend and API key
  → Explicitly opt-in, never on by default

├── extension.js              # VS Code entry point (~130 lines)
├── src/
│   ├── commands.js           # 15 command handlers
│   ├── sidebar-provider.js   # Sidebar webview provider
│   ├── sidebar-html.js       # Full sidebar HTML/CSS/JS template
│   ├── dashboard.js          # 4-tab Analytics dashboard
│   ├── driftguard.js         # On-save import validation
│   ├── cli-runner.js         # CLI spawning + cost reporting
│   ├── utils.js              # Shared helpers
│   └── telemetry.js          # Opt-in local telemetry (zero network)
├── dist/extension.js         # esbuild production bundle (70 KB)
├── python/
│   └── pruvagraph/
│       ├── mcp_server.py     # 23-tool MCP server (stdio transport)
│       ├── cli.py            # pruvagraph . entry point
│       ├── pipeline.py       # 5-stage build pipeline
│       ├── benchmark_harness.py  # 84-question truth machine
│       ├── driftguard.py     # Import/type validation
│       ├── context_lens.py   # Context tracking
│       ├── task_weaver.py    # Checkpoint DAG
│       ├── budget_governor.py # Token budget
│       └── rules_forge.py   # AST-aware coding rules
└── python/tests/             # 460 Python tests (0 failures)

git clone https://github.com/PRUVALEX-Systems/pruvagraph
cd pruvagraph/python
pip install -e ".[dev]"
python -m pytest tests/ -q       # 460 tests must pass
npm install && npm test           # 48 JS tests must pass