Setup guide
Repo Atlas runs on your own computer. One command installs and starts it; a model is optional and you bring your own: Ollama on your machine, or Claude with your API key.
Install and run
You need Node 18 or newer and git. Then run:
npm create repo-atlas
The first run takes a minute or two: it downloads the app and its Python packages through uv. If uv isn't installed, Repo Atlas asks before installing it, or prints the one-line install command. Later runs start in seconds.
When it's ready, the terminal shows where it is running and your browser opens it:
Repo Atlas 0.1.1
Open http://127.0.0.1:47821
Model Ollama · qwen3.6:35b
Data ~/.repo-atlas
Press Ctrl+C to stop.
If port 47821 is taken, the next free one is used. Press Ctrl+C in the terminal to stop it. To update to the newest version, run npm create repo-atlas@latest.
Read a repository
- Paste a GitHub URL on the home screen, like
https://github.com/pallets/itsdangerous, and press Read repo. - Follow the stages: Clone, Extract graph, Build layers, Name parts, Index for search. A small library takes about a minute with a local model; a large application takes longer.
- Open it: the five-layer stack, the mind map, and Ask in the side panel.
Public repositories only, default branch. A repository is read once and kept. Paste the same URL again to pick up new commits (nothing is redone if the branch hasn't moved). To rebuild anyway: npm create repo-atlas -- ingest <url> --refresh.
Connect a model
A model writes the names and descriptions of the top two layers and the answers to your questions. Choose it in Settings (the gear at the top right of the app):
- Auto
- Claude if an API key is set, otherwise the best model installed in Ollama. The default.
- Ollama
- A model on your computer. Nothing leaves your machine.
- Claude
- Anthropic's API with your own key. Your question and the related code are sent to Anthropic.
- None
- Maps and search still work; questions return the related places in the code without a written answer.
Press Save and test to check the connection. Maps already read keep the names they were made with; new answers use the new model.
Ollama (local)
- Install Ollama from ollama.com/download and start it.
- Pull a chat model. Bigger answers better; pick what your machine can run:
ollama pull qwen3.6:35b # best answers, needs a strong machine ollama pull qwen2.5-coder:7b # lighter, for most laptops - Pull the embedding model, which lets search find code by meaning and not only by name:
ollama pull nomic-embed-text-v2-moe - Restart Repo Atlas, or press Save and test in Settings.
With Auto, Repo Atlas picks the first of these that is installed: qwen3.6:35b, qwen2.5-coder:32b, qwen2.5:32b, ministral-3:8b, qwen2.5-coder:7b, otherwise any installed chat model. To use a different one, choose it under Ollama → Model in Settings. If Ollama runs on another address, set it there too, or start with ATLAS_OLLAMA_URL.
Claude API key
- Create a key at console.anthropic.com. Usage is billed to your Anthropic account.
- In Settings choose Claude, paste the key, pick the model (Claude Opus 5.5 by default, or Sonnet 5.5 or Haiku 5.5) and press Save and test.
Or set it only for this session, without saving it:
ANTHROPIC_API_KEY=sk-ant-... npm create repo-atlas
- A saved key lives only in
~/.repo-atlas/config.json, readable by you alone, and is sent only to Anthropic. The app never shows it again, only its last four characters. Remove saved key deletes it. - A key in
ANTHROPIC_API_KEYwins over a saved one and is never written to disk. - Meaning-based search still uses Ollama's embedding model when it's installed; with Claude alone, search matches names and words.
Command line
Everything after -- goes to Repo Atlas.
| Command | What it does |
|---|---|
npm create repo-atlas | Start the app and open it in the browser. |
npm create repo-atlas -- serve --port 8080 --no-open | Start on a chosen port, without opening the browser. |
npm create repo-atlas -- ingest <github-url> | Read a repository without the app. --refresh rebuilds it, --no-model skips names, descriptions and the search index. |
npm create repo-atlas -- ask <repo-id> "question" | Ask in the terminal. --node <id> asks about one part. The repo id looks like pallets__itsdangerous. |
npm create repo-atlas -- status | Show the connected model and the repositories you have read. |
npm create repo-atlas -- --version | Print the version. |
Environment variables
| Variable | Default | Use |
|---|---|---|
ANTHROPIC_API_KEY | none | Claude key for this session; wins over a saved key. |
ATLAS_DATA | ~/.repo-atlas | Where maps, cloned code and settings are kept. |
ATLAS_PORT | 47821 | First port to try. |
ATLAS_OLLAMA_URL or OLLAMA_HOST | http://127.0.0.1:11434 | Where Ollama is running. |
ATLAS_CHAT_MODEL | best installed | Ollama chat model to use. |
ATLAS_EMBED_MODEL | nomic-embed-text-v2-moe | Ollama embedding model for meaning-based search. |
ATLAS_LANG | en | Language of model-written names and answers: en or ko. |
Local API
The app is a small web server on your computer, and everything the screen does is available at http://127.0.0.1:47821/api. It answers only requests from your own machine (other websites in your browser are refused).
| Request | Returns |
|---|---|
POST /api/repos {"url": "…"} | Starts reading a repository. |
GET /api/repos, GET /api/repos/{id} | The repositories you've read, with progress and layer counts. |
GET /api/repos/{id}/layers/{0-4} | One layer's parts and the calls between them. |
GET /api/repos/{id}/branch?rel=inside|calls|callers&node= | One branch of the mind map. |
GET /api/repos/{id}/node?node= | One part: description, code, GitHub link, callers and callees. |
GET /api/repos/{id}/search?q= | Parts matching words or meaning. |
POST /api/repos/{id}/ask | An answer with numbered sources (streamed as server-sent events, or "stream": false for one JSON reply). |
GET /api/settings, PUT /api/settings | The model settings (a saved key is never returned). |
GET /api/health | Version, data folder and connected model. |
For example:
curl -s http://127.0.0.1:47821/api/repos/pallets__itsdangerous/ask \
-H 'content-type: application/json' \
-d '{"question": "Which error is raised when a timed signature is too old?", "stream": false}'
Your data
Everything lives in ~/.repo-atlas: atlas.db (the maps), repos/ (the cloned code) and config.json (settings). No account, nothing sent anywhere except to Claude when you choose it. Delete a repository from the home screen; to remove Repo Atlas completely, delete that folder.
How accurate is it
The bottom three layers (symbols, files, folders) and every arrow come straight from the code: Graphify parses it on your computer. The top two layers are grouped from the folders, and only their names and descriptions are written by the model. Answers use only the code they're given and number every source.
We measured it on two repositories, with a local Ollama model (qwen3.6:35b):
| fastapi/full-stack-fastapi-template | pallets/itsdangerous | |
|---|---|---|
| Arrows confirmed in the source | 766 of 768 | 178 of 178 |
| Calls in the code that have an arrow | 194 of 194 | 48 of 52 |
| Answers with the right facts | 11 of 12 | 5 of 5 |
| Questions about things not in the repo, answered "not there" | 2 of 2 | 1 of 1 |
| Citations to sources that don't exist | 0 | 0 |
Limits worth knowing: calls made dynamically (by name in a string, through dependency injection containers) can't be seen by a parser; very large repositories show the most connected parts first; private repositories aren't supported yet. The scripts behind these numbers are in evals/.
Troubleshooting
- "Repo Atlas runs on uv … Install uv now?"
- Answer yes, or install it yourself with
curl -LsSf https://astral.sh/uv/install.sh | sh(on Windows:powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex") and run the command again. - "Repo Atlas needs git"
- Install git (on a Mac:
xcode-select --install), then run again. - The top bar says "Connect a model"
- Ollama isn't running or has no chat model. Start Ollama,
ollama pulla model, and press Save and test. Or add a Claude key. - Answers are slow
- A local model answers in about 10–15 seconds on a strong machine. Pick a smaller Ollama model, or use Claude.
- An answer says the sources don't cover it
- Search didn't find the right code. Open the part you're asking about first (questions then go to it), or ask with words that appear in the code.
- Port already in use
- The next free port is used automatically; or choose one with
-- serve --port 8080.