github-twin

github-twin

You reviewed a permission check six months ago. Claude doesn't remember

it. github-twin does — it indexes your commits and review comments,

and surfaces them as retrieval hits whenever an agent writes or reviews

new code in your style.

Try it now from Claude Code — drop this into ~/.claude.json and reload:

{

"mcpServers": { "github-twin": { "command": "uvx", "args": ["github-twin", "serve"] } } }

Your code stays on your box. Embeddings are computed locally

(Ollama or sentence-transformers); only the LLM seam (gt summarize,

gt distill, gt eval) optionally calls a hosted provider, and even

that's swappable to local Ollama. The gemini embedder is the one

exception — opt-in only.

---

A personal RAG over your GitHub history, served to Claude Code (or any MCP client) as a stdio server. Two scopes, one codebase:

• User mode — index your own commits + review comments. Surfaces your past code as style examples and your past comments as review hints when an agent is writing or reviewing new code.
• Org mode — index a whole GitHub org's files-at-HEAD, commits, and PR reviews across every member. Queries scope by repo, language, or reviewer login.

Retrieval is hybrid (BM25 + vector via RRF), AST-aware via tree-sitter for python/scala/javascript/typescript/go/rust, and contextually enriched at embed time with per-chunk headers + optional LLM-generated summaries.

Install

The fastest path is uvx — no virtualenv to manage, isolated per-tool:

# One-shot

uvx github-twin --help

Pinned version

uvx github-twin@0.1.0 --help

With sentence-transformers for the alt embedder

uvx --with 'github-twin[st]' github-twin --help

If you prefer a project-local install:

uv add github-twin            # or: pip install github-twin

gt --help

gt and github-twin are the same Typer app — use whichever fits your muscle memory.

Authenticate

Pick whichever is least friction — github-twin tries them in this order:

1. OAuth device flow (no `gh` install needed):

   uvx github-twin auth login        # opens browser, persists token

uvx github-twin auth status # show which source is active

   Token persists in the OS keyring (macOS Keychain / Linux Secret

Service / Windows Credential Manager) or, when unavailable, a 0600 file under your data dir.

1. Existing `gh` CLI: if you've already run gh auth login, gt picks up the token via gh auth token — nothing to do.
2. `GITHUB_TOKEN` env var: a classic PAT works too; useful for CI / headless / docker. Required scopes: repo, read:org, user:email.

Wire into Claude Code

The MCP server runs over stdio via github-twin serve (or gt serve). Run uvx github-twin auth login once on the box that will host the server.

Option A — via the Claude Code plugin marketplace (lowest-friction):

/plugin marketplace add ChristopherDavenport/christopherdavenport-marketplace

/plugin install github-twin@christopherdavenport

This registers the MCP server entry automatically; set GT_PATHS__DATA_DIR in your environment (or in ~/.claude.json's env block for this server) to point at the DB directory.

Option B — manual wiring: add an entry to ~/.claude.json (or your mcp_servers.json):

{

"mcpServers": { "github-twin": { "command": "uvx", "args": ["github-twin", "serve"], "env": { "GT_PATHS__DATA_DIR": "/path/to/your/github-twin-data" } } } }

If you'd rather not persist a token and instead supply it inline (CI, ephemeral container), add "GITHUB_TOKEN": "ghp_..." to that env block; it acts as the lowest-priority fallback.

Restart Claude Code; the find_*, predict_review_outcome, summarize_review_patterns, and sync tools will be available.

Quickstart

Pick a directory to hold the SQLite DB, config, and ingested cache — everything per-data-dir lives under this one root:

export GT_PATHS__DATA_DIR=~/github-twin-data

uvx github-twin auth login # one-time OAuth (or set GITHUB_TOKEN)

user mode (your own GitHub history)

uvx github-twin init # discover identity via /user uvx github-twin sync # ingest + summarize + embed uvx github-twin serve # MCP server over stdio

layer an org into the SAME DB

uvx github-twin init --kind org --org http4s uvx github-twin sync

OR keep the org in its own DB by switching data dirs

GT_PATHS__DATA_DIR=~/twin-http4s \ uvx github-twin init --kind org --org http4s GT_PATHS__DATA_DIR=~/twin-http4s uvx github-twin sync

gt sync is incremental on subsequent runs.

config.toml lives next to the DB at /config.toml and is created on the first gt init --embed-backend ... call. Default is $XDG_DATA_HOME/github-twin (or ~/.local/share/github-twin) when GT_PATHS__DATA_DIR is unset.

LLM provider matrix

The retrieval surface (find_*, predict_review_outcome) always runs locally on the SQLite index — no API call. LLM calls only happen in three places:

• gt distill — clusters review comments / commits into rules.
• gt summarize — generates per-chunk NL summaries used by the embed-time prefix.
• gt eval reviews / eval predictions — held-out RAG-vs-baseline scoring.

Each picks a backend by precedence Claude → Gemini → Ollama (whichever API key is set), or you can force one explicitly.

The Vertex / ADC path needs the aiplatform.googleapis.com API enabled on your project, and billing applies even for "free" Gemini models — the AI Studio free tier does not extend to Vertex. Project IDs are not secrets; the credential itself lives at ~/.config/gcloud/application_default_credentials.json and is refreshed by gcloud.

Embedder backends

We keep the embedder backend separate from the LLM backend. Choose one:

• Default — Ollama (nomic-embed-text, 768-dim, ~50ms/chunk). Requires a running Ollama daemon. Zero cost, fully local.
• Alternative — sentence-transformers (uv add 'github-twin[st]', pulls torch). Useful when an Ollama daemon isn't available or you want a specific HuggingFace model. Local.
• Alternative — Gemini (gemini-embedding-001 at 3072-dim by default). Uses the google-genai dep that's already installed; auth via GEMINI_API_KEY / GOOGLE_API_KEY, or via GT_GEMINI_PROJECT
• ADC (gcloud auth application-default login) to route through Vertex AI without managing a key. Remote — this is the only embedder that sends chunk text off-box. Pick it when you have Gemini auth but no Ollama / [st] install, and your corpus is okay to share with Google.

The embedder is a per-DB commitment — sqlite-vec bakes the vector dimension into the table at first creation. Stamp the choice into /config.toml at init time so every subsequent command picks it up:

gt init --embed-backend gemini                              # gemini-embedding-001, 3072

gt init --embed-backend gemini --embed-dim 1536 # request shorter output gt init --embed-backend sentence_transformers \ --embed-model BAAI/bge-small-en-v1.5 --embed-dim 384

Re-running with the same values is a no-op; running with different values against an existing config.toml fails loud rather than silently changing the corpus. GT_EMBED__* env vars still work for one-off overrides and CI.

A "cloud-LLM only" setup either needs an embedder process (Ollama / [st]) or has to opt into the remote Gemini embedder.

Required GitHub token scopes

When you gt init, the GH client needs:

• repo — private repos and PR comments on them
• user:email — verified email addresses for the user-mode identity sweep
• read:org — org member listing and private org repo discovery

A fine-grained PAT works; classic tokens too.

Retrieval

Hybrid search by default: BM25 (SQLite FTS5) and vector similarity run in parallel, then fuse via Reciprocal Rank Fusion (k=60). The vector leg matches semantic intent; the BM25 leg catches exact identifiers (getUserById, SQLITE_OPEN_READWRITE) that vector search routinely misses. Design reference: Anthropic — Contextual Retrieval.

At embed time, each chunk gets a deterministic header prepended: # path :: symbol_name (node_kind), plus the function's leading docstring/comment when present, plus an optional LLM-generated summary (see gt summarize). The header lets vector queries land on chunks whose bodies only contain identifiers (e.g. natural-language queries against a VaultSecretEq function).

BM25 query expansion is on by default (cfg.retrieval.query_expansion = "rule"), with rule-based code-shaped synonyms applied only to the BM25 leg — embeddings already capture synonymy, so expansion never touches the vector query. Switch to "ollama" to add LLM-generated alternates on top, cached on disk per-token.

predict_review_outcome stays on pure vector retrieval because its inverse-distance vote weighting depends on calibrated L2 distance.

MCP tools

All retrieval tools accept optional repo= and author_login= filters.

CLI

gt init [--kind user|org|repo] [--org N] [--repo owner/name]

gt repos # list discovered org repos gt ingest # backfill gt summarize [--limit N] [--backend ...] # LLM NL summaries per chunk gt embed