{"id":48524589,"url":"https://github.com/kehoej/contextception","last_synced_at":"2026-04-07T22:01:12.394Z","repository":{"id":349573239,"uuid":"1201387772","full_name":"kehoej/contextception","owner":"kehoej","description":"Deterministic context intelligence for code","archived":false,"fork":false,"pushed_at":"2026-04-06T14:49:04.000Z","size":419,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-06T16:34:11.890Z","etag":null,"topics":["code-context","dependency-graph","developer-tools","go","mcp","static-analysis"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kehoej.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-04T15:59:29.000Z","updated_at":"2026-04-06T14:04:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kehoej/contextception","commit_stats":null,"previous_names":["kehoej/contextception"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/kehoej/contextception","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kehoej%2Fcontextception","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kehoej%2Fcontextception/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kehoej%2Fcontextception/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kehoej%2Fcontextception/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kehoej","download_url":"https://codeload.github.com/kehoej/contextception/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kehoej%2Fcontextception/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31530647,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-context","dependency-graph","developer-tools","go","mcp","static-analysis"],"created_at":"2026-04-07T22:00:27.399Z","updated_at":"2026-04-07T22:01:12.377Z","avatar_url":"https://github.com/kehoej.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Contextception\n\n[![CI](https://github.com/kehoej/contextception/actions/workflows/ci.yml/badge.svg)](https://github.com/kehoej/contextception/actions/workflows/ci.yml)\n[![Go Reference](https://pkg.go.dev/badge/github.com/kehoej/contextception.svg)](https://pkg.go.dev/github.com/kehoej/contextception)\n[![Go Report Card](https://goreportcard.com/badge/github.com/kehoej/contextception)](https://goreportcard.com/report/github.com/kehoej/contextception)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Release](https://img.shields.io/github/v/release/kehoej/contextception)](https://github.com/kehoej/contextception/releases)\n[![Go Version](https://img.shields.io/github/go-mod/go-version/kehoej/contextception)](go.mod)\n\n**Deterministic context intelligence for code.**\nAnswers: *\"What must be understood before making a safe change?\"*\n\nContextception 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.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/01-full-pipeline.svg\" alt=\"Contextception dependency graph traversal\" width=\"800\"\u003e\n\u003c/p\u003e\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e97% Precision (independent ground truth)\u003c/strong\u003e \u0026nbsp;\u0026middot;\u0026nbsp;\n  \u003cstrong\u003eTested across 16 repos\u003c/strong\u003e \u0026nbsp;\u0026middot;\u0026nbsp;\n  \u003cstrong\u003eSub-second Analysis\u003c/strong\u003e \u0026nbsp;\u0026middot;\u0026nbsp;\n  \u003cstrong\u003e5 Languages\u003c/strong\u003e \u0026nbsp;\u0026middot;\u0026nbsp;\n  \u003cstrong\u003eFree \u0026 Open Source\u003c/strong\u003e\n\u003c/p\u003e\n\n---\n\n## Install\n\n**Go install:**\n\n```bash\ngo install github.com/kehoej/contextception/cmd/contextception@latest\n```\n\n\u003e **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.\n\n**Homebrew:**\n\n```bash\nbrew install kehoej/tap/contextception\n```\n\n**Shell script (Linux/macOS):**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/kehoej/contextception/main/install.sh | sh\n```\n\n**Build from source:**\n\n```bash\ngit clone https://github.com/kehoej/contextception.git\ncd contextception \u0026\u0026 make build\n# Binary at ./bin/contextception\n```\n\n**Windows:** Download the `.zip` from [GitHub Releases](https://github.com/kehoej/contextception/releases) and add to your PATH.\n\n---\n\n## How It Works\n\n### 1. Index your repo\n\n```bash\n$ contextception index\nIndexed 2,638 files, 10,087 edges in 0.9s\n```\n\nScans your codebase, extracts imports across 5 languages, resolves dependencies, computes git history signals. **Incremental:** only changed files reprocessed.\n\n### 2. Analyze any file\n\n```bash\n$ contextception analyze src/auth/login.py\n```\n\n```json\n{\n  \"schema_version\": \"3.2\",\n  \"subject\": \"src/auth/login.py\",\n  \"confidence\": 0.92,\n  \"must_read\": [\n    { \"file\": \"src/auth/session.py\", \"symbols\": [\"createSession\"], \"direction\": \"imports\", \"role\": \"foundation\" },\n    { \"file\": \"src/auth/types.py\", \"symbols\": [\"User\", \"AuthConfig\"], \"direction\": \"imports\", \"role\": \"utility\" }\n  ],\n  \"likely_modify\": {\n    \"high\": [{ \"file\": \"src/auth/session.py\", \"signals\": [\"direct_import\"] }]\n  },\n  \"tests\": {\n    \"direct\": [\"tests/auth/test_login.py\"],\n    \"indirect\": [\"tests/auth/test_session.py\"]\n  },\n  \"blast_radius\": {\n    \"level\": \"medium\",\n    \"detail\": \"8 files in dependency subgraph, 3 direct importers\",\n    \"fragility\": 0.45\n  }\n}\n```\n\nReturns ranked context: what to read, what might change, which tests cover it, and the blast radius, with **every recommendation explained**.\n\nAnalyze multiple files at once to get merged context across a feature:\n\n```bash\n$ contextception analyze src/auth/login.py src/auth/session.py src/auth/types.py\n```\n\n### 3. Act on the context\n\nFeed the output to your AI agent via MCP, gate PRs with blast radius in CI, or use it to understand unfamiliar code:\n\n```yaml\n# CI: fail PR if blast radius is high\ncontextception analyze-change --ci --fail-on high\n```\n\n---\n\n## Blast Radius Analysis\n\nEvery change has a ripple effect. Contextception maps it:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/03-blast-radius.svg\" alt=\"Blast radius visualization\" width=\"800\"\u003e\n\u003c/p\u003e\n\n- **Critical zone:** files that will definitely break\n- **Warning zone:** files needing review\n- **Fragility score:** how unstable the affected subgraph is (0.0–1.0)\n\n---\n\n## Hotspot Detection\n\nHigh churn + high fan-in = architectural risk. Contextception finds these automatically:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/08-hotspot-heatmap.svg\" alt=\"Hotspot heatmap\" width=\"800\"\u003e\n\u003c/p\u003e\n\nFiles 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.\n\n---\n\n## Git History Intelligence\n\nStatic analysis shows what *can* affect a file. Git history shows what *actually changes together*. Contextception combines both.\n\nDuring indexing, Contextception analyzes your last 90 days of git history to extract three signals:\n\n- **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\n- **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\n- **Churn tracking:** high-churn files are flagged so you know which dependencies are volatile vs. stable\n\nThese 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.\n\n---\n\n## PR \u0026 Change Analysis\n\nAnalyze an entire PR or commit range to understand its impact before merging:\n\n```bash\n$ contextception analyze-change origin/main\n```\n\nReturns a PR-level impact report with:\n\n- **Test gaps:** changed files with no test coverage, flagged before merge\n- **Coupling detection:** pairs of changed files that depend on each other\n- **Hidden coupling:** co-change partners *not in your diff* that may need updating\n- **Per-file blast radius:** which specific changes carry the most risk\n- **Aggregated must_read:** merged context across all changed files\n\nUse `--ci --fail-on high` to gate PRs automatically. Results are stored in a local history database, enabling trend tracking with `contextception history`:\n\n```bash\n$ contextception history hotspots     # Files that repeatedly appear as hotspots\n$ contextception history trend        # Blast radius trend over recent analyses\n```\n\n---\n\n## Confidence Scoring\n\nEvery analysis includes a confidence score (0.0–1.0) based on import resolution completeness:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/05-confidence-scoring.svg\" alt=\"Confidence scoring\" width=\"800\"\u003e\n\u003c/p\u003e\n\nIf imports can't be resolved (dynamic imports, missing packages), the confidence score tells you how much to trust the results.\n\n---\n\n## Performance\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/10-speed-benchmark.svg\" alt=\"Performance benchmarks\" width=\"800\"\u003e\n\u003c/p\u003e\n\n| Repository | Files | Index Time | Analysis Time |\n|-----------|-------|-----------|---------------|\n| Excalidraw | 602 | 0.3s | \u003c100ms |\n| Zulip | 2,638 | 0.9s | \u003c100ms |\n| Cal.com | 7,366 | 2.8s | \u003c100ms |\n\nAnalysis is always sub-100ms after indexing. Indexing is incremental; subsequent runs process only changed files.\n\n---\n\n## Head-to-Head\n\nTested against Aider's repo-map and Repomix across 6 real-world repos. The httpx results use independent, hand-verified fixture ground truth. For other repos, ground truth is Contextception's own validated output (see [methodology](benchmarks/methodology.md) for details).\n\n**httpx (independent ground truth):**\n\n| Metric | Contextception | Aider @8192t | Repomix |\n|--------|---------------|-------------|---------|\n| **Recall** | 97% | 90% | N/A |\n| **Precision** | 97% | 31% | \u003c0.01% |\n| **Tokens (avg)** | 748 | 6,727 | 198,000 |\n\nContextception averages ~1,000 tokens per analysis vs. Repomix's full-repo output (200K–17M tokens). Compared to Aider's repo-map, **Contextception uses 3–5x fewer tokens while achieving higher recall** on independent ground truth. Aider's recall degrades significantly as repos grow, from 90% on httpx (60 files) to 0% on Spring Boot (7,978 files).\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003ePer-repo recall breakdown\u003c/strong\u003e\u003c/summary\u003e\n\n| Repository | Files | Contextception | Aider @8192t | Aider @4096t |\n|-----------|-------|---------------|-------------|-------------|\n| httpx (Python) | 60 | 97% | 90% | 83% |\n| Excalidraw (TS) | 602 | 100%\\* | 25.3% | 20.0% |\n| Tokio (Rust) | 1,021 | 100%\\* | 1.4% | 1.4% |\n| Terraform (Go) | 1,885 | 100%\\* | 7.9% | 6.3% |\n| Zulip (Python) | 2,638 | 100%\\* | 27.4% | 24.2% |\n| Spring Boot (Java) | 7,978 | 100%\\* | 0% | 0% |\n\n\\* Measured against CC's own validated output (Grade A, 3.76–3.97). See [benchmarks/](benchmarks/) for full methodology and reproducible results.\n\n\u003c/details\u003e\n\n---\n\n## MCP Setup (30 seconds)\n\nMake your AI agent smarter. Add to your `~/.claude.json` (Claude Code) or equivalent MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"contextception\": {\n      \"command\": \"contextception\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nThis exposes eight tools to the AI agent:\n\n| Tool | Description |\n|------|-------------|\n| `get_context` | Analyze a file's context dependencies (auto-indexes if needed) |\n| `index` | Build or update the repository index |\n| `status` | Return index diagnostics |\n| `search` | Search the index for files by path pattern or symbol name |\n| `get_entrypoints` | Return entrypoint and foundation files for project orientation |\n| `get_structure` | Return directory structure with file counts and language distribution |\n| `get_archetypes` | Detect representative files across architectural layers |\n| `analyze_change` | Analyze the impact of a git diff / PR (blast radius, test gaps, coupling) |\n\nWorks with **Claude Code**, **Cursor**, **Windsurf**, and any MCP-compatible tool.\n\n---\n\n## Language Support\n\n| Language | Extractor | Resolver | File Types |\n|----------|-----------|----------|------------|\n| **Python** | Regex | Package hierarchy, pyproject.toml, `__init__.py` | `.py` |\n| **TypeScript/JS** | Tree-sitter (CGO) / Regex fallback | tsconfig paths + extends chains, workspace monorepos, barrel files | `.ts` `.tsx` `.js` `.jsx` |\n| **Go** | Regex | go.mod + go.work, same-package resolution | `.go` |\n| **Java** | Regex | Package-to-directory, mirror-directory test discovery | `.java` |\n| **Rust** | Regex | Cargo workspaces, mod.rs, crate/super/self paths, inline test detection | `.rs` |\n\n---\n\n## CLI Reference\n\n```\ncontextception index                    Build or update the index\ncontextception analyze \u003cfile\u003e           Analyze context dependencies for a file\ncontextception analyze-change [base]    Analyze the impact of a PR or commit range\ncontextception search \u003cquery\u003e           Search the index for files by path or symbol\ncontextception archetypes               Detect archetype files from the index\ncontextception history \u003csubcommand\u003e     View historical analysis (trend, hotspots, distribution, file)\ncontextception reindex                  Delete and rebuild the index from scratch\ncontextception extensions                List supported file extensions\ncontextception status                   Show index status and diagnostics\ncontextception mcp                      Start the MCP server (stdio transport)\n```\n\n### Key Flags\n\n| Flag | Description |\n|------|-------------|\n| `--mode plan\\|implement\\|review` | Shape output for AI workflow stage |\n| `--token-budget N` | Cap output to fit token limits |\n| `--ci --fail-on high\\|medium` | Exit codes for CI pipelines |\n| `--cap N` | Limit must_read entries (overflow to related) |\n| `--no-external` | Exclude external dependencies |\n\n---\n\n## What You Get\n\nThe output provides structured, ranked context across eight categories:\n\n- **`confidence`:** 0.0–1.0 reliability score for the analysis\n- **`must_read`:** files required to safely understand the change, with symbols, direction, and role\n- **`likely_modify`:** files likely needing modification, grouped by confidence (high/medium/low)\n- **`tests`:** test files covering the subject (direct and indirect tiers)\n- **`related`:** nearby context worth reviewing (2-hop dependencies, hidden coupling)\n- **`blast_radius`:** overall risk profile (high/medium/low with fragility metric)\n- **`hotspots`:** high-churn files that are also structural bottlenecks\n- **`circular_deps`:** import cycles involving the subject file\n\n---\n\n## Configuration\n\nOptional. Create `.contextception/config.yaml` in your repo root:\n\n```yaml\nversion: 1\nentrypoints:\n  - cmd/server/main.go\nignore:\n  - vendor\n  - third_party\ngenerated:\n  - proto/generated\n```\n\n| Field | Description |\n|-------|-------------|\n| `entrypoints` | Files treated as architectural entry points (boosted in scoring) |\n| `ignore` | Directories excluded from analysis results |\n| `generated` | Directories whose files are categorized as ignore |\n\n---\n\n## Tested Across 16 Repositories\n\nIndexed and analyzed real-world codebases spanning all 5 supported languages:\n\n| Repository | Language | Files |\n|-----------|----------|-------|\n| Next.js | TypeScript | 4,200+ |\n| Remix | TypeScript | 800+ |\n| Supabase | TypeScript | 3,500+ |\n| Cal.com | TypeScript | 7,366 |\n| Django | Python | 2,800+ |\n| Home Assistant | Python | 12,000+ |\n| Zulip | Python | 2,638 |\n| Excalidraw | TypeScript | 602 |\n| Terraform | Go | 1,885 |\n| Moby (Docker) | Go | 4,500+ |\n| Spring Boot | Java | 7,978 |\n| Kafka | Java | 3,200+ |\n| Tokio | Rust | 1,021 |\n| Bevy | Rust | 2,400+ |\n| Medusa | TypeScript | 1,800+ |\n| supermemory | TypeScript | 200+ |\n\n**Tested across 419 files spanning all 5 supported languages.**\n\n---\n\n## How Contextception Differs\n\nContextception is a standalone static analysis tool, not an AI coding assistant. Tools like Cursor, Augment, and Aider include implicit dependency reasoning within their LLM pipelines but don't expose it as inspectable, deterministic output. The comparison below focuses on tools that produce standalone file-level context.\n\n| Capability | Contextception | Aider repo-map | Repomix |\n|------------|:-:|:-:|:-:|\n| Static dependency graph | Full (5 languages) | Partial (tree-sitter) | No |\n| Per-file relevance ranking | Yes | PageRank-based | No (full dump) |\n| Explainability (direction, symbols, role) | Yes | No | No |\n| Blast radius / risk scoring | Yes | No | No |\n| Test discovery | Yes | No | No |\n| Co-change / hotspot detection | Yes | No | No |\n| Circular dependency detection | Yes | No | No |\n| MCP server | Yes | No | No |\n| Deterministic (no LLM required) | Yes | No (requires LLM API) | Yes |\n| Local / offline | Yes | Requires LLM API | Yes |\n| Free \u0026 open source | Yes | Yes (tool); LLM costs apply | Yes |\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkehoej%2Fcontextception","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkehoej%2Fcontextception","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkehoej%2Fcontextception/lists"}