GitDetective — AI Code Detective

It had to be a Tuesday. I was in my repo, staring at a segmentation fault that had been there for three weeks—three weeks of innocent commits passing by like strangers in the rain. I needed answers. I needed GitDetective.

GitDetective turns your LLM into a git-history detective. Given a bug description and (optionally) a file/line, it uses tool-calling agents to search commits, blame files, inspect diffs, and cross-reference evidence—all in character as your favorite detective archetype.

---

Installation

pip install gitdetective

Or from source:

git clone https://github.com/NeuronPulse/gitdetective.git
cd gitdetective
pip install -e .

Quick Start

# Configure your API key
mkdir -p ~/.gitdetective
cat > ~/.gitdetective/config.toml << 'EOF'
[llm.openai]
api_key = "sk-..."
base_url = "https://api.openai.com/v1"
model = "gpt-4o"

[settings]
detective_style = "noir"
EOF

# Start investigating
cd your-git-repo
gitdetective investigate

Configuration

GitDetective reads ~/.gitdetective/config.toml:

[settings]
detective_style = "noir"  # noir | holmes | conan | poirot

[llm.openai]
api_key = "sk-..."
base_url = "https://api.openai.com/v1"
model = "gpt-4o"
openai_compatible = true

[llm.deepseek]
api_key = "sk-..."
base_url = "https://api.deepseek.com/v1"
model = "deepseek-chat"
openai_compatible = true

[llm.mistral]
api_key = "..."
base_url = "https://api.mistral.ai/v1"
model = "mistral-large-latest"
openai_compatible = true

[llm.custom]
api_key = "sk-..."
base_url = "https://your-provider.com/v1/chat/completions"
model = "your-model"
openai_compatible = false
# Custom request body template (optional)
request_body_template = '{"model": "{{model}}", "messages": {{messages_json}}, "temperature": {{temperature}}}'
response_path = "choices.0.message.content"
extra_headers = { "X-Custom-Header": "value" }

Active provider is the first one found (in order): openai, deepseek, mistral, custom. If no API key is configured, the tool exits with setup instructions.

Detective Styles

Style	Vibe	Sample
noir	Hardboiled black film detective	"The dame was trouble. The diff was murder. Both left their marks."
holmes	Sherlock Holmes deductive reasoning	"Elementary. The commit message is a clear misdirection."
conan	Anime-style energetic detective	"真実はいつも一つ！ The culprit is hiding in plain sight!"
poirot	Belgian methodical flair	"Ah, mon ami, let us consult the little grey cells."

Commands

gitdetective investigate

Interactive investigation. The AI agent uses 5 tools to gather evidence:

• search_commits — Search commit messages (keyword or regex: prefix)
• get_commit_detail — Full diff of a specific commit (optionally single-file)
• blame_file — Who last touched each line
• get_contributors — All contributors and their commit counts
• get_file_at_commit — File contents at a specific commit

gitdetective investigate
# → Prompts for bug description, optional file and line
# → AI streams reasoning, tool calls, and results in real-time
# → Final verdict saved as a case

gitdetective investigate -f src/main.rs -l 42
# → Skips file/line prompts, uses CLI args

gitdetective blame <file> <line>

Quick blame analysis with AI commentary:

gitdetective blame src/components/gui.jsx 589

gitdetective timeline

Last 30 commits in a table, with activity stats.

gitdetective suspect <author>

Full dossier of a contributor: commit count, date range, files touched, and AI-generated profile.

gitdetective suspect KOSHINO

gitdetective casefile <case-id>

View a saved case's metadata, suspects, evidence, and verdict.

gitdetective close

List open cases and close one by ID, with a resolution note and thematic closing monologue.

gitdetective stats

Commit leaderboard, hottest files, and investigation stats.

gitdetective reconstruct <case-id>

Generate a re-enactment script: the step-by-step commit sequence that led to the bug.

gitdetective reconstruct GD-20260404-123456 -o reconstruction.md

gitdetective --version / -V

Show version.

Case Database

All investigations are saved to ~/.gitdetective/cases.db (SQLite). Use casefile, close, stats, and reconstruct to browse and manage cases.

How It Works

 Bug Description
       │
       ▼
 ┌─────────────────┐     tool loop (up to 15 rounds)     ┌──────────────────┐
 │  AI Agent (LLM) │ ────► search / blame / diff ────►   │  Git Repository  │
 │                 │ ◄──── evidence results ◄────────    │                  │
 └─────────────────┘                                     └──────────────────┘
       │
       ▼
  Case saved ───► SQLite DB ───► casefile, stats, reconstruct

Why Not Just Use git log or git bisect?

• Deep diffs — The agent reads full diffs and suspicious pattern detection
• Cross-referencing — Connects commits, authors, and files automatically
• Narrative output — You get a compelling story, not just a SHA
• Persistent cases — Revisit, close, and reconstruct investigations

Requirements

• Python 3.10+
• A git repository
• An LLM API key (OpenAI, DeepSeek, or any OpenAI-compatible provider)

License

MIT

---

"In a city full of bugs, one detective made a difference. This is its story."