Contextception

Contextception

[](https://github.com/kehoej/contextception/actions/workflows/ci.yml) [](https://pkg.go.dev/github.com/kehoej/contextception) [](https://goreportcard.com/report/github.com/kehoej/contextception) [](LICENSE) [](https://github.com/kehoej/contextception/releases) [](go.mod)

Deterministic context intelligence for code. Answers: "What must be understood before making a safe change?"

Contextception builds a dependency graph of your repository and returns ranked, explainable lists of files you need to read before safely modifying a given file. Static analysis only, no AI generation, no tokens wasted.

---

97% Precision (independent ground truth)  ·  Tested across 16 repos  ·  Sub-second Analysis  ·  6 Languages  ·  Free & Open Source

---

Install

Go install:

go install github.com/kehoej/contextception/cmd/contextception@latest

> Note: go install works out of the box on all platforms. On systems with a C compiler available, TypeScript/JavaScript extraction uses tree-sitter (AST-based) for higher accuracy. Without a C compiler (CGO_ENABLED=0), it falls back to regex-based extraction which handles the vast majority of import patterns correctly.

Homebrew:

brew install kehoej/tap/contextception

Shell script (Linux/macOS):

curl -fsSL https://raw.githubusercontent.com/kehoej/contextception/main/install.sh | sh

Build from source:

git clone https://github.com/kehoej/contextception.git
cd contextception && make build
# Binary at ./bin/contextception

Windows: Download the .zip from GitHub Releases and add to your PATH.

---

How It Works

1. Index your repo

$ contextception index
Indexed 2,638 files, 10,087 edges in 0.9s

Scans your codebase, extracts imports across 6 languages, resolves dependencies, computes git history signals. Incremental: only changed files reprocessed.

2. Analyze any file

$ contextception analyze src/auth/login.py

{
  "schema_version": "3.2",
  "subject": "src/auth/login.py",
  "confidence": 0.92,
  "must_read": [
    { "file": "src/auth/session.py", "symbols": ["createSession"], "direction": "imports", "role": "foundation" },
    { "file": "src/auth/types.py", "symbols": ["User", "AuthConfig"], "direction": "imports", "role": "utility" }
  ],
  "likely_modify": {
    "high": [{ "file": "src/auth/session.py", "signals": ["direct_import"] }]
  },
  "tests": {
    "direct": ["tests/auth/test_login.py"],
    "indirect": ["tests/auth/test_session.py"]
  },
  "blast_radius": {
    "level": "medium",
    "detail": "8 files in dependency subgraph, 3 direct importers",
    "fragility": 0.45
  }
}

Returns ranked context: what to read, what might change, which tests cover it, and the blast radius, with every recommendation explained.

Analyze multiple files at once to get merged context across a feature:

$ contextception analyze src/auth/login.py src/auth/session.py src/auth/types.py

3. Act on the context

Feed the output to your AI agent via MCP, gate PRs with blast radius in CI, or use it to understand unfamiliar code:

# CI: fail PR if blast radius is high
contextception analyze-change --ci --fail-on high

---

Blast Radius Analysis

Every change has a ripple effect. Contextception maps it:

• Critical zone: files that will definitely break
• Warning zone: files needing review
• Fragility score: how unstable the affected subgraph is (0.0–1.0)

---

Hotspot Detection

High churn + high fan-in = architectural risk. Contextception finds these automatically:

Files that change frequently AND are imported by many others are the most dangerous files in your codebase. These are the ones that need the most care, and the most tests.

---

Git History Intelligence

Static analysis shows what can affect a file. Git history shows what actually changes together. Contextception combines both.

During indexing, Contextception analyzes your last 90 days of git history to extract three signals:

• Co-change frequency: files that are frequently modified in the same commits get boosted in rankings, even if they're several hops apart in the dependency graph
• Hidden coupling: files that co-change 3+ times but have no import relationship are surfaced in related with a hidden_coupling:N signal. These represent behavioral coupling invisible to static analysis: shared data formats, API contracts, coordinated changes
• Churn tracking: high-churn files are flagged so you know which dependencies are volatile vs. stable

These signals feed directly into the scoring engine. A file that co-changes frequently with your target is ranked higher than one that merely imports it. A file flagged stable (high fan-in, low churn) tells you it's safe to rely on without deep review.

---

PR & Change Analysis

Analyze an entire PR or commit range to understand its impact before merging:

$ contextception analyze-change origin/main

Returns a PR-level impact report with:

• Per-file risk scoring: every changed file gets a risk score (0–100) and tier (SAFE/REVIEW/TEST/CRITICAL)
• Risk triage: files grouped by tier with human-readable risk narratives explaining why each file is flagged
• Test gaps: changed files with no test coverage, flagged before merge
• Test suggestions: auto-generated recommendations for high-risk untested files (which test file to create, what to test)
• Coupling detection: pairs of changed files that depend on each other
• Hidden coupling: co-change partners not in your diff that may need updating
• Aggregate risk: overall PR risk score with percentile ranking against historical baselines (after 10+ analyses)
• Aggregated must_read: merged context across all changed files

Risk Tiers

| Tier | Score | Meaning | |------|-------|---------| | SAFE | 0–20 | New files, well-tested utilities, low coupling | | REVIEW | 21–50 | Moderate risk, standard code review sufficient | | TEST | 51–75 | High risk, targeted testing recommended | | CRITICAL | 76–100 | Maximum risk, regressions likely without careful review |

Risk scores combine change status, structural factors (importer count, co-change frequency, fragility, mutual dependencies), and test coverage adjustments.

Token-optimized output

Use --compact for a text summary optimized for LLM consumption (~60–75% fewer tokens than JSON):

$ contextception analyze-change --compact

CI integration

Use --ci --fail-on to gate PRs automatically. A risk badge is printed to stderr:

# Fail on high blast radius
contextception analyze-change --ci --fail-on high

# Fail only if risk triage has CRITICAL files
contextception analyze-change --ci --fail-on critical

Results are stored in a local history database, enabling trend tracking with contextception history:

$ contextception history hotspots     # Files that repeatedly appear as hotspots
$ contextception history trend        # Blast radius trend over recent analyses

---

Confidence Scoring

Every analysis includes a confidence score (0.0–1.0) based on import resolution completeness:

If imports can't be resolved (dynamic imports, missing packages), the confidence score tells you how much to trust the results.

---

Performance

| Repository | Files | Index Time | Analysis Time | |-----------|-------|-----------|---------------| | Excalidraw | 602 | 0.3s | Per-repo recall breakdown

| Repository | Files | Contextception | Aider @8192t | Aider @4096t | |-----------|-------|---------------|-------------|-------------| | httpx (Python) | 60 | 97% | 90% | 83% | | Excalidraw (TS) | 602 | 100%\ | 25.3% | 20.0% | | Tokio (Rust) | 1,021 | 100%\ | 1.4% | 1.4% | | Terraform (Go) | 1,885 | 100%\ | 7.9% | 6.3% | | Zulip (Python) | 2,638 | 100%\ | 27.4% | 24.2% | | Spring Boot (Java) | 7,978 | 100%\* | 0% | 0% |

\* Measured against CC's own validated output (Grade A, 3.76–3.97). See [benchmarks/](benchmarks/) for full methodology and reproducible results.

---

MCP Setup (30 seconds)

Make your AI agent smarter. The setup command auto-detects every installed editor and configures all of them:

# Auto-detect: Claude Code, Cursor, Windsurf, opencode, VSCode (Copilot Chat), Warp
contextception setup

# Or target one explicitly
contextception setup --editor cursor
contextception setup --editor opencode
contextception setup --editor vscode
contextception setup --editor warp           # prints manual UI steps (Warp's MCP is UI-configured)

# Also drop the agent instruction snippet into the current project
cd /path/to/your/project
contextception setup --instructions          # upserts CLAUDE.md / AGENTS.md / .cursor/rules/ / .github/copilot-instructions.md

Use --dry-run to preview changes, or --uninstall to reverse. --instructions uses begin/end markers so existing user content in those files is preserved on re-runs and on --uninstall --instructions.

Or configure manually — add to your ~/.claude.json (Claude Code) or equivalent MCP config:

{
  "mcpServers": {
    "contextception": {
      "command": "contextception",
      "args": ["mcp"]
    }
  }
}

This exposes nine tools to the AI agent:

| Tool | Description | |------|-------------| | get_context | Analyze a file's context dependencies (auto-indexes if needed) | | index | Build or update the repository index | | status | Return index diagnostics | | search | Search the index for files by path pattern or symbol name | | get_entrypoints | Return entrypoint and foundation files for project orientation | | get_structure | Return directory structure with file counts and language distribution | | get_archetypes | Detect representative files across architectural layers | | analyze_change | Analyze the impact of a git diff / PR (risk scoring, triage, test gaps, coupling) | | rate_context | Rate how useful a previous get_context result was (feedback for accuracy tracking) |

Works with Claude Code, Cursor, Windsurf, and any MCP-compatible tool.

Slash Commands

Two built-in slash commands for AI-assisted PR review (installed automatically by contextception setup):

| Command | Description | |---------|-------------| | /pr-risk | Run risk analysis on the current branch and present an actionable, human-friendly review | | /pr-fix | Analyze risk, then build an ordered plan to fix every issue found (test gaps, coupling, fragility) |

These work by combining contextception's deterministic risk analysis with the LLM's ability to explain and translate — contextception computes the scores, the LLM presents them in plain language. See [integrations/](integrations/) for setup details.

---

Language Support

| Language | Extractor | Resolver | File Types | |----------|-----------|----------|------------| | Python | Regex | Package hierarchy, pyproject.toml, __init__.py | .py | | TypeScript/JS | Tree-sitter (CGO) / Regex fallback | tsconfig paths + extends chains, workspace monorepos, barrel files | .ts .tsx .js .jsx | | Go | Regex | go.mod + go.work, same-package resolution | .go | | Java | Regex | Package-to-directory, mirror-directory test discovery | .java | | Rust | Regex | Cargo workspaces, mod.rs, crate/super/self paths, inline test detection | .rs | | C# | Regex | .csproj project detection, namespace-to-file resolution, filename search fallback | .cs |

---

CLI Reference

contextception index                    Build or update the index
contextception analyze            Analyze context dependencies for a file
contextception analyze-change [base]    Analyze the impact of a PR or commit range
contextception search            Search the index for files by path or symbol
contextception archetypes               Detect archetype files from the index
contextception history      View historical analysis (trend, hotspots, distribution, file)
contextception reindex                  Delete and rebuild the index from scratch
contextception extensions                List supported file extensions
contextception status                   Show index status and diagnostics
contextception mcp                      Start the MCP server (stdio transport)
contextception update                   Check for and install the latest version
contextception setup                    Configure contextception for your AI editor
contextception gain                     Show usage analytics dashboard
contextception accuracy                 Show recommendation accuracy from LLM feedback
contextception discover                 Find files edited without get_context being called
contextception session                  Show contextception adoption across Claude Code sessions

Key Flags

| Flag | Description | |------|-------------| | --mode plan\|implement\|review | Shape output for AI workflow stage | | --token-budget N | Cap output to fit token limits | | --compact | Token-optimized text summary (~60-75% fewer tokens than JSON) | | --ci --fail-on high\|medium\|critical | Exit codes for CI pipelines | | --cap N | Limit must_read entries (overflow to related) | | --no-external | Exclude external dependencies | | --no-update-check | Disable automatic update version check |

Updating

Contextception checks for new versions automatically (once per day, cached) and prints a notification to stderr when an update is available. To update:

contextception update

The update command detects your install method and acts accordingly:

• Direct download: downloads and replaces the binary with checksum verification
• Homebrew: suggests brew upgrade contextception
• go install: suggests go install ...@latest

Disable the automatic check with --no-update-check, CONTEXTCEPTION_NO_UPDATE_CHECK=1, or set update.check: false in the global config at /contextception/config.yaml (where ` is ~/Library/Application Support on macOS, ~/.config on Linux, %AppData%` on Windows).

---

Analytics & Feedback

Contextception tracks its own usage and recommendation quality:

contextception gain                     # Usage dashboard: analysis counts, top files, trends
contextception accuracy                 # Recommendation quality: precision, recall from LLM feedback
contextception discover                 # Find files edited without context being checked
contextception session                  # Adoption rates per Claude Code session

The rate_context MCP tool lets AI agents submit structured feedback after using get_context — which files were useful, unnecessary, or missing. This creates a closed feedback loop for measuring and improving recommendation quality over time.

All analytics are deterministic and stored locally in .contextception/history.sqlite. Export with --format json or --format csv for dashboards.

---

What You Get

The output provides structured, ranked context across eight categories:

• confidence: 0.0–1.0 reliability score for the analysis
• must_read: files required to safely understand the change, with symbols, direction, and role
• likely_modify: files likely needing modification, grouped by confidence (high/medium/low)
• tests: test files covering the subject (direct and indirect tiers)
• related: nearby context worth reviewing (2-hop dependencies, hidden coupling)
• blast_radius: overall risk profile (high/medium/low with fragility metric)
• hotspots: high-churn files that are also structural bottlenecks
• circular_deps: import cycles involving the subject file

---

Configuration

Optional. Create .contextception/config.yaml in your repo ro

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kehoej
• Source: kehoej/contextception
• License: MIT

Install and usage instructions live in the source repository linked above.