Every codebase has ghosts.
A mysterious delay. A workaround nobody remembers adding. A function that behaves strangely, with a comment that explains nothing.
The code is still there. The context is gone.
When that happens, we usually start digging through commits, running git blame, searching old messages, and trying to reconstruct what someone was thinking months ago.
I built RepoGhost to make that investigation more systematic.
👻 What is RepoGhost?
RepoGhost is a terminal-first Python CLI that investigates suspicious code by gathering evidence from Git history.
Instead of asking an AI to guess why a line exists, RepoGhost first collects the history surrounding it: relevant commits, line attribution, diffs, related files, and potential tests. You can then inspect that evidence yourself or optionally ask a local language model to help interpret it.
Think of it as a ghost hunter for forgotten Git history.
🔍 What can it investigate?
RepoGhost brings several investigation steps into one workflow:
- Line-level history: Investigate a suspicious file and line range, then examine the relevant Git history and blame attribution.
- Commit context: Inspect commit metadata and diffs to understand how code changed.
- Historical search: Search Git history for relevant terms that might explain a strange implementation or old workaround.
- Related tests: Discover candidate test files that could help reproduce or investigate a suspected regression.
-
Working-tree awareness: Distinguish the current working tree from committed code at
HEAD, so uncommitted changes aren't confused with historical evidence. - Structured evidence: Export findings to JSON for further inspection, automation, or AI-assisted analysis.
- Optional local AI explanations: Use Ollama with a model such as Qwen2.5:3B to help turn the collected evidence into a readable explanation.
The important part is that the AI explanation is optional. The core investigation is useful without a model or a paid hosted AI API.
🧪 Try it on a real Git repository
After installing RepoGhost and making the CLI available, run:
repoghost inspect cache.py:1-12 --repo C:\path\to\repository --json-out evidence.json
Replace the repository path and file range with the code you want to investigate.
RepoGhost gathers the relevant evidence and writes a JSON report that you can inspect or pass to the optional explanation step.
For a reproducible demonstration, the repository also includes a fixture script that creates a small Git repository with a deliberately introduced bug. You can use it to see how historical changes and tests help reveal the problem without experimenting on your actual project.
Check the README for installation and usage instructions.
🤖 Why not just ask an AI chatbot?
That's a fair question. AI coding assistants can explain code, suggest fixes, and help debug problems. Git itself already provides excellent tools for examining history.
RepoGhost isn't trying to replace either.
Its focus is the gap between finding suspicious code and gathering enough historical context to investigate it properly.
A general-purpose chatbot may explain what a function does today. But understanding why a developer introduced a workaround, changed a condition, or modified a test can require historical evidence that isn't present in the current source file.
RepoGhost makes that evidence-gathering process explicit:
- Identify the file and line range you're investigating.
- Gather relevant Git history, blame information, diffs, and candidate tests.
- Inspect the evidence and follow the leads that matter.
- Optionally use a language model to help summarize the findings.
The result is a more inspectable starting point for debugging—not a promise that every mystery will be solved automatically.
🧠 The important lesson: citations aren't proof
I also wanted the AI-assisted part to be more than a prompt wrapped around a Git command.
RepoGhost checks AI citations against references present in its evidence report, such as commit hashes, paths, and line references. That helps catch citations that point to nonexistent evidence.
But there's a catch: a valid citation doesn't guarantee a valid conclusion.
During local testing, the model produced unsupported claims even when its citations referred to real evidence. A citation can exist without actually supporting the statement attached to it.
That distinction matters. Citation validation can improve traceability, but it cannot prove that an explanation is factually correct.
For that reason, RepoGhost treats AI output as a set of hypotheses to verify—not as an authoritative verdict. The underlying evidence remains available for the developer to inspect.
I think that is a more useful way to build AI-assisted developer tools: make the reasoning easier to examine instead of asking users to trust a confident answer.
🔒 Why local-first?
Repository history can contain internal implementation details, security fixes, and context that developers may not want to send to a remote inference service.
RepoGhost's core investigation runs locally against a Git repository. Its optional AI explanation uses Ollama, allowing you to run a compatible model on your own machine.
In this configuration, the repository context can stay local rather than being sent to a remote inference provider. Local execution still depends on your machine and configuration, but it avoids requiring a hosted AI service for the main workflow.
That also means you can investigate Git history without making AI a mandatory dependency.
🛠️ Built with
- Python for the CLI and investigation workflow
- Git for commit history, blame, diffs, and repository context
- Ollama + Qwen2.5:3B for optional local explanations
-
Python
unittestfor automated tests - GitHub Actions for continuous integration
The current local test suite passes 37 tests. I also tested the CLI against a generated Git fixture, including inspection and JSON export.
Those checks don't prove the tool is perfect, but they give me a repeatable baseline as I continue improving it.
🚀 What's next?
RepoGhost is a focused starting point, and there are several directions I'd like to explore:
- Smarter discovery of relationships between suspicious changes and relevant tests
- Better ways to assess whether an AI claim is actually supported by its cited evidence
- Language-aware symbol and test discovery
- IDE integration for investigating a suspicious line without leaving the editor
- Developer-approved agent workflows that can gather evidence and propose next steps while keeping humans in control
The goal isn't to automate every debugging decision. It's to reduce the time spent reconstructing context so developers can spend more time solving the actual problem.
👩💻 Who might find it useful?
RepoGhost is especially relevant when you're:
- Debugging a regression in an older codebase
- Trying to understand a workaround added by someone else
- Onboarding to a repository with limited documentation
- Reviewing a change and wondering what led to it
- Contributing to an open-source project with a long commit history
If you've ever found a suspicious line and thought, "Who wrote this, and what were they trying to fix?"—you already understand the problem.
🎃 Built for Hacktoberfest Week 4
RepoGhost is my entry for the Hacktoberfest Open-Source AI Challenge — Week 4: Ghost in the Machine.
This project gave me an opportunity to explore a practical intersection of Git tooling, local language models, evidence collection, and responsible AI-assisted development.
One of my biggest takeaways is that adding a model is often the easy part. Designing a workflow that makes its output inspectable—and being honest about what the model still gets wrong—is much harder.
I'd love feedback on how RepoGhost could make historical debugging more useful without becoming another tool that produces answers developers can't verify.
🔗 Repository: github.com/kushal-pandey/RepoGhost(https://github.com/kushal-pandey/RepoGhost)
If you try it, I'd be interested to hear which part of investigating Git history you find most tedious—and what you'd want a tool like this to do next.
Built with Python, Git, and optional local AI.
Top comments (0)