This repo is also a Claude Code plugin marketplace. Its plugin registers the MCP server and, when a session starts, refreshes the index in the background if the last refresh is at least 12 hours old. It needs repolore-mcp 0.3.0 or later installed as above. Install the plugin before running repolore setup, which then sees its server and leaves the registration to it:

/plugin install repolore --marketplace ryckakas/repolore

That works in one step from Claude Code 2.1.275; on older versions, run /plugin marketplace add ryckakas/repolore, then /plugin install repolore@repolore. The plugin's tools are named mcp__plugin_repolore_repolore__search and so on.

The plugin's refresh_hours option sets the interval, and 0 turns the refresh off: /plugin, then Installed, repolore and Configure options. The refresh skips until repolore setup has built the index, and while another refresh runs.

If Claude Code also has repolore registered for every project with the same command, it uses that registration, leaves the plugin's server out, and the tools keep their mcp__repolore__ names. A registration with another command, such as a checkout run through uv run, runs beside the plugin's, and Claude sees every tool twice; keep one, with claude mcp remove repolore --scope user or by disabling the plugin.

Claude Code doesn't update plugins from other people's marketplaces by itself: /plugin marketplace update repolore fetches the latest plugin, or turn on auto-update for the marketplace in /plugin under Marketplaces. The plugin doesn't update repolore itself; uv tool upgrade repolore-mcp does.

--managed-python makes uv use its own Python build, which can load the SQLite extension the index needs; some system builds, such as python.org's on macOS, can't. If the commands aren't found afterwards, run uv tool update-shell and open a new terminal. The install takes about 160 MB.

The first launch of each command compiles its Python code, which took about 25 seconds on Windows, close to Claude Code's 30-second wait for an MCP server; later launches take a few seconds. Adding --compile-bytecode to the install does that work up front instead. On some Windows machines uv then fails with "os error 1224" (astral-sh/uv#14017); install without it there.

Reranking (--rerank, off by default) needs PyTorch on top, about 900 MB more, and says how to add it when you ask for it.

To run the latest main instead of the last release, install git+https://github.com/ryckakas/repolore the same way.

Without a tool install, uvx runs it too: uvx --managed-python --python 3.12 --from repolore-mcp repolore setup --no-register, and the other commands the same way. See Other MCP clients for launching the server like that.

repolore setup runs these steps, which you can also run yourself:

1. See which repos it found:

   repolore repos
   

   Create repolore.toml at the config path that repolore version prints, then run repolore repos again to check the selection:

   include = ["you/some-repo", "your-org/*"]   # globs over owner/name; every repo when unset
   exclude = ["your-org/old-*"]                # never these
   local_roots = ["~/projects"]                # checkouts in here add their local .plans/ documents
   

2. Fetch and index:

   repolore ingest   # fetch from GitHub; later runs fetch only what changed
   repolore build    # embed and index; later runs embed only what changed
   

3. Register the MCP server with Claude Code once:

   claude mcp add --scope user --transport stdio repolore -- repolore-mcp
   

   For Codex and other clients, see Other MCP clients.

All sessions share one server that holds the model: each session's repolore-mcp is a small relay (about 70 MB) that starts the shared server when none is running and passes the tools through. The server loads the model in the background when it starts, which takes about half a minute, so only a search in that time waits for it, and it exits 10 minutes after the last session closes. It listens on 127.0.0.1 only and needs a token that changes every time it starts. repolore server status shows it and repolore server stop stops it. repolore-mcp --standalone serves from the session's own process, with its own copy of the model, as before.

repolore refresh ingests what changed and rebuilds the index with the settings it was built with, and only one refresh runs at a time. Search keeps working meanwhile. An MCP client can do the same: the server's refresh tool starts one in the background, and list_repos says when the index was built, how the last refresh went and, while one runs, how far it has got (repos fetched, chunks embedded). Claude Code asks before the first call; to allow it for good, add mcp__repolore__refresh to permissions.allow in your Claude Code settings, or mcp__plugin_repolore_repolore__refresh when the plugin provides the server.

The plugin also refreshes when a session starts and the last refresh is at least 12 hours old. Without the plugin, a SessionStart hook in ~/.claude/settings.json does the same:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "repolore", "args": ["session-start", "--hours", "12"], "async": true }
        ]
      }
    ]
  }
}

repolore session-start starts the refresh in the background and returns at once, so the session doesn't wait for it and closing the session doesn't stop it; Claude Code ends a hook's own process with its session.

uv tool upgrade repolore-mcp updates repolore itself. On Windows, close the sessions using repolore (in Claude Code you can disable it in /mcp instead) and run repolore server stop first, since running programs keep their files locked. Elsewhere, a session opened before the upgrade says so on its next search; reconnect repolore in your client (/mcp in Claude Code).

The index and the raw GitHub responses live in the data directory that repolore version prints; they contain your private repos' content, so treat that folder like the repos themselves.

When something doesn't work, repolore doctor checks each part of the setup and prints the fix for each one that fails: GitHub access and the token's scopes, repolore.toml, the index, the embedding model, the last refresh, the shared server and the MCP clients that have repolore registered. It makes one GitHub request, and when Claude Code is installed it asks claude mcp get repolore (or plugin:repolore:repolore, the plugin's server), which starts repolore to check that it connects.

Add it to ~/.codex/config.toml with longer timeouts. repolore setup adds this entry when codex is on PATH, with an env_vars line for the variables below that are set when it runs:

[mcp_servers.repolore]
command = "repolore-mcp"
startup_timeout_sec = 60
tool_timeout_sec = 300

Codex's startup timeout covers the server's tools/list, which takes about 8 seconds when no shared server is running yet and longer after a reboot, and its tool timeout covers a search that waits for the model to load, about 10 seconds warm and longer cold. Its documented defaults are 10 and 60 seconds. When building a session's tool list, Codex waits only about a second for servers that aren't required (mcp_optional_startup_grace_ms); set that to 0, or required = true on this server, to wait for the startup timeout instead.

Codex gives a server only a short list of environment variables: PATH, the home, app data and temp folders, and a few more. That's enough for gh auth token (checked on Windows). If you rely on REPOLORE_GITHUB_TOKEN, HTTPS_PROXY, REPOLORE_DEVICE or an XDG_* directory, list it in env_vars = ["REPOLORE_GITHUB_TOKEN"]. The relay finds its folders through XDG_*, and the shared server, which every client's sessions share, and the refreshes it starts inherit the environment of whichever session started it.