Skip to content

About

Local codebase Q&A agent — browse any public GitHub repo and chat with the code. Runs 100% locally via Ollama + ChromaDB, no paid APIs.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

5 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

CodeWalker

CodeWalker is a local retrieval augmented generation tool for exploring public GitHub repositories. You give it a repo URL, it fetches and indexes the source, and you ask it plain English questions about the code. It answers with a real explanation and cites the exact file.py:42 locations it used, so you can jump straight to the source.

Everything runs on your machine through Ollama. No data leaves your device, no cloud AI service is called, no API keys are required, and there are no ongoing costs.

What it actually does

CodeWalker is not a chatbot with a repo pasted into its context window. It builds a real search index over the codebase and runs a multi step agent loop to answer each question:

  1. Paste a GitHub URL and click Index. CodeWalker fetches the file tree and file contents through the GitHub REST API, no git clone happens.
  2. Each file is split into chunks. Source files are split at function and class boundaries using tree sitter, so a chunk is a whole function or class rather than an arbitrary slice of lines. Files without a supported grammar fall back to overlapping token windows.
  3. Every chunk is embedded into a vector and stored in a local ChromaDB collection, one collection per repo.
  4. When you ask a question, an agent plans up to three distinct search queries covering different angles such as implementation, callers, and data model. Each query is embedded and matched against the vector store, the results are merged and ranked by distance, and the top chunks become the context for the answer.
  5. The language model writes the answer from that context, streaming tokens back to the chat panel with inline citations. If the model says it lacks context, the agent extracts the missing topic, searches again, and retries up to three times before giving up.

Every stage, planning, searching, reading, and synthesizing, is shown live in the chat panel, and the exact source chunks used for each answer are listed underneath it.

Models

CodeWalker uses two open weight models, both served locally through Ollama:

  • granite-code:8b-instruct. An 8 billion parameter instruction tuned code model from IBM, released under Apache 2.0. It reads the retrieved code context and writes the answer.
  • nomic-embed-text. An embedding model from Nomic AI that converts code chunks and questions into vectors so the vector store can find semantically similar content.

Both models are configured as single constants in backend/agent.py and backend/ingestion.py, so either can be swapped for a different Ollama model with a one line change.

Prerequisites

Install Ollama. It is the only thing you need before running CodeWalker.

brew install ollama

Run

./start.sh

On first run this will create a Python virtual environment and install backend dependencies, install frontend dependencies, pull both models from Ollama, and start the backend and frontend servers.

Then open http://localhost:3000.

Usage

  1. Paste any public GitHub URL in the topbar, for example https://github.com/tiangolo/fastapi.
  2. Click Index to fetch the repo and build the local search index. This takes about one to two minutes for a typical repo.
  3. Click Ask AI or press ⌘K to open the chat panel.
  4. Ask anything about the code. Answers stream back with clickable citations that jump to the exact line.

Any public repository works. The default branch is resolved automatically, whether it is main, master, trunk, or anything else. Over 45 file extensions are indexed, and there is no cap on repo size by default, so very large repos will simply take longer to index.

No files are ever cloned or written to disk on your machine. Repo content is fetched over HTTPS from the GitHub API and embedded directly in memory.

Optional configuration

Variable Purpose
GITHUB_TOKEN Raises the GitHub API rate limit from 60 to 5,000 requests per hour
CODEWALKER_MAX_FILES Caps the number of files indexed per repo. Default is 0, meaning unlimited. Set a number to speed up indexing on very large repos

Stack

Layer Tech
Frontend Next.js, TypeScript, Tailwind CSS, Shiki
Backend FastAPI, Python
LLM granite-code:8b-instruct via Ollama
Embeddings nomic-embed-text via Ollama
Vector store ChromaDB, stored locally in backend/chroma_db/

About

Local codebase Q&A agent — browse any public GitHub repo and chat with the code. Runs 100% locally via Ollama + ChromaDB, no paid APIs.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages