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

  1. Paste a GitHub URL on the home screen, like https://github.com/pallets/itsdangerous, and press Read repo.
  2. 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.
  3. 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)

  1. Install Ollama from ollama.com/download and start it.
  2. 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
  3. Pull the embedding model, which lets search find code by meaning and not only by name:
    ollama pull nomic-embed-text-v2-moe
  4. 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

  1. Create a key at console.anthropic.com. Usage is billed to your Anthropic account.
  2. 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_KEY wins 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.

CommandWhat it does
npm create repo-atlasStart the app and open it in the browser.
npm create repo-atlas -- serve --port 8080 --no-openStart 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 -- statusShow the connected model and the repositories you have read.
npm create repo-atlas -- --versionPrint the version.

Environment variables

VariableDefaultUse
ANTHROPIC_API_KEYnoneClaude key for this session; wins over a saved key.
ATLAS_DATA~/.repo-atlasWhere maps, cloned code and settings are kept.
ATLAS_PORT47821First port to try.
ATLAS_OLLAMA_URL or OLLAMA_HOSThttp://127.0.0.1:11434Where Ollama is running.
ATLAS_CHAT_MODELbest installedOllama chat model to use.
ATLAS_EMBED_MODELnomic-embed-text-v2-moeOllama embedding model for meaning-based search.
ATLAS_LANGenLanguage 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).

RequestReturns
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}/askAn answer with numbered sources (streamed as server-sent events, or "stream": false for one JSON reply).
GET /api/settings, PUT /api/settingsThe model settings (a saved key is never returned).
GET /api/healthVersion, 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-templatepallets/itsdangerous
Arrows confirmed in the source766 of 768178 of 178
Calls in the code that have an arrow194 of 19448 of 52
Answers with the right facts11 of 125 of 5
Questions about things not in the repo, answered "not there"2 of 21 of 1
Citations to sources that don't exist00

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 pull a 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.