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):
   sh

   Copy

   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.
2. Existing gh CLI: if you've already run gh auth login, gt picks up the token via gh auth token — nothing to do.
3. 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 <data_dir>/config.toml and is created on the first gt init --embed-backend ... call. Default <data_dir> 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 <data_dir>/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.