0.0.6 • Published 2d ago

@repolore/core

Licence

MIT

Version

0.0.6

Deps

Size

289 kB

Vulns

Weekly

Summary Dependency Versions

repolore

Point it at a codebase, chat with it. repolore walks a repo, chunks it (code-aware for source, header-aware for docs), embeds the chunks into a local vector store, auto-generates a system prompt describing the project, and lets you ask questions about the codebase with retrieval-augmented context.

Fully local-first by default — no cloud dependency, no account, no API key required — but usable with cloud LLM providers (Anthropic, OpenAI) if you want them, and self-hostable as a server + web GUI for remote/team use.

Full documentation: docs/ — getting started, CLI reference, providers, doc-gen, web GUI, remote mode, config file reference, architecture, troubleshooting. This README is a quick tour; docs/ is the deep reference.

Status

Actively developed, pre-1.0. Local-mode CLI usage is the most-exercised path.

Known gap: the OpenAI provider is implemented and unit-tested, but hasn't been verified against a real OpenAI API yet. Anthropic and Ollama have both been verified live (real chat calls, real tool-use calls, real doc-gen runs). Treat OpenAI as "should work, unconfirmed."

Install

npm install -g repolore

That's the CLI. If you also want the web GUI (repolore serve), install the optional add-on too:

npm install -g repolore-gui

Requirements: Node.js >= 20. Ollama running locally if you want the zero-config, zero-cost default — embedding, chat, and doc-gen all work fully offline via Ollama with no API key. Otherwise, have an Anthropic or OpenAI API key ready.

Quick start

repolore init

An interactive wizard: pick the repo to index, choose folders to exclude, pick a provider/model (smart defaults if Ollama's detected running), then kicks off the first index automatically.

repolore list
repolore chat <repo-id>                    # interactive REPL
repolore chat <repo-id> "what does this do?"   # one-shot

Prefer to skip the wizard? repolore index <path-or-git-url> does the same indexing step directly, non-interactively.

CLI commands

init                       Interactive setup wizard — guided first-time walkthrough
index <path-or-git-url>    Index a repo (local path or git URL)
  --generate-docs             run an agentic doc-gen pass first (see below)
  --full                      force a full re-index instead of diffing against the last one
list                       List indexed repos
remove <repo-id>           Remove an indexed repo
chat <repo-id> [message]   Chat with an indexed repo — REPL if no message given, one-shot otherwise
watch <repo-id>            Watch a repo's local directory and auto-reindex on save
settings                   Interactive menu for provider/model, doc-gen, exclude patterns, server access
settings get/set <key> [value]   Same settings, scriptable
config get/set <key> [value]     This CLI install's own config (mode, serverUrl, apiKey for remote mode)
serve                      Start the server + web GUI from one process (needs repolore-gui)

Re-indexing an already-indexed repo diffs against the last index (git-diff-based if the repo is git, content-hash-based otherwise) — only changed files get re-chunked and re-embedded. --full forces a complete re-index.

Providers

Every capability that calls an LLM — embedding, chat, and the optional doc-gen pass — is independently configurable, via repolore settings (interactive) or repolore settings set:

repolore settings set embedding.provider ollama
repolore settings set chat.provider anthropic
repolore settings set chat.model claude-sonnet-5
repolore settings set docgen.provider anthropic
repolore settings set docgen.model claude-haiku-4-5

ollama is the default everywhere — zero config, zero cost, fully offline. anthropic and openai are available for any capability if you want a more capable (and non-free) model — most useful for the doc-gen pass, see below.

Cloud provider API keys: set ANTHROPIC_API_KEY/OPENAI_API_KEY as env vars, or run repolore settings and pick "API keys" — either works, env vars always take precedence. repolore init/settings also prompt for a key inline the first time you pick a cloud provider that doesn't have one yet.

Doc-gen (`--generate-docs`)

For repos that aren't already well-documented, --generate-docs runs an agentic pass before indexing: an LLM (using whichever provider/model is configured for docgen) walks the repo with a small, sandboxed toolset (list a directory, read a file, semantic-search the existing index, write a Markdown doc) and produces documentation, which then gets indexed alongside the real source.

This needs a genuinely capable, tool-use-reliable model. Small local models (tested: Ollama qwen3.5:9b, llama3.1:8b) aren't reliable enough — they tend to narrate what they're about to do instead of calling the tool, or explore broadly without ever writing anything. A cloud model (claude-haiku-4-5 has been verified live and works well) is recommended for docgen.provider/docgen.model specifically, even if you keep embedding/chat on local Ollama. Off by default — it costs tokens (real money, on a cloud provider) and isn't needed for repos with decent docs already.

The turn/tool-call budget scales automatically with repo size and the chosen provider's real context window — no manual tuning needed for most repos. repolore prints a heads-up if the computed budget is large on a metered cloud provider.

Web GUI

Optional add-on (repolore-gui). One command starts both the API server and the web frontend:

repolore serve

If no REPOLORE_API_KEY is set, repolore serve generates a random one and prints it once at startup — paste it into the web GUI's setup screen to connect. Set REPOLORE_API_KEY yourself for a stable key across restarts, or run repolore settings → "Server access" to allow anonymous access instead (only do this on a trusted network — repolore serve binds to all network interfaces, not just localhost).

Remote mode

A repolore CLI install can point at someone else's (or your own remote) repolore serve instance instead of indexing locally:

repolore config set mode remote
repolore config set serverUrl https://your-server.example.com
repolore config set apiKey <key>

Every other command works identically — the local/remote split is entirely internal, never a different set of commands.

Config files

Settings and indexed-repo state are plain, hand-editable JSON — not just CLI-managed black-box state:

~/.repolore/settings.json — shared settings (provider/model per capability, exclude patterns, doc-gen budget overrides, allowAnonymous, ...)
~/.repolore/secrets.json — cloud provider API keys, kept separate from settings.json so it's never accidentally exposed by anything that returns settings wholesale
~/.repolore/repos.json — indexed-repo metadata
~/.repolore/config.json — the CLI's own client config (mode, serverUrl, apiKey for remote mode)

Any of these tolerate a partial or hand-edited file — missing fields fall back to defaults. Override the data directory with REPOLORE_DATA_DIR (or repolore config set dataDir <path>) if you don't want ~/.repolore.