forensic-deepdive

forensic-deepdive is an Apache-2.0 command-line tool by Dhevenddra that analyzes a codebase in nine languages and builds a persistent knowledge graph, an MCP server, and five markdown artifacts for AI coding agents. The current release on PyPI is 0.10.0, listed as Development Status 3 - Alpha.

What It Is

The tool runs forensic extract against a repository and writes an embedded graph to .deepdive/graph.lbug. The graph contains File, Symbol, Module, Commit, Author, Endpoint and DbTable nodes, connected by edges such as CALLS, IMPORTS, EXTENDS, AUTHORED_BY and CO_CHANGES_WITH. Every edge carries a confidence tag: EXTRACTED, INFERRED or AMBIGUOUS. Supported languages are Python, C, Dart, Swift, TypeScript, JavaScript, Java, Go and Rust. Extraction works with no LLM API key and no network.

Outputs and Agent Integration

Five markdown artifacts are regenerated under docs/codebase/: MAP, HOTPATHS, ARCHAEOLOGY, MENTAL_MODEL and AGENT_BRIEF. Ten shims are also written into the target repo: editor rule files for Claude Code, AGENTS.md, Cursor and Continue, five Claude skills, and a plugin manifest. Existing hand-edited files are not overwritten. An optional --emit-vault flag writes an Obsidian-friendly vault.

forensic serve runs a stdio MCP server with nine composite tools: impact, context, archaeology, flow, query, record_insight, recall_insights, visualize and trace. The Endpoint join node unifies HTTP, MCP tools, registry-dispatch, gRPC and messaging protocols, so trace can follow a frontend call to its backend handler.

Setup Path

Install with uv tool install forensic-deepdive or pip install forensic-deepdive, run forensic extract /path/to/repo, then wire the server through a Claude Code plugin, the MCP Registry, or a manual config snippet. Optional extras add offline semantic query, an interactive REPL and terminal browser, OpenAPI YAML parsing, and a Graphiti temporal insight backend.

Current Status

The README describes v0.10.0 as an integrity release focused on upgrade convergence and stale-shim detection, and adds forensic extract --timings. The maintainer states it is an assisted-analysis tool and that faster autonomous issue resolution is not yet proven.