mcp-code-index 0.1.0__tar.gz

mcp_code_index-0.1.0/.claude/agents/eval-judge.md

@@ -0,0 +1,52 @@
+---
+name: eval-judge
+description: "Impartial text-only evaluator for the mcp-eval skill. Compares two code-research answers to the same task and produces a structured JSON verdict. Has no tools — judges from text alone to avoid evidence-based bias."
+tools: WebSearch
+---
+
+You are an impartial code-research evaluator. You will receive:
+
+1. The original task
+2. Two answers (Agent A and Agent B) to that task
+3. The list of files each agent inspected
+
+Your job is to score each answer on four dimensions and declare a winner. **Do not call any tool, including the one in your allowlist.** It exists only because the framework requires a non-empty tools field — you score from text alone. Tool use would let you re-investigate the codebase and bias the verdict toward whichever evidence you can verify.
+
+## Scoring rubric (each 1–5)
+
+- **Correctness**: Does the answer accurately address what was asked? Wrong claims cost points.
+- **Specificity**: Does it cite exact paths, line ranges, symbol names? Vague answers ("the auth code handles this") score low.
+- **Completeness**: Does it cover all parts of the task? Partial answers score lower than thorough ones.
+- **Hallucination safety**: Does the answer stay grounded in cited code, or does it speculate beyond the evidence? Higher score = safer.
+
+## Bias controls
+
+- **Length is not quality.** A concise correct answer beats a verbose hand-wavy one.
+- **More files inspected is not better.** Efficient agents may inspect fewer files and still answer correctly. Count this as a positive for specificity, not a negative for completeness.
+- **Refusal can be correct.** Do not penalize an agent for refusing a task that genuinely cannot be answered with its tools — that's a signal about the tool surface, not about agent quality.
+- **Do not infer agent identity.** You don't know which agent had which tools. Score the answers, not the perceived methodology.
+
+## Required output format
+
+Output ONLY this JSON block. No preamble, no commentary, no markdown headings.
+
+```json
+{
+  "agent_a": {
+    "correctness": <1-5>,
+    "specificity": <1-5>,
+    "completeness": <1-5>,
+    "hallucination_safety": <1-5>,
+    "notes": "<one sentence>"
+  },
+  "agent_b": {
+    "correctness": <1-5>,
+    "specificity": <1-5>,
+    "completeness": <1-5>,
+    "hallucination_safety": <1-5>,
+    "notes": "<one sentence>"
+  },
+  "verdict": "a_wins" | "b_wins" | "tie",
+  "verdict_reasoning": "<two sentences max — what tipped it>"
+}
+```

mcp_code_index-0.1.0/.claude/agents/eval-with-mcp.md

@@ -0,0 +1,41 @@
+---
+name: eval-with-mcp
+description: "Read-only code-research sub-agent restricted to the code-index MCP. Used by the mcp-eval skill to represent the with-MCP arm of an A/B comparison. Do not invoke directly outside that skill."
+tools: mcp__code-index__code_search, mcp__code-index__symbol_lookup, mcp__code-index__file_outline, mcp__code-index__get_symbol_body, mcp__code-index__callers, mcp__code-index__callees, mcp__code-index__dependents, mcp__code-index__dependencies
+---
+
+You are a read-only code-research agent. You answer the user's task by querying the code-index MCP server. The index is current — trust it unless results visibly disagree with each other.
+
+## Tool routing
+
+- **Identifier-shaped query** (`camelCase`, `snake_case`, `ALL_CAPS`) → start with `symbol_lookup`. Fall back to `code_search(mode="lexical")` if not found.
+- **Conceptual query** ("authentication", "where we rate limit") → `code_search(mode="hybrid")`.
+- **Relationship query** ("who calls X", "what does Y depend on") → `callers` / `callees` / `dependents` / `dependencies`. Never use search for these — graph queries are direct lookups.
+- **Need to see what's in a file** → `file_outline`. Never read the full file unless a specific symbol body is required.
+- **Need a specific function's body** → `get_symbol_body(symbol_id)`.
+
+## Composition recipes
+
+- **Trace a feature**: `code_search` → pick top hit → `callers` on its symbol → `file_outline` on each file in the chain.
+- **Plan a refactor**: `symbol_lookup(target)` → `callers(id, depth=2)` to enumerate blast radius → `file_outline` on each touched file.
+- **Find a bug**: `code_search(symptom)` → `callers` on top hit → `get_symbol_body` on the prime suspect.
+
+## Constraints
+
+- You have NO access to `Read`, `Grep`, `Glob`, or `LS`. The tool surface above is exhaustive.
+- If the index genuinely cannot answer the question (e.g. the code is outside indexed paths), say so explicitly. Do not hallucinate.
+- Cite specific paths and line ranges in your answer — `auth/jwt.ts:42-58`, not "the auth file".
+- Be efficient. The point of this comparison is to demonstrate that the index minimizes tokens — don't over-call.
+
+## Required output format
+
+End your response with a fenced JSON block. This is mandatory — the parent harness parses it.
+
+```json
+{
+  "tool_calls": <integer count of tool invocations made>,
+  "files_inspected": ["<path>", "<path>"],
+  "answer": "<your full final answer, prose>",
+  "confidence": <float 0.0 to 1.0>
+}
+```

mcp_code_index-0.1.0/.claude/agents/eval-without-mcp.md

@@ -0,0 +1,34 @@
+---
+name: eval-without-mcp
+description: "Baseline read-only code-research sub-agent restricted to default file tools (Read, Grep, Glob, LS). Used by the mcp-eval skill to represent the without-MCP arm of an A/B comparison. Do not invoke directly outside that skill."
+tools: Read, Grep, Glob, LS
+---
+
+You are a read-only code-research agent. You answer the user's task using only standard filesystem tools. This represents the baseline workflow in a repo without an indexed MCP.
+
+## Approach
+
+- Use `Glob` to discover candidate files by pattern.
+- Use `Grep` to locate text patterns within files.
+- Use `Read` to inspect file contents — read only what you need to answer. Prefer reading line ranges over whole files when possible.
+- Use `LS` when directory structure is unclear.
+
+## Constraints
+
+- You have NO access to MCP tools (`mcp__*`). Do not attempt them — they will fail.
+- Do not edit any files. This is research only.
+- Cite specific paths and line ranges in your answer — `auth/jwt.ts:42-58`, not "the auth file".
+- Work as you normally would. Do not artificially restrain yourself "to be fair to the comparison" — the comparison is about the realistic baseline.
+
+## Required output format
+
+End your response with a fenced JSON block. This is mandatory — the parent harness parses it.
+
+```json
+{
+  "tool_calls": <integer count of tool invocations made>,
+  "files_inspected": ["<path>", "<path>"],
+  "answer": "<your full final answer, prose>",
+  "confidence": <float 0.0 to 1.0>
+}
+```

mcp_code_index-0.1.0/.claude/skills/code-search/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: code-search
+description: Use when navigating an unfamiliar codebase, locating a definition, finding callers or callees, or answering "where is X", "what calls Y", "what does this file contain". Replaces ad-hoc Read/Grep/Glob with targeted SQLite-backed retrieval.
+---
+
+# code-search
+
+You have access to a pre-built code index over this repo, exposed as MCP tools.
+**Default to the index for navigation. Only `Read` after you know the exact path
+and line range.**
+
+## Routing decision tree
+
+| You have... | Use first |
+|---|---|
+| An identifier (camelCase, snake_case, ALL_CAPS) | `symbol_lookup` |
+| A concept ("auth flow", "parsing markdown") | `code_search` |
+| A file path and want its structure | `file_outline` |
+| A symbol_id and want full code | `get_symbol_body` |
+| "What calls this?" | `callers` |
+| "What does this depend on?" | `callees` |
+| "Who imports this file?" | `dependents` |
+| "What does this file import?" | `dependencies` |
+
+## Composition recipes
+
+**Trace a feature end-to-end**
+
+1. `code_search "<feature concept>"` → top hits.
+2. For the most promising hit, `callers` to find entry points.
+3. For each entry point, `callees` to map the call graph.
+4. `get_symbol_body` only on the symbols you actually need to understand.
+
+**Plan a refactor / assess blast radius**
+
+1. `symbol_lookup` the function/class.
+2. `callers symbol_id depth=2` for transitive impact.
+3. `dependents path` for files importing the module.
+
+**Onboard to a new module**
+
+1. `dependencies path` → upstream modules the file leans on.
+2. `file_outline path` → structure.
+3. `code_search` only if you need a particular concept.
+
+## Anti-patterns
+
+- **Don't `Read` before searching.** Reading a 500-line file to find one symbol
+  costs ~10x the tokens of `symbol_lookup` + `get_symbol_body`.
+- **Don't `Grep` for an identifier.** Grep returns raw lines; `symbol_lookup`
+  returns the symbol with its signature, file, and line range.
+- **Don't read more than ~50 lines of a found chunk.** If the snippet is too
+  trimmed, call `get_symbol_body` instead of expanding the read.
+- **Don't ask the index to refresh itself.** A `PostToolUse` hook reindexes on
+  `Edit`/`Write`/`MultiEdit`. The watcher catches IDE-side edits.
+
+## Staleness recovery
+
+If a result's line numbers don't match the file you then `Read` (e.g. you
+checked out a new branch), retry the same call once — `file_outline` and
+`get_symbol_body` reindex the file synchronously when they detect a stale
+mtime. If two retries disagree with the file, fall back to `Grep` once and
+report the inconsistency.

mcp_code_index-0.1.0/.claude/skills/mcp-eval/README.md

@@ -0,0 +1,38 @@
+# mcp-eval — A/B harness for the code-index MCP
+
+A Claude Code skill that runs the same task through two isolated sub-agents — one with the code-index MCP, one with only standard file tools — and produces a side-by-side comparison of tokens, tool calls, latency, and answer quality.
+
+## Install
+
+Copy these into your repo (or your `~/.claude/` for user-level):
+
+```
+.claude/skills/mcp-eval/SKILL.md
+.claude/agents/eval-with-mcp.md
+.claude/agents/eval-without-mcp.md
+.claude/agents/eval-judge.md
+```
+
+That's it. No other dependencies.
+
+## Use
+
+```
+> evaluate the MCP on this task: where do we handle authentication?
+> benchmark with vs without MCP: trace the flow when a user uploads a file
+> is the index actually saving tokens? test it on: what calls parseJWT
+```
+
+The skill triggers on those phrasings, runs both agents in parallel, scores the results with a third sub-agent, and prints a comparison table.
+
+## What it doesn't do
+
+- **Edit tasks.** The skill refuses tasks that would modify files — running the same edit twice in parallel corrupts the tree. Convert to a "describe what you would change" prompt instead.
+- **Single-task conclusions.** One run is high-variance. The skill includes a suggested 5-task mix in its calibration section. Use it.
+- **Cross-repo benchmarking.** Each repo has its own index and its own task profile. Numbers from repo A don't predict repo B.
+
+## Tuning
+
+If the eval-judge sub-agent attempts to call WebSearch despite instructions, switch its `tools:` field to a tool that doesn't exist (e.g. `tools: NoSuchTool`) — Claude Code will reject the call and the agent will fall back to text-only reasoning. The current setup uses WebSearch as a no-op because the framework needs a non-empty allowlist.
+
+If the with-MCP agent over-calls (lots of redundant searches), tighten its system prompt — that's a real failure mode of the index, not noise.

mcp_code_index-0.1.0/.claude/skills/mcp-eval/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: mcp-eval
+description: "Run the same code-research task through two isolated sub-agents — one with the code-index MCP, one with only Read/Grep/Glob — and produce a side-by-side comparison of token usage, tool calls, latency, and answer quality. Triggers on requests to evaluate, benchmark, A/B test, or measure the code-index MCP. Use when the user says 'evaluate the MCP on [task]', 'is the index worth it', 'how much does the MCP save', 'compare with vs without MCP', or asks for proof the MCP is helping. Do NOT trigger for ordinary code-search questions where the user just wants an answer, and do NOT trigger for tasks that involve file edits."
+---
+
+# MCP Evaluation Harness
+
+Runs an A/B comparison of the code-index MCP server against the default Read/Grep/Glob baseline on the same task, then reports tokens, tool calls, latency, and a judge-scored quality verdict.
+
+## Preconditions
+
+Before doing anything else, verify all three:
+
+1. The `code-index` MCP is connected — `mcp__code-index__*` tools must be visible in the current toolset. Check with `/mcp` if unsure.
+2. `.claude/index.db` exists and was modified within the last 24 hours. Run `ls -la .claude/index.db` and check mtime.
+3. The task is **read-only**. Phrasings like "find", "where", "explain", "trace", "what calls", "how does" are fine. Anything that says "edit", "fix", "add", "implement", "rename", "refactor" is NOT — running the same edit twice in parallel corrupts the working tree.
+
+If any precondition fails, stop and tell the user which one. Do not proceed with workarounds.
+
+## Procedure
+
+### Step 1 — Lock the task prompt
+
+Capture the user's task verbatim into `$TASK`. Do not rephrase, expand, or "improve" it. Both agents must receive byte-identical wording, or the comparison is invalid.
+
+### Step 2 — Spawn both research agents in parallel
+
+Issue both Task tool calls in a **single assistant message** so they run concurrently. Sequential runs double wall time and skew the latency numbers.
+
+- Agent A: `subagent_type: "eval-with-mcp"`, prompt: `$TASK`
+- Agent B: `subagent_type: "eval-without-mcp"`, prompt: `$TASK`
+
+These sub-agents are defined in `.claude/agents/eval-with-mcp.md` and `.claude/agents/eval-without-mcp.md`. Their tool restrictions are enforced at the framework level — do not pass extra tools.
+
+### Step 3 — Extract metrics from each result
+
+Each sub-agent terminates its response with a fenced JSON block:
+
+```json
+{
+  "tool_calls": <int>,
+  "files_inspected": ["path1", "path2"],
+  "answer": "<final answer>",
+  "confidence": 0.0
+}
+```
+
+Parse this JSON. Then from the Task tool's metadata, capture:
+
+- `total_input_tokens` (input + cache_read summed)
+- `total_output_tokens`
+- `wall_time_seconds`
+
+If a sub-agent did not emit the JSON block, record `parse_failure: true` for that side and continue. Do not retry — the failure is signal.
+
+### Step 4 — Run the judge
+
+Spawn the `eval-judge` sub-agent (no tools, text-only reasoning). Pass it:
+
+- The original `$TASK`
+- Both `answer` strings, clearly labeled `agent_a` and `agent_b`
+- Both `files_inspected` lists
+
+The judge returns a JSON verdict with per-dimension scores and a winner.
+
+### Step 5 — Render the report
+
+Produce this table for the user. Use Sonnet pricing ($3/M input, $15/M output) unless the user has indicated Opus or Haiku.
+
+```
+## MCP Evaluation Report
+
+**Task**: <verbatim>
+**Repo**: <git rev-parse --short HEAD>
+**Index age**: <hours since .claude/index.db mtime>
+
+| Metric                | With MCP  | Without MCP | Delta            |
+|-----------------------|-----------|-------------|------------------|
+| Input tokens          |           |             |                  |
+| Output tokens         |           |             |                  |
+| Total tokens          |           |             | -X (-Y%)         |
+| Tool calls            |           |             |                  |
+| Files inspected       |           |             |                  |
+| Wall time             |           |             |                  |
+| Correctness (1–5)     |           |             |                  |
+| Specificity (1–5)     |           |             |                  |
+| Completeness (1–5)    |           |             |                  |
+| Hallucination safety  |           |             |                  |
+
+**Judge verdict**: <a_wins | b_wins | tie>
+**Reasoning**: <judge's reasoning, 1–2 sentences>
+
+**Cost (this task)**: $<a> vs $<b> — savings $<delta>
+**Projected monthly** (30 similar tasks/day): $<a × 900> vs $<b × 900>
+
+### Answer excerpts
+**With MCP** (first 300 chars): <…>
+**Without MCP** (first 300 chars): <…>
+```
+
+## Anti-patterns
+
+- **Never run on edit tasks.** Two parallel agents editing in parallel corrupts the tree. Refuse, or convert to read-only ("describe the changes you would make instead of making them").
+- **Never rephrase the task between agents.** Identical strings, or the comparison is invalid.
+- **Never give the judge tools.** A tool-enabled judge re-investigates and biases the verdict toward whichever agent's evidence it can verify.
+- **Never run the agents sequentially.** Parallel Task calls in one message — anything else skews wall time.
+- **Never declare a single run conclusive.** State variance in the report. For real conclusions: 3+ varied tasks, aggregate.
+- **Never relax the without-MCP agent's constraints to "help" it.** If it refuses or fails because it lacks the index, that IS the result.
+
+## Calibration
+
+The MCP wins on **exploration** — "where is X", "what calls Y", "trace the flow of Z". It ties or loses on **lookup** — tasks where the file path is already known, or where one Grep nails it. A balanced eval set must include both. If every task is exploratory, the MCP looks better than its true average value.
+
+Suggested representative task mix for a fair eval (run 5):
+
+1. Pure discovery: "where do we handle authentication"
+2. Symbol trace: "what calls `parseJWT`"
+3. Refactor planning: "what's the blast radius of changing the User model"
+4. Bug hunt: "find the code that handles 429 responses"
+5. Known-path lookup: "explain what `auth/jwt.ts` does" — should be near-tie, sanity check
+
+## Failure modes
+
+- **Sub-agent times out** → record as failure for that side. Do not retry.
+- **Sub-agent refuses** ("I cannot do this without Read") → that IS the data point. Judge scores it accordingly.
+- **`code-index` MCP disconnected mid-run** → abort and report. Don't fall back silently.
+- **Index stale** (chunks reference deleted files) → abort and tell the user to reindex.
+- **Judge produces non-JSON** → re-invoke the judge once with "respond ONLY with the JSON block, no preamble". If still fails, present the raw judge output to the user with a note.

mcp_code_index-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual envs
+.venv/
+venv/
+env/
+ENV/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+
+# Project
+.claude/index.db
+.claude/index.db-shm
+.claude/index.db-wal
+.claude/settings.json
+.claude/reindex-hook-wrapper.sh
+.env
+*.log
+
+# Tests
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/

mcp_code_index-0.1.0/CLAUDE.md

@@ -0,0 +1,13 @@
+## Code navigation
+
+This repo has a code index exposed via MCP (tools: `code_search`, `symbol_lookup`,
+`file_outline`, `get_symbol_body`, `callers`, `callees`, `dependents`,
+`dependencies`).
+
+- For ANY discovery task ("where is X", "what calls Y", "find the code that..."),
+  use the index tools. Do not Read or Grep to explore.
+- Read files only AFTER the index has identified the exact path.
+- Use `file_outline` instead of Read when you only need to know what's in a file.
+- For exact identifiers (camelCase, snake_case, ALL_CAPS), use `symbol_lookup`.
+  For conceptual queries, use `code_search`.
+- The index auto-updates on `Edit`/`Write`/`MultiEdit`; you don't need to refresh it.

mcp_code_index-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Achref Tlili
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_code_index-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: mcp-code-index
+Version: 0.1.0
+Summary: SQLite-backed code index for Claude Code, exposed via MCP
+Project-URL: Homepage, https://github.com/achreftlili/code-index
+Project-URL: Repository, https://github.com/achreftlili/code-index
+Project-URL: Issues, https://github.com/achreftlili/code-index/issues
+Author: Achref Tlili
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pathspec>=0.12.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: sqlite-vec>=0.1.0
+Requires-Dist: tree-sitter-go>=0.23.0
+Requires-Dist: tree-sitter-python>=0.23.0
+Requires-Dist: tree-sitter-rust>=0.23.0
+Requires-Dist: tree-sitter-typescript>=0.23.0
+Requires-Dist: tree-sitter>=0.23.0
+Requires-Dist: voyageai>=0.3.0
+Requires-Dist: watchdog>=4.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# code-index
+
+<!-- mcp-name: io.github.achreftlili/code-index -->
+
+A SQLite-backed code index for Claude Code, exposed via MCP. Replaces exploratory
+`Read`/`Grep`/`Glob` calls with targeted retrieval.
+
+## What it does
+
+- **Parses** your repo with tree-sitter (Python, TypeScript/JavaScript, Go, Rust).
+- **Chunks** per symbol; expands identifiers (`getUserAuthToken` → `get user auth token`).
+- **Embeds** with Voyage `voyage-code-3` (default) or local Ollama.
+- **Stores** symbols, chunks, vectors, and call/import edges in `.claude/index.db`.
+- **Serves** retrieval over MCP — 8 retrieval tools + 1 admin tool (see below).
+- **Auto-updates** via a Claude Code `PostToolUse` hook and an optional file watcher.
+
+## Tools
+
+| Tool              | Purpose                                                                                                  |
+| ----------------- | -------------------------------------------------------------------------------------------------------- |
+| `init`            | Build or refresh the project's index. Incremental by default; `force=true` rebuilds from scratch.        |
+| `code_search`     | Hybrid (vector + FTS) search for **conceptual** queries (e.g., "auth flow", "where do we parse JSON").   |
+| `symbol_lookup`   | Exact-name lookup of functions / classes / methods / types. Prefer over `code_search` for identifiers.   |
+| `file_outline`    | Symbols (with signatures) in a file, in source order. Use instead of `Read` when you only need shape.    |
+| `get_symbol_body` | Full chunk for a `symbol_id` returned by `symbol_lookup` or `code_search`.                               |
+| `callers`         | Symbols that CALL the given symbol. `depth` (1-5) expands transitively.                                  |
+| `callees`         | Symbols that the given symbol CALLS. `depth` (1-5) expands transitively.                                 |
+| `dependents`      | Files that import the given file.                                                                        |
+| `dependencies`    | Files that the given file imports.                                                                       |
+
+All tools return bounded JSON; large bodies use `get_symbol_body` rather than
+inlining whole files.
+
+## Requirements
+
+Python with **loadable SQLite extension support** (required by `sqlite-vec`).
+Python 3.13 has this enabled by default. For 3.10–3.12, use either:
+- the python.org installer, or
+- pyenv: `PYTHON_CONFIGURE_OPTS=--enable-loadable-sqlite-extensions pyenv install 3.12.x`
+
+## Install
+
+### In Claude Code (primary)
+
+```bash
+# 1. Set your embedder API key (Voyage default; for local Ollama see Configuration)
+export VOYAGE_API_KEY=...
+
+# 2. Register the MCP server. uvx clones, builds, and runs — no global install.
+claude mcp add code-index -- uvx --from git+https://github.com/achreftlili/code-index code-index-mcp
+```
+
+That's it. Open Claude Code in your repo and ask:
+
+> _"Build the code index for this repo."_
+
+Claude calls the `init` MCP tool, which writes `.claude/index.db`. Subsequent
+prompts can use `code_search`, `symbol_lookup`, `callers`, etc. — see
+**Tools** above for the full surface.
+
+#### Or, with a permanent install
+
+```bash
+pip install mcp-code-index
+claude mcp add code-index -- code-index-mcp
+```
+
+#### Optional: keep the index live as you edit
+
+Without the hook below, the index drifts when files change outside the agent
+(`mv`, `git checkout`, IDE saves) until you call `init` again. With it, every
+`Edit` / `Write` / `MultiEdit` Claude performs triggers an incremental reindex
+of the touched file:
+
+```bash
+git clone https://github.com/achreftlili/code-index ~/code-index
+~/code-index/scripts/install-hook.sh /path/to/your/repo   # idempotent
+```
+
+### In other MCP-compatible agents
+
+The server speaks standard MCP over stdio, so any client that supports MCP
+servers works (Cursor, Continue, Cody, Zed, etc.). Configure the client to
+launch `code-index-mcp` (after `pip install`) or the `uvx --from git+…`
+command above. Once connected, call the `init` tool from inside the client
+to bootstrap the index.
+
+### From source (development)
+
+```bash
+git clone https://github.com/achreftlili/code-index
+cd code-index
+pip install -e .
+code-index init        # CLI alternative to the `init` MCP tool
+code-index-mcp         # starts the MCP server on stdio (for manual wiring)
+```
+
+## Configuration
+
+Environment variables:
+
+| Var | Default | Notes |
+|---|---|---|
+| `CODE_INDEX_DB` | `.claude/index.db` | SQLite path. |
+| `CODE_INDEX_EMBEDDER` | `voyage` | `voyage` or `ollama`. |
+| `CODE_INDEX_EMBED_MODEL` | `voyage-code-3` | Model name. |
+| `CODE_INDEX_EMBED_DIM` | `1024` | Must match the model. |
+| `VOYAGE_API_KEY` | — | Required when `CODE_INDEX_EMBEDDER=voyage`. |
+| `OLLAMA_URL` | `http://localhost:11434` | Ollama server. |
+
+## Layout
+
+```
+src/code_index/
+  db.py           SQLite schema, connection, sqlite-vec loading
+  parser.py       Tree-sitter wrapper, symbol + edge extraction
+  chunker.py      Per-symbol chunks, identifier expansion
+  embedder.py     Voyage / Ollama backends
+  indexer.py      Pipeline: walk → parse → chunk → embed → write
+  retriever.py    Hybrid search (vector + FTS5) with RRF
+  watcher.py      File watcher (watchdog)
+  mcp_server.py   8 MCP tools
+  cli.py          init / reindex / watch / stats
+```