# forensic-deepdive

> Persistent code knowledge graph and MCP server that gives AI coding agents forensic understanding of a codebase, with confidence-tagged edges and markdown artifacts.

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.

## Features
- Persistent embedded code knowledge graph with confidence-tagged edges (EXTRACTED/INFERRED/AMBIGUOUS)
- MCP server with 9 composite tools
- Cross-stack tracing via Endpoint join node across HTTP, MCP, registry-dispatch, gRPC and messaging
- Five markdown artifacts: MAP, HOTPATHS, ARCHAEOLOGY, MENTAL_MODEL, AGENT_BRIEF
- Git archaeology: churn, top authors, bus factor, co-change clusters
- Agent insight layer with record_insight and recall_insights
- Ten shims for Claude Code, Cursor, Continue and AGENTS.md
- Mermaid diagram generation
- Optional Obsidian vault export
- Interactive REPL and terminal graph browser
- Runs with no LLM or network
- Supports 9 languages

## Integrations
Claude Code, Cursor, Codex, Continue, Cline, Windsurf, VS Code/Copilot, MCP Registry, Obsidian, Graphiti

## Platforms
WEB, API, VSC_EXTENSION, CLI

## Pricing
Open Source

## Version
0.10.0

## Links
- Website: https://pypi.org/project/forensic-deepdive/
- Documentation: https://github.com/Dhevenddra/forensic-deepdive/blob/main/docs/install.md
- Repository: https://github.com/Dhevenddra/forensic-deepdive
- EveryDev.ai: https://www.everydev.ai/tools/forensic-deepdive