cpnlookup

 ██████╗██████╗ ███╗   ██╗██╗      ██████╗  ██████╗ ██╗  ██╗██╗   ██╗██████╗
██╔════╝██╔══██╗████╗  ██║██║     ██╔═══██╗██╔═══██╗██║ ██╔╝██║   ██║██╔══██╗
██║     ██████╔╝██╔██╗ ██║██║     ██║   ██║██║   ██║█████╔╝ ██║   ██║██████╔╝
██║     ██╔═══╝ ██║╚██╗██║██║     ██║   ██║██║   ██║██╔═██╗ ██║   ██║██╔═══╝
╚██████╗██║     ██║ ╚████║███████╗╚██████╔╝╚██████╔╝██║  ██╗╚██████╔╝██║
 ╚═════╝╚═╝     ╚═╝  ╚═══╝╚══════╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚═╝

Smarter retrieval. Deeper context. Persistent memory.

cpnlookup lets you ask questions about any GitHub repository from your terminal, without cloning it. It reads the code through the GitHub API, splits it into functions, classes and documentation sections, and answers with a hybrid retrieval pipeline (vector search, keyword search, a reranker and a static call graph) on top of your local Ollama model. Your code, questions and embeddings never leave your machine.

lookup init psf/requests
lookup ask "How are retries configured for a Session?"

Installation

You need Python 3.10+, Ollama running locally, and a GitHub personal access token (classic) with the repo scope.

pip install cpnlookup
ollama pull mistral
lookup auth <your_github_token>
lookup                      # welcome screen; shows whether Ollama is running

The first init downloads the embedding model (about 90 MB) and the first ask downloads the reranker (about 85 MB), both into ~/.cpnlookup/models. After that, everything runs offline except reading repositories from GitHub.

Usage

Run init inside the directory where you want the index to live; every command then works on that directory's index.

Settings

Settings are stored per directory in .cpnlookup/config.json.

lookup config model qwen2.5-coder
lookup config num_ctx 16384

How it works

lookup init owner/repo
  GitHub tree API ── one call: every path + blob SHA
        │
  Change detection ── compare SHAs with the last run; unchanged files are skipped
        │
  Fetch ── download only new or changed .py / .md files
        │
  Chunk ── Python via ast (functions, classes, methods) · Markdown by header
        │
  Store (SQLite .cpnlookup/index.db)
        ├── chunks + FTS5 keyword index
        ├── call graph edges (name( → function or class)
        └── embeddings (all-MiniLM-L6-v2) → FAISS index

lookup ask "question"
  FAISS (meaning)  ─┐
                    ├─ merge ─ cross-encoder rerank ─ top_k chunks
  FTS5 BM25 (words) ┘                                     │
                                  call graph: + callers and callees
                                                          │
                       + last 4 Q&A turns ─ local Ollama model ─ answer

• Hybrid retrieval. Vector search finds code by meaning ("what handles authentication?"); BM25 keyword search finds exact symbols ("where is parse_token defined?"). A cross-encoder then reads the question and each candidate together to pick the most relevant ones.
• Call-graph context. For each selected chunk, the functions it calls and the functions that call it are added, within a size budget that fits your model's context window.
• Incremental indexing. GitHub blob SHAs tell cpnlookup exactly which files changed, so re-indexing only downloads and embeds those.
• Safe interruption. An index is marked incomplete until a run finishes; ask refuses to use a half-written index.
• Conversation memory. Questions and answers are kept in ~/.cpnlookup/memory.db, separate from indexes, so they survive lookup drop. The last four turns go into each new prompt.

Files

~/.cpnlookup/auth.json        GitHub token
~/.cpnlookup/registry.json    every indexed directory
~/.cpnlookup/memory.db        conversation history
~/.cpnlookup/models/          embedding + reranker models
<dir>/.cpnlookup/index.db     chunks, keyword index, call graph, metadata
<dir>/.cpnlookup/faiss.index  vector index
<dir>/.cpnlookup/config.json  settings for this directory

Upgrading from 2.x or 3.0.0b1

3.0.0 uses a new index format. The first lookup init after upgrading rebuilds each index from scratch once; after that, re-indexing is incremental again. Conversation history is kept.

Known limitations

• Languages: only Python and Markdown files are indexed for now.
• First answer is slow: each ask loads PyTorch and the embedding models (several seconds), and generation time depends on your Ollama model and hardware.
• Call graph is name-based: a call to process() links to every indexed function named process, regardless of module. Dynamic dispatch isn't detected.
• Large repositories: vector search is exhaustive (IndexFlatL2); beyond roughly 10,000 chunks queries slow down.
• Memory: the last four turns are included verbatim; older turns are stored but not summarised.

Roadmap

Version history

Privacy

Embeddings, reranking and answers are computed on your machine. The GitHub API is used only to read the repositories you choose to index, and model files are downloaded once from Hugging Face. Conversation history stays in ~/.cpnlookup/memory.db.

License

MIT © 2026 Charles Cabatian. See LICENSE.

Acknowledgements

Developed by @projcjdevs. Thanks to @2nieGarcia, @renzv-compsci and @NIghtIngale340 for feedback and testing.