-
-
Cdebase Archaeologist
Codebase Archaeologist
Inspiration
Understanding an unfamiliar codebase is often harder than writing new code.
When working with existing projects, a developer may need to answer questions such as:
- Where does the application start?
- Which component contains the core logic?
- What happens if I change this function?
- Which files depend on this module?
- How has this part of the project changed over time?
Normally, answering these questions requires manually searching through files, tracing relationships, reading documentation, and inspecting Git history.
I wanted to explore whether an AI-assisted tool could make this process more systematic.
The important idea behind Codebase Archaeologist was that an LLM should not simply be asked to "understand the repository" and generate an answer from assumptions. Instead, the system should first analyze the repository, retrieve relevant evidence, and then use an LLM to reason about that evidence.
What It Does
Codebase Archaeologist is a CLI-based developer tool for investigating and understanding unfamiliar codebases.
It provides commands for:
- 🔍 Scanning repositories
- 🔎 Searching for symbols and code
- 📄 Explaining files
- 🤖 Asking questions about a repository
- 🧭 Tracing relationships between files
- 💥 Analyzing the potential impact of changes
- 📜 Inspecting Git history
- 📊 Producing structured output
The central workflow is:
Repository → Deterministic Analysis → Evidence Retrieval → LLM Reasoning → Grounded Response
Rather than making the LLM responsible for discovering everything about the repository, the analysis layer first retrieves relevant information. The LLM is then used for higher-level interpretation and explanation.
How We Built It
The project uses a hybrid architecture.
🦀 Rust
Rust is used for performance-sensitive repository analysis and core code-processing functionality.
🐍 Python
Python handles the CLI, orchestration, and integration between the analysis layer and the reasoning system.
🤖 LLM Integration
The project supports configurable LLM providers and can connect to models through compatible APIs and providers such as OpenRouter.
The reasoning layer receives repository evidence and generates answers based on that context.
📂 Git Integration
Git information can also be inspected to help developers understand the history and evolution of a repository.
The resulting system is designed as a developer-facing command-line tool, rather than a visual dashboard. This was intentional: the primary workflow is repository exploration directly from the terminal.
Challenges We Ran Into
1. Avoiding Unsupported AI Answers
One of the biggest challenges was preventing the system from producing confident explanations without sufficient repository evidence.
Early testing showed why simply connecting an LLM to a repository question is not enough. The quality of the answer depends heavily on whether the correct files and information are retrieved first.
This led to a stronger separation between:
- Deterministic analysis and retrieval
- LLM reasoning and explanation
The goal became to make the LLM reason from evidence rather than treat it as a source of repository facts.
2. Working With Different Repositories
A repository can contain many unrelated files, generated files, documentation, source code, configuration, and dependencies.
Retrieval therefore becomes an important problem: finding some matching file is not enough if that file does not actually answer the user's question.
We tested the tool against both demo repositories and a separate real-world project, Ultimate XOXO, to see how it behaved outside the project's own controlled examples.
3. LLM Provider Configuration
Supporting real LLM usage introduced another challenge: different providers use different model names, endpoints, and authentication mechanisms.
Instead of permanently tying the project to one model, the reasoning architecture was designed to support configurable providers.
This also made it possible to distinguish between deterministic/mock mode, useful for testing, and real LLM mode, used for actual AI-powered reasoning.
4. Keeping the Tool CLI-First
An earlier direction considered presenting the project through a website or visual interface.
I decided against that approach.
The project is fundamentally a developer tool, and forcing repository investigation into a graphical dashboard would add unnecessary complexity. A CLI makes it easier to use the tool directly against local repositories and integrate it into a developer workflow.
What I Learned
This project taught me that building an AI-powered developer tool is not primarily about connecting an API to a prompt.
The difficult parts are often:
- Retrieving the correct context
- Structuring evidence
- Separating deterministic facts from AI interpretation
- Handling insufficient evidence
- Designing useful CLI workflows
- Supporting multiple repositories
- Integrating external LLM providers without tightly coupling the architecture to one model
I also learned more about combining Python and Rust within the same project, designing provider abstractions, working with Git programmatically, and testing an AI system against repositories it was not specifically built around.
What's Next
Future improvements could include:
- More language-aware analysis
- Improved dependency and relationship detection
- Better retrieval and ranking
- Additional LLM providers
- More detailed impact analysis
- Stronger repository indexing for larger projects
The current version is an exploration of a simple idea:
Before asking AI to explain a codebase, first give it evidence from the codebase.
Links
🎥 Project Demo:
https://youtu.be/85zgZa3wYRs
💻 GitHub Repository:
https://github.com/White-Reaper0/Codebase-Archaeologist
Log in or sign up for Devpost to join the conversation.