{
  "markdown": "# forensic-deepdive\n\n<!-- mcp-name: io.github.Dhevenddra/forensic-deepdive -->\n\n**`forensic-deepdive` gives an AI coding agent forensic understanding of an unfamiliar codebase** — a persistent knowledge graph, an MCP server, and five durable markdown artifacts, so your agent stops re-discovering the same architecture from scratch every session.\n\n```bash\nuv tool install forensic-deepdive && forensic extract /path/to/repo\n```\n\n![forensic-deepdive: forensic extract, then forensic graph, rendering a confidence-styled Mermaid diagram in the terminal](docs/assets/demo.gif)\n<!-- regenerate with `make demo-gif` (scripts/render_demo_gif.py — pure Python + Pillow, no vhs/ttyd, DEC-122) -->\n\n**Why this is different:** every edge and every emitted claim carries a confidence tag —\n`EXTRACTED` (deterministic fact) / `INFERRED` (a heuristic resolved cleanly) / `AMBIGUOUS`\n(multiple candidates, shown, not guessed) — so your agent knows what to trust *before* it\nacts on it. Nothing else in this category tags confidence at all.\n\n## Why not GitNexus / CodeGraphContext / DeepWiki / Sourcegraph\n\n| | forensic-deepdive | GitNexus | CodeGraphContext | DeepWiki | Sourcegraph |\n|---|---|---|---|---|---|\n| License | **Apache-2.0** | PolyForm Noncommercial | MIT | proprietary (open variant: MIT) | partial |\n| Persistent code knowledge graph | ✅ LadybugDB | ✅ LadybugDB | partial | ❌ | partial |\n| MCP server | ✅ 9 composite tools | ✅ 16 tools | partial | ❌ | ❌ |\n| Per-edge confidence taxonomy | ✅ EXTRACTED / INFERRED / AMBIGUOUS | ❌ | ❌ | ❌ | ❌ |\n| Git archaeology as a first-class layer | ✅ | ❌ | ❌ | ❌ | partial |\n| Durable committed markdown artifacts | ✅ 5 files | partial | partial | ✅ (wiki) | ❌ |\n| Agent-insight layer (`record_insight` / `recall_insights`) | ✅ | ❌ | ❌ | ❌ | ❌ |\n| Multi-platform skill emission | ✅ 10 shims | partial | partial | ❌ | ❌ |\n| Local-only (no cloud required) | ✅ co-equal | ✅ | ✅ | ❌ | ❌ |\n\n**GitNexus is the runaway leader in this category — but its PolyForm Noncommercial\nlicense locks every commercial user out.** `forensic-deepdive` is the Apache-2.0\nalternative: same persistent-graph-plus-MCP shape, plus honest confidence tags, git\narchaeology, persistent agent memory, and the 5 markdown artifacts as a fallback for any\nagent that doesn't speak MCP — with a license your employer's legal team will actually\nsign off on.\n\n---\n\n## What it produces\n\n`forensic-deepdive` analyzes any codebase (9 languages, polyglot) and produces:\n\n1. **A persistent embedded graph** at `<repo>/.deepdive/graph.lbug` — File, Symbol, Module, Commit, Author, **Endpoint**, and **DbTable** nodes plus DEFINES, MEMBER_OF, IMPORTS, CALLS, EXTENDS, IMPLEMENTS, TOUCHED_BY_COMMIT, AUTHORED_BY, CO_CHANGES_WITH, and the cross-boundary HANDLES / CALLS_ENDPOINT / **ROUTES_TO** / INJECTS / PERSISTS_TO edges. **Every edge carries a confidence tag** (`EXTRACTED` / `INFERRED` / `AMBIGUOUS`) — no hidden heuristics. The single `Endpoint` join node unifies **five cross-boundary protocols** (HTTP, MCP tools, registry-dispatch, gRPC, messaging/AMQP), so a frontend call resolves to its backend handler across the stack as one `ROUTES_TO` edge.\n2. **An MCP server** (`forensic serve`) exposing **9 composite tools** (`impact`, `context`, `archaeology`, `flow`, `query`, `record_insight`, `recall_insights`, `visualize`, `trace`) consumable by Claude Code, Cursor, Codex, Continue, Cline, Windsurf — and any other MCP-aware agent.\n3. **Five durable markdown artifacts** under `<repo>/docs/codebase/`, regenerated from the graph on every extract:\n   - **`MAP.md`** — what's where, ranked by centrality.\n   - **`HOTPATHS.md`** — the dependency hot spots, with a per-row confidence-mix column so you see exactly how cleanly each symbol resolves.\n   - **`ARCHAEOLOGY.md`** — why the code looks the way it does (git history, top authors with %, bus factor, co-change clusters, defect proximity).\n   - **`MENTAL_MODEL.md`** — the doc the original author *would* write to onboard a new hire.\n   - **`AGENT_BRIEF.md`** — ≤5 KB of assertive Never/Always rules with per-rule confidence tags. Drop-in `CLAUDE.md` for any project.\n4. **Ten shims into the target repo** — 4 editor rule files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/codebase.mdc`, `.continue/rules/codebase.md`), 5 single-intent Claude skills under `.claude/skills/codebase-{exploring,debugging,impact-analysis,refactoring,onboarding}/`, and a `.claude-plugin/plugin.json` manifest. All write-if-absent — hand-edited files are never overwritten.\n5. **An agent-insight layer** — `record_insight` / `recall_insights` MCP tools backed by `<repo>/.deepdive/insights.jsonl` by default (zero dependencies, human-readable, git-friendly). The optional `[graphiti]` extra upgrades to a temporal knowledge graph backend above a 2-of-5 repo-size threshold.\n\nExtract also regenerates **`ARCHITECTURE.md`** — a system-level Mermaid view of the cross-boundary graph (ROUTES_TO / INJECTS / PERSISTS_TO, confidence-styled), a *separate human-validation surface* (not one of the five contract artifacts, exactly like `forensic visualize` and `serve --ui`). Regenerate it on its own with `forensic diagram --repo <repo>`. Use it to sanity-check the graph — a wrong edge there is a wrong edge everywhere.\n\nAdd **`--emit-vault`** to also write an [Obsidian](https://obsidian.md)-friendly vault under `<output>/vault/` — every artifact gets `summary:`/`tags:` frontmatter, cross-references become `[[wikilinks]]`, and an `INDEX.md` MOC ties them together (with a `.obsidian/` config). A local-first second brain for humans (graph view, backlinks) and agents (triage by `summary:` without opening files, a traversable index). Opt-in; off by default.\n\n## Status\n\n**v0.10.0 \"The Upgrade Path\"** — an integrity release. v0.9 shipped correct, and then its findings run caught `--refresh-shims` being structurally unable to refresh half its targets, with 909 tests green over it. The cause wasn't the fix — it was that **every test in the suite wrote into an empty directory, so only the *first* run had ever been tested.** Everyone who isn't a new user lives on the untested path.\n\nSo 0.10 adds almost no surface. It makes the guarantees already made real: running Deepdive over a repo that already carries a previous release's output now provably **converges** (and provably leaves your hand-edited files alone), `extract` **tells you** when generated shims are stale instead of waiting for you to know the flag exists, and a stale `examples/` fails CI rather than being caught by eye mid-release. New: [`forensic extract --timings`](#quick-start), per-phase wall clock.\n\nIt also contains a **cancelled feature**, which is the more useful story. The planned performance work targeted PageRank. The profile required before touching it measured PageRank at **0.04 %** of a large extract, and the *already-batched* store writes at **79–87 %**. The optimization was disproven before it was written — see [`docs/findings/v0.10/PROFILE.md`](docs/findings/v0.10/PROFILE.md). Confirming a known technique had been applied had been mistaken for confirming it was fast.\n\nThe engine, the graph, the contract layer and the 5-artifact + 9-MCP-tool contract are **unchanged** from 0.9, and emitted content is byte-identical but for the version footer.\n\n> **⚠ If you installed 0.8.0 or 0.9.0 and `forensic serve` stopped working — this is why.** Those\n> releases declare `mcp>=1.27.1` with no upper bound. `mcp` 2.0.0 removed `mcp.server.fastmcp`,\n> which the MCP server imports, so a **fresh install of 0.8.0 or 0.9.0 today** resolves to `mcp`\n> 2.0.0 and fails on import. Our development lockfile pinned 1.27.1, so every local check stayed\n> green and only the clean-environment wheel smoke in CI could see it. **Fix: upgrade to 0.10.0**\n> (which caps `mcp<2`), or pin `mcp<2` yourself. Nothing else about those releases is affected.\n\n**What's proven, and what isn't** — the honest-framing section moved to\n[`docs/findings/HONEST.md`](docs/findings/HONEST.md) (unchanged content, DEC-119). Short\nversion: proven **usable** with real agent auto-discovery; **not** proven to make\nautonomous issue resolution measurably faster end-to-end (hardware-gated). This is an\nassisted-analysis tool, and it is not overclaimed as more.\n\n## Quick start\n\n```bash\n# install from PyPI (puts `forensic` on PATH); or run ephemerally with uvx\nuv tool install forensic-deepdive\nforensic info            # banner + capability panel\nforensic extract /path/to/repo\n\n# …or from source for development:\ngit clone https://github.com/Dhevenddra/forensic-deepdive && cd forensic-deepdive\nuv sync --all-extras\n\n# what can it do? (banner + capability panel: artifacts, protocols, MCP tools, confidence legend)\nuv run forensic info\n\n# guided setup: analyze a repo, then wire it up as an MCP server\n# (--yes takes every default: scriptable, and the one mode that needs no extra)\nuv run forensic onboard --repo /path/to/repo\n\n# run on any repo\nuv run forensic extract /path/to/repo\n\n# graph lands at <repo>/.deepdive/graph.lbug\n# 5 markdown artifacts at <repo>/docs/codebase/\n# 10 shims at <repo>/.claude/, .cursor/, .continue/, root\n\n# trace a cross-stack feature slice (frontend call -> endpoint -> handler -> tail)\nuv run forensic trace <symbol> --repo /path/to/repo\n\n# interactive query REPL over one held-open store (needs the [interactive] extra)\n# bare text = natural-language query (no LLM) · :cypher <q> = raw Cypher · :help · Ctrl-D exits\nuv run forensic repl --repo /path/to/repo\n\n# full-screen terminal graph browser — the loopback-free sibling of serve --ui\n# 1/2/3 = Symbols/Files/Endpoints · type to filter · c/e/l = confidence/edge/language · Enter = context · i/f = impact/flow\nuv run forensic browse --repo /path/to/repo\n\n# the session shell: all of the above over ONE held-open graph, with history\n# in-session: extract · query · trace · impact · flow · diagram · browse · onboard · serve\nuv run deepdive --repo /path/to/repo\n\n# query the graph as an MCP server (point it at the analyzed repo)\nuv run forensic serve --repo /path/to/repo\n\n# inspect every repo you've analyzed\nuv run forensic list\n```\n\n## Install from PyPI\n\nPublished as **[`forensic-deepdive`](https://pypi.org/project/forensic-deepdive/)** —\nno clone needed:\n\n```bash\nuv tool install forensic-deepdive        # puts `forensic` on PATH\nforensic extract /path/to/repo\n\n# …or run ephemerally, no install:\nuvx forensic-deepdive extract /path/to/repo\n```\n\nOptional extras: `uv tool install \"forensic-deepdive[semantic]\"` (offline ONNX NL\nquery), `[interactive]` (the `forensic repl` query console, the `forensic browse`\nTUI graph browser, and the `deepdive` session shell), `[openapi]` (YAML spec\nparsing), `[graphiti]` (temporal insight backend).\n\n### Upgrading from 0.8\n\nRe-run `extract` with `--refresh-shims` once. The generated shims and skills under\n`.claude/`, `.cursor/` and `.continue/` are written only if absent, so a plain\nre-extract leaves your 0.8-era copies in place, and two of the skill files still cite\ninternal decision IDs that 0.9 removed:\n\n```bash\nforensic extract /path/to/repo --force --refresh-shims\n```\n\nOnly files Deepdive generated are rewritten. A shim you have hand-edited is never\ntouched.\n`pip install forensic-deepdive` works too if you're not on `uv`.\n\n## Use it as an MCP server\n\n`forensic serve` is a stdio MCP server exposing the 9 composite tools to any\nMCP-aware agent (Claude Code, Cursor, VS Code/Copilot, Codex, Continue, Cline,\nWindsurf). First build the graph once (`forensic extract <repo>`), then wire the\nserver. Three ways, easiest first:\n\n**1. Claude Code plugin (self-hosted marketplace — no PyPI step):**\n\n```shell\n/plugin marketplace add Dhevenddra/forensic-deepdive\n/plugin install forensic-deepdive@dhevenddra\n```\n\n**2. From the [MCP Registry](https://registry.modelcontextprotocol.io)** — indexed as\n`io.github.Dhevenddra/forensic-deepdive`, so registry-aware clients and discovery hubs\n(PulseMCP, MCPJungle, the VS Code `@mcp` index) can find and install it directly.\n\n**3. Manual config** — generate a client snippet with `forensic mcp-config`, or paste:\n\n```json\n{\n  \"mcpServers\": {\n    \"forensic-deepdive\": {\n      \"command\": \"uvx\",\n      \"args\": [\"forensic-deepdive\", \"serve\", \"--repo\", \".\"]\n    }\n  }\n}\n```\n\nPer-client copy-paste blocks (Cursor, VS Code, Codex, the `uvx`-not-found GUI gotcha)\nare in **[docs/install.md](docs/install.md)**.\n\n## The 9 supported languages\n\nPython, C, Dart, Swift, TypeScript, JavaScript, Java, Go, Rust.\n\n## The 9 MCP tools\n\n| Tool | What it does |\n|---|---|\n| `impact(symbol, depth, direction, min_confidence)` | Blast-radius BFS over CALLS edges, depth-bucketed, confidence-filterable. |\n| `context(symbol)` | Single-call kitchen sink: definition + callers + callees + parent/siblings/members + extends/implements + recent commits + dominant author + recent insights. |\n| `archaeology(file_or_symbol)` | Churn, top authors with %, bus factor, co-change cluster, defect proximity, recent commits. |\n| `flow(entry_point, max_depth)` | DFS over CALLS with cycle detection. |\n| `query(cypher \\| natural_language)` | Raw Cypher, or hybrid NL retrieval (FTS5/BM25 + structural graph signal + opt-in offline semantic, RRF-fused and shaped) with per-hit provenance + confidence. |\n| `record_insight(symbol, claim, evidence, verified_by)` | Persist a verified learning. |\n| `recall_insights(symbol, since, limit)` | Newest-first substring match against stored insights. |\n| `visualize(target, format, depth, max_nodes, ...)` | Bounded Mermaid diagram of a symbol/file neighborhood (or `central`); edge dash style encodes confidence. |\n| `trace(symbol, direction, max_depth)` | Cross-stack feature slice across the `Endpoint` join node: `downstream` walks frontend call → `CALLS_ENDPOINT` → endpoint → `HANDLES` → handler → CALLS tail; `upstream` answers \"who calls this endpoint\". |\n\nTool descriptions are individually ≤200 tokens so the 9-tool envelope stays comfortably inside Anthropic's per-turn skill metadata budget.\n\n## The confidence taxonomy\n\nEvery edge and every emitted claim carries `EXTRACTED` / `INFERRED` / `AMBIGUOUS`:\n\n- **`EXTRACTED`** — deterministic from AST or `git log`. Facts.\n- **`INFERRED`** — a heuristic resolved cleanly (import-graph walk, receiver-type inference, single same-name candidate cross-file). High-trust but derived.\n- **`AMBIGUOUS`** — multiple candidates surfaced; the resolver couldn't disambiguate. **You see every candidate**, not a silent guess.\n\nHOTPATHS shows a per-row confidence-mix column so at a glance you can tell `Logger` (4 EXTRACTED + 1458 INFERRED — mostly clean) from `ChatToolResponse` (449 AMBIGUOUS — same-name cross-file collision).\n\n## Honest-mode (pure-static, zero LLM, zero network)\n\n`forensic extract` works end-to-end with **no `ANTHROPIC_API_KEY`, no `OPENAI_API_KEY`, no Ollama, no network**. Graphiti is opt-in via the `[graphiti]` PyPI extra plus a 2-of-5 repo-size threshold (≥50 k LOC, ≥25 contributors, ≥18 mo old, ≥200 PRs/12 mo, ≥100 issues with discussion). The `JsonlInsightStore` is the always-available floor.\n\n(The GitNexus/CodeGraphContext/DeepWiki/Sourcegraph comparison table is up top — it's\nthe headline, not a footnote.)\n\n## Local development\n\n```bash\ngit clone https://github.com/Dhevenddra/forensic-deepdive\ncd forensic-deepdive\nuv sync --all-extras\nuv run forensic --version\nuv run pytest -x          # 1000+ tests at v0.10.0\nuv run ruff check src/ tests/\nuv run forensic extract tests/fixtures/tiny_fixture\n```\n\nRead `CLAUDE.md`, `DECISIONS.md` (81 active DECs), and `PROGRESS.md` before making changes. This repo dogfoods its own pattern: every session starts with the protocol in `CLAUDE.md`, every architectural choice is captured as a `DEC-N` entry, and the artifact-name contract (`MAP`, `HOTPATHS`, `ARCHAEOLOGY`, `MENTAL_MODEL`, `AGENT_BRIEF`) is part of the public API.\n\n## Acknowledgments\n\n- **Aider** (Paul Gauthier) for the PageRank-on-Tree-sitter repo-map pattern. Algorithm ported with attribution; we do not depend on `aider` as a package.\n- **Graphify** (safishamsi) for the EXTRACTED / INFERRED / AMBIGUOUS confidence taxonomy. Productized in DEC-015 across every emitter.\n- **GitNexus** (abhigyanpatwari) for the multi-repo registry pattern (`~/.deepdive/registry.json`, DEC-018), the composite-MCP-tool shape, and being the licensing wedge that makes this project's Apache-2.0 differentiation matter.\n- **Kuzu** (now Apple-archived) for the embedded graph engine; **LadybugDB** for the live community fork that v0.2 ships against (DEC-013).\n- **Zep / getzep** for **Graphiti** — the temporal knowledge graph that powers the above-threshold insight backend (DEC-019).\n- **Anthropic** for the Skills format, Claude Code, and the MCP protocol that makes this whole product shape possible.\n- **Astral** for `uv` and `ruff`.\n- **Repomix** (yamadashy) for the original v0.1 flatten-the-repo pattern, now demoted to `--legacy-repomix` (DEC-017) but still available for legacy use cases.\n\n## Contributing\n\nContributions are welcome — see **[CONTRIBUTING.md](CONTRIBUTING.md)** for the dev\nsetup, the verification gate, and the architectural invariants (the 5-artifact contract,\nthe `Endpoint` keystone, the confidence taxonomy). By contributing you agree your work\nis licensed under Apache-2.0.\n\n## License\n\nApache-2.0. See [`LICENSE`](LICENSE).\n\nIf you redistribute, modify, or build on this project, the Apache-2.0 terms apply: you\nmust **retain the copyright notice, the `LICENSE` text, and the `NOTICE` file**, and\n**state any changes you made** (License §4). Attribution is required; the project is\nCopyright 2026 Dhevenddra (see [`NOTICE`](NOTICE)). The boilerplate header in the\n`LICENSE` appendix (`Copyright [yyyy] [name of copyright owner]`) is a *template* for\napplying the license to source files — it is not itself a requirement, and the `LICENSE`\nfile is kept verbatim as the official Apache-2.0 text.\n",
  "bytes": 17873,
  "sha": "bcdd4daec2660ead8dd2040d4b64ace01a1c7c71459d163e4ff459d3e43fb91c",
  "repo_slug": "dhevenddra/forensic-deepdive",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dhevenddra_forensic_deepdive_49018a88/readme"
}