-
-
Homepage
Inspiration
One of the most frustrating parts of working on mature software is inheriting code that nobody fully understands anymore. Git history tells you who changed something, documentation explains what it does, but neither answers the question that matters most before making a change:
Why does this code exist?
That idea inspired Repo Archaeologist. Instead of building another AI coding assistant that explains code, I wanted to build one that reconstructs the historical reasoning behind it using evidence from the repository itself.
What it does
Repo Archaeologist investigates a specific piece of code and explains why it exists.
Given a repository, target file, symbol, and question, it analyzes Git history, blame information, commits, tests, repository metadata, and code structure to reconstruct the evolution of that behavior.
Instead of producing a generic AI summary, every explanation is grounded in repository evidence. The application also separates verified facts from inference and links conclusions back to the supporting commits, tests, and source files so developers can verify every important claim.
How we built it
Repo Archaeologist is built in Python with a Streamlit interface.
The investigation pipeline combines deterministic repository analysis with GPT-5. The application first collects evidence from Git history, blame, tests, symbols, repository metadata, and code analysis. Only after that evidence has been collected does GPT-5 synthesize it into a structured explanation.
Throughout development I relied heavily on Codex as an engineering assistant. It helped implement features, generate tests, refactor components, debug difficult state-management issues, and iterate on the user interface. Rather than replacing development, it accelerated it and let me spend more time improving the architecture and user experience.
Challenges we ran into
The biggest challenge was making the explanations trustworthy instead of simply convincing.
Early versions produced summaries that sounded reasonable but weren't always well supported by repository evidence. I redesigned the investigation pipeline so evidence is always collected first and major conclusions are traceable back to commits, tests, or source code.
Another challenge was managing complex Streamlit session state while supporting repeated investigations, prepared demonstrations, and custom repositories without stale application state leaking between workflows.
Accomplishments that we're proud of
The accomplishment I'm most proud of is building a workflow that explains why code exists instead of only describing what it does.
I'm also proud that every important conclusion is backed by repository evidence rather than unsupported AI reasoning. Seeing the application successfully investigate a real project like Flask and reconstruct meaningful historical decisions made the idea feel genuinely useful.
What we learned
This project reinforced that AI becomes significantly more useful when it's grounded in reliable evidence instead of being asked to speculate.
I also learned how valuable Codex can be as a development partner. It accelerated implementation, testing, debugging, and iteration, while still requiring engineering judgment to design the overall architecture and validate the final result.
What's next for Repo Archaeologist
The next step is expanding the range of repository evidence that can be incorporated into investigations, including pull requests, issue trackers, CI history, and richer semantic code analysis.
I'd also like to improve experiment generation, support larger repositories, and make Repo Archaeologist easier to integrate into existing developer workflows so it can become a practical tool for understanding and maintaining legacy software.
Log in or sign up for Devpost to join the conversation.