This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine
What I Built
RepoSeance is an open-source, local-first AI codebase archaeologist that helps developers understand unfamiliar repositories, investigate forgotten implementation decisions, and reconstruct the history behind software projects.
Every codebase has a story.
Behind every function, module, and architectural decision, there is a history of experiments, refactoring, bug fixes, and sometimes abandoned ideas. Unfortunately, much of that context gets lost as projects grow and developers move on.
I wanted to build something that could help developers uncover that hidden history.
That's how RepoSeance was born.
RepoSeance combines source-code analysis, Git history investigation, and Retrieval-Augmented Generation (RAG) to let developers ask questions about their repositories and receive AI-generated answers supported by source-code and Git evidence.
✨ Key Features
- 🔍 Repository Archaeology: Analyze TypeScript/JavaScript projects, discover project structure, and extract symbols, imports, and exports.
- 🕰️ Git History Investigation: Explore commit history, blame information, and implementation evolution.
- 🧠 Local AI Question Answering: Ask natural-language questions about your codebase using locally running open-weight models.
- 📚 Evidence-Backed Answers: Get answers with source-file and line references.
- 💬 Interactive Terminal Chat: Have a conversational experience with your repository.
- 🔒 Privacy-First Architecture: Keep repository analysis and AI inference local through Ollama.
- ⚡ CLI Experience: Investigate repositories directly from your terminal without needing a web dashboard or cloud AI service.
The idea is simple: instead of manually digging through hundreds of files and commits, let RepoSeance help you investigate the history of your codebase.
Demo
RepoSeance is available as an npm package.
Install it:
npm install -g reposeance
Or run it with npx:
npx reposeance
You'll need Node.js 22+, Git, and Ollama installed and running.
Try it yourself
# Navigate to an existing repository
cd your-project
# Initialize RepoSeance
reposeance init
# Index the repository
reposeance index
# Ask a question about your codebase
reposeance ask "What does this repository do?"
# Investigate a specific module
reposeance history src/features/auth
# Start an interactive conversation
reposeance chat
For example, you can ask questions like:
- How does authentication work in this project?
- Which modules are responsible for database operations?
- What is the history of this particular feature?
- Where should I look to understand a particular implementation?
Try the package: https://www.npmjs.com/package/reposeance
Code
RepoSeance is open source under the MIT License.
- GitHub Repository: https://github.com/CodesWithSubham/reposeance
- npm Package: https://www.npmjs.com/package/reposeance
Contributions, feedback, and suggestions are welcome!
How I Built It
I built RepoSeance using TypeScript and Node.js, with a modular architecture designed to keep repository analysis independent of the AI layer.
Technology Stack
| Technology | Purpose |
|---|---|
| TypeScript | Type-safe application development |
| Node.js | CLI runtime |
| Commander.js | Command-line interface |
| Ollama | Local LLM inference |
| Gemma | Open-weight language models |
| MiniSearch | Lightweight local search and retrieval |
| simple-git | Git history investigation |
| TypeScript Compiler API | Source-code analysis |
| Zod | Runtime validation |
| Vitest | Testing |
How the AI Works
One of the important architectural decisions was to avoid sending the entire repository directly to an LLM.
Instead, RepoSeance follows a retrieval-based approach.
- Repository Discovery: Identify the Git repository and discover relevant source files.
- Code Analysis: Analyze source files and extract useful structural information.
- Git Archaeology: Collect commit history and historical implementation context.
- Local Indexing: Store searchable repository information locally using MiniSearch.
- Context Retrieval: Retrieve relevant code and historical evidence for a user's question.
- AI Inference: Pass the selected context to a locally running model through Ollama.
- Evidence Validation: Validate generated source references against the indexed repository before presenting them.
This approach keeps the context focused and makes answers more useful than simply asking an LLM to guess how a repository works.
Why Ollama and Gemma?
I wanted RepoSeance to be genuinely local-first.
By using Ollama for inference and Gemma as an open-weight model family, developers can run AI-powered repository investigations without depending on a hosted AI API.
The model is configurable, so users can choose a model that suits their available hardware.
Why Does Open Innovation Matter?
Open innovation is particularly important for a tool that analyzes source code.
Developers frequently work with private repositories, internal projects, and proprietary software. Requiring them to upload their entire codebase to a third-party AI service creates unnecessary privacy and security concerns.
Using open-weight models and local inference makes a different approach possible.
With RepoSeance:
- Developers can run inference on their own machines.
- Repository contents do not need to be uploaded to a hosted AI provider.
- Users can choose and configure their own compatible models.
- The tool does not depend on proprietary AI APIs or API keys.
- The project itself remains open for inspection, modification, and contributions.
Open innovation also gives developers more control over the technology powering their tools.
For RepoSeance, this isn't just a cost-saving decision. It's part of the product philosophy.
The Spirit of It 👻
The most interesting thing about software repositories is that they contain more than code.
They contain decisions.
A developer might introduce a function to solve a problem, another developer might refactor it months later, and someone else might remove the feature entirely.
Eventually, the original developers may leave, documentation becomes outdated, and the reasoning behind certain implementations disappears.
But traces of that history remain in the repository.
Commit messages, changed files, source code, and implementation patterns all tell pieces of the story.
I wanted RepoSeance to bring those pieces together and make them easier to explore.
Because sometimes, understanding a codebase means talking to the ghosts of the developers who built it.
Every codebase has a story worth uncovering.
What's Next?
RepoSeance is an evolving open-source project.
Some areas I'd like to explore next include:
- Semantic search using local embedding models.
- Better understanding of architectural relationships.
- More advanced historical decision reconstruction.
- Improved investigation workflows.
- IDE integrations.
I'd love to hear how other developers approach understanding unfamiliar or inherited codebases.
If you find the idea interesting, give the project a try, share feedback, or contribute!
RepoSeance — Talk to the ghosts of your codebase. 👻
Top comments (0)