init-rag-rat · diff
git:20260913.72dbfb1 to git:20260923.7774461
15 added, 6 removed. Audit A to A.
---
name: init-rag-rat
description: >
Use to set up rag-rat in a repository that is not indexed yet — when the rag-rat MCP server is
DORMANT (its tools return {"status":"no_index"} with a "Run rag-rat init … then restart" remedy),
or when the user asks to initialize / configure / "set up rag-rat" / "index this repo" / choose an
embedding backend. Drives the setup conversationally: scans the repo, explains only the material
choices, recommends the local FastEmbed default for a modest machine, and — only when a remote /
GPU embedder is worth it — loads a reference for local infinity (Docker) or an ephemeral
Modal/RunPod worker, then previews the config, writes it after confirmation, runs the first index,
offers to set up the git maintenance hooks (asks before touching `.git/hooks`), and tells the user
to restart the MCP server. Triggers: "set up rag-rat", "rag-rat is dormant",
"no rag-rat.toml", "index this repo", "configure rag-rat embeddings".
---
# init-rag-rat — configure a dormant rag-rat repo conversationally
rag-rat's MCP server boots **dormant** in a repo with no `rag-rat.toml`: ordinary tools return
`{"status":"no_index", "remedy":"Run rag-rat init … then restart"}`. This skill turns that into a
short guided setup. **You own the conversation; `rag-rat init` owns the scan and validation** — never
hand-write a config blind, and let a real config load re-check it before indexing.
## The common path
1. **Detect state.** You are here because a rag-rat tool returned `status: "no_index"`, or the user
asked to set up rag-rat. Confirm there is no `rag-rat.toml` at (or above) the repo root. If one
already exists, this is a *reconfigure* — send the user to the interactive `rag-rat init` wizard
and stop.
2. **Resolve the CLI** and use the same form throughout, from the **target repo's root**. It must
match the version the rag-rat MCP server runs, so the index you create is one the server can read —
do **not** use `@latest`, and **don't blindly trust an on-`PATH` `rag-rat`**:
- If `rag-rat` is on `PATH`, check `rag-rat --version` and use it **only if it matches** the
- plugin/MCP version — a stale global install would build the index with the wrong binary.
+ plugin/MCP version — a stale global install would build the index with the wrong binary. With
+ the plugin, `~/.local/bin/rag-rat` is its version-matched binary (the MCP server links it when
+ it starts), so try that path too if `rag-rat` alone is not found.
- Otherwise (or on a version mismatch) use `npx -y @rag-rat/bin@0.23.2 …` — the plugin pins
`@rag-rat/bin` to its own version and caches the binary privately, so this is the
version-matched CLI; `npx` runs it in the current directory.
3. **Dry-run discovery.** `<rag-rat> init --yes --dry-run` scans the repo and prints the
auto-detected config (languages, path bindings, the default local FastEmbed backend) **without
writing**. Read it; tell the user the material bits in a line or two (which languages and
directories) — not every commented knob.
4. **Default to FastEmbed unless the machine is powerful (or the repo is large).** FastEmbed
(all-MiniLM, 384-dim, local CPU) needs zero setup and is the right call for most repos on a modest
workstation. Recommend it by default. Only raise a remote / GPU embedder when it earns its keep: a
**large repo**, a wish for a **stronger code-specific embedder**, or an available **GPU / cloud
budget**.
5. **Only if a remote embedder makes sense, load the relevant reference and configure it.** Start
with the overview, then the one that fits — read the file into context on demand; do not inline
its content here:
- **`references/remote-embeddings.md`** — the `[llm.embedding.remote]` block, the local↔remote
model pairing table, dim parity, and which of the two paths below to take.
- **`references/local-infinity.md`** — run a local infinity server via Docker (Connect mode); the
recommended default model + the CPU engine footgun.
- **`references/ephemeral-providers.md`** — provision an ephemeral Modal/RunPod GPU worker
(cookbook); GPU classes, the cost/trust boundary, and the local+cloud hybrid.
6. **Preview and confirm.** Pick the path and confirm with the user before writing anything. Neither
installs git hooks — that's a separate, consented step (step 7).
- **FastEmbed (default):** `<rag-rat> init --yes --no-hooks` writes `rag-rat.toml`, installs the
model, and builds the initial index **and embeddings** in one step. `--no-hooks` is what keeps
hook install a separate ask — plain `init --yes` would install the git hooks immediately. Preview
first with `<rag-rat> init --yes --dry-run` if the user wants to see the config. No hand-editing,
- and **no separate index/reconcile step** for this path.
+ and **no separate index/reconcile step** for this path. It downloads the model and indexes and
+ embeds the whole repo, so on anything but a small repo **run it in the background** (or with
+ your longest command timeout) and poll until it exits — a foreground call can time out partway.
+ Its closing "connect your coding agent … `claude mcp add` / `codex mcp add`" hint is for users
+ **without** the plugin: **do not run those commands** — the plugin already registered the
+ server, and a second registration runs two servers against one index.
- **Custom remote backend:** take the base from `<rag-rat> init --yes --dry-run` (which writes
nothing), add the `[llm.embedding.remote]` block from step 5, show the final config, and write
`rag-rat.toml` only after the user confirms.
7. **Index + embed (custom path only), decide on the git hooks, then restart.**
- **FastEmbed:** step 6 already indexed **and embedded** — **do not re-run.**
- **Custom remote backend:** validate the written config by loading it — `<rag-rat> doctor` fails
loudly on a bad block (dim mismatch, `gpu` with `endpoint`, missing `query_endpoint`, …). Then
run **two commands, in order**:
1. `<rag-rat> index --discover` — builds the source/chunk rows. This does **not** compute
embeddings.
2. `<rag-rat> reconcile` — the embedding backfill: it computes the vectors over the configured
remote backend (provisioning the ephemeral box if the config uses `cookbook`). **Skip it and
the repo has no semantic-search vectors** until a later maintenance pass — always run it
before declaring setup complete.
- **Git maintenance hooks — ask, then install.** rag-rat can install managed
`post-checkout` / `post-merge` / `post-rewrite` / `post-commit` hooks that keep the index fresh as
the repo changes. They modify `.git/hooks`, so **ask the user** — nothing above installed them
(the FastEmbed path ran with `--no-hooks`). If they agree: `<rag-rat> hooks install` — idempotent,
- and it **never clobbers a foreign hook** (if a non-rag-rat hook occupies a slot it errors "move
- it aside or merge manually"; surface that and move on). If they decline, or it isn't a git
- worktree, skip it — nothing to undo.
- - **Then restart the rag-rat MCP server** in the agent. A dormant server does not self-activate
+ and **all or nothing**: if a hook rag-rat does not manage occupies any slot, it installs none and
+ names each one. Tell the user which hooks are in the way and that they can move them aside and
+ re-run `hooks install`; don't leave them thinking the index will stay fresh. If they decline, or
+ it isn't a git worktree, skip it — nothing to undo.
+ - **Then restart the rag-rat MCP server** in the agent — in Claude Code the user runs `/mcp` and
+ reconnects `rag-rat`; in Codex and opencode, a new session. A dormant server does not self-activate
(that would be a half-active server without the watcher and hook listener). After restart it
discovers `rag-rat.toml`, starts fully active, and ordinary tools work against the new index.
## Guardrails
- **Default to FastEmbed.** Don't push a remote backend onto a small repo or a modest machine.
- **localhost-only** for any local embedder — never bind it to a public interface.
- **Same model + dim everywhere.** Mixing embedding models or dims across local and ephemeral
corrupts the vector space; `[llm.embedding] model` must be a registry model whose dim matches what
the server returns. A mismatch is rejected at load.
- **Cost + trust.** Never start a cookbook / ephemeral (cloud) run without explicit go-ahead — it
spends money and runs third-party provisioning code with the user's cloud credentials.
- **Never write config blind.** Always go through `init --yes --dry-run` for the base and a real load
(`doctor` / `index`) for validation.
- **Keep the machine-global database.** Never add an `[index] database` key — the keyless config
`init` produces resolves to the global store, which is what lets the index and memories survive a
`git clean` or a deleted checkout. A per-repo `database` path is the deprecated, un-consolidated
deployment (it never syncs); do not introduce one.