clast-ai 0.2.2 → 0.2.4

package/README.md

@@ -1,70 +1,68 @@
-# Clast v0.2
+<div align="center">
 
-A code index for LLM coding agents, served over MCP. Clast parses your repository with
-[tree-sitter](https://tree-sitter.github.io/), keeps a live index of symbols, calls, references, imports and
-type relationships in SQLite, and exposes tools that answer navigation questions in one call instead of a
-chain of greps and file reads.
+# Clast
 
-What an agent gets:
+### Ask the code. Skip the grep marathon.
 
-- **Ranked symbol search** - exact names, partial names, abbreviations (`KProd`, `gcn`), typos, qualified
-  names (`Parser.parse`) and plain words (`resolve import path`) matched against names, signatures, docs
-  and what function bodies mention.
-- **Exact symbol source** - the body of one function or class, read fresh from disk with line numbers,
-  together with its callers, callees, overrides and subtypes. No need to read the whole file.
-- **Type-aware call graph** - calls are resolved with declared receiver types, imports, inheritance,
-  `this`/`self`/`super` and argument counts, so `record.topic()` goes to the right class, an overload
-  gets its own callers and `list.push()` is not mistaken for your `Stack.push`. Edges that are name-only
-  guesses are marked `?`.
-- **References, type hierarchy, repo map, text search, git change impact** - see the tool list below.
-- **Always fresh** - a file watcher re-indexes on save, and every query re-checks the files it is about to
-  quote, so line numbers and source are never stale, even right after the agent edits a file.
-- **Fast** - parallel indexing in worker threads; warm start only stats files; queries take milliseconds.
-- **No native compilation** - grammars are WASM, storage is Node's built-in `node:sqlite`.
+A code index for coding agents. One call tells Claude who calls a function, what implements an<br>
+interface, what breaks if you change it, and what nobody uses any more.
 
-Languages: TypeScript, TSX, JavaScript, Python, Java, C#, Go, Rust, C, C++, Ruby, PHP, Swift, Dart.
+**Built for Claude Code** &nbsp; | &nbsp; **Works with Codex, Gemini CLI and any MCP client** &nbsp; | &nbsp; **14 languages** &nbsp; | &nbsp; **MIT licensed**
 
----
+[Install](#install) &nbsp; / &nbsp; [What it does](#made-for-the-questions-grep-cannot-answer) &nbsp; / &nbsp; [Measured results](#measured-not-promised) &nbsp; / &nbsp; [First steps](#your-first-minute) &nbsp; / &nbsp; [Changelog](CHANGELOG.md)
 
-## Quick start
+</div>
 
-Requires **Node.js 22.22 or newer** (Clast uses the built-in SQLite module).
+An agent with only grep finds a name. To follow a call chain, list every subclass or count the
+endpoints it has to search, read, and search again. Clast parses your repository with tree-sitter,
+keeps a live index of symbols, calls, imports and type relationships, and answers those questions
+directly, with exact `file:line` locations. The index follows every edit, so answers are never stale.
 
-### As a Claude Code plugin (recommended)
+## Install
 
-In Claude Code:
+**Claude Code (recommended).** Two commands inside Claude Code, then restart:
 
 ```
 /plugin marketplace add xls/clast
 /plugin install clast@clast
 ```
 
-or from a shell: `claude plugin marketplace add xls/clast && claude plugin install clast@clast`.
-
-The plugin brings the MCP server, a short skill that teaches Claude which tool answers which question,
-and four slash commands:
+The plugin brings the index server, a short skill that teaches Claude which tool answers which
+question, and four slash commands:
 
 | Command | What it does |
 | --- | --- |
-| `/clast:deadcode [path]` | Finds unused functions, methods and types, verifies the candidates, and removes the ones you confirm |
+| `/clast:deadcode [path]` | Finds unused functions, methods and types, verifies them, and removes the ones you confirm |
 | `/clast:impact <symbol>` | What must change with a symbol, every caller, and the tests to run |
 | `/clast:audit [path]` | Inventory for due diligence or onboarding: size, structure, endpoints, database access, dependencies, dead code |
 | `/clast:status` | State of the index |
 
-The plugin starts the server from a global `clast-ai` that is at least as new as the plugin, otherwise
-through `npx clast-ai@<plugin version>` (downloaded on first use).
+Requires **Node.js 22.22 or newer**. The first start indexes the project in the background (seconds;
+about half a minute for 15,000 files). Later starts are ready immediately.
 
-### Upgrading from an older install
+**Codex, Gemini CLI and other agents.** Clast is a standard MCP server, so any agent that speaks MCP
+can use it:
 
-If clast is already set up the old way (`npm install -g clast-ai` plus `claude mcp add`, or through
-the old VS Code extension), install the plugin and restart. That is all, provided Node.js is 22.22 or
-newer (0.1 ran on Node 18; check with `node --version`):
+```sh
+npm install -g clast-ai
 
+codex mcp add clast -- clast-ai          # Codex
+gemini mcp add -s user clast clast-ai    # Gemini CLI
 ```
-/plugin marketplace add xls/clast
-/plugin install clast@clast
+
+Then give the agent the usage guide the Claude plugin ships as a skill:
+
+```sh
+clast-ai guide >> AGENTS.md              # or GEMINI.md, or your rules file
 ```
 
+<details>
+<summary><strong>Coming from an older install?</strong></summary>
+
+If clast is already set up the old way (`npm install -g clast-ai` plus `claude mcp add`, or through
+the old VS Code extension), install the plugin as above and restart. That is all, provided Node.js is
+22.22 or newer (0.1 ran on Node 18; check with `node --version`).
+
 The first session after that cleans up in the background, once per plugin version:
 
 - clast servers registered with `claude mcp add`, for all projects or for single ones, are removed
@@ -81,10 +79,9 @@ from the file (`clast-ai migrate` names the file).
 Optional: `npm uninstall -g clast-ai` removes the old global package. The plugin does not need it; it
 only uses a global install that is at least as new as the plugin itself.
 
-To see what would be removed, or to do it by hand (for example when you keep using the plain MCP
-server and only want the old index gone):
+To see what would be removed, or to do it by hand:
 
-```bash
+```sh
 clast-ai migrate           # report only
 clast-ai migrate --apply   # remove the leftovers
 ```
@@ -92,127 +89,249 @@ clast-ai migrate --apply   # remove the leftovers
 What was removed is logged to `migrate.log` in the plugin's data folder. `CLAST_NO_MIGRATE=1` switches
 the automatic clean-up off.
 
-Later plugin updates: `/plugin marketplace update clast`, then `/plugin update clast@clast`.
+</details>
 
-### As a plain MCP server
+<details>
+<summary><strong>Updating, and how the plugin starts the server</strong></summary>
 
-```bash
-npm install -g clast-ai
-claude mcp add -s user clast clast-ai
+Update with `/plugin marketplace update clast`, then `/plugin update clast@clast`.
+
+The plugin starts the server from a global `clast-ai` that is at least as new as the plugin, otherwise
+through `npx clast-ai@<plugin version>` (downloaded on first use, cached afterwards).
+
+</details>
+
+<details>
+<summary><strong>Cursor, VS Code and other editors</strong></summary>
+
+Add the server to the editor's MCP configuration. These follow each editor's documented format; they
+have not been tested the way Claude Code, Codex and Gemini CLI have.
+
+Cursor, `.cursor/mcp.json` in the project (or `~/.cursor/mcp.json`):
+
+```json
+{ "mcpServers": { "clast": { "command": "clast-ai", "env": { "CLAST_PROJECT_DIR": "${workspaceFolder}" } } } }
 ```
 
-`-s user` registers the server for all projects. This gives the tools without the skill and the slash
-commands. Use one of the two ways, not both: with both, every tool is listed twice (the plugin removes
-a registration made this way when it is installed later).
+VS Code, `.vscode/mcp.json`:
 
-Either way, restart Claude Code (or "Developer: Reload Window" in VS Code) and run `/mcp`: `clast`
-should be listed with 15 tools. The first start indexes the project in the background (seconds, about
-half a minute for 15k files); until that first index is ready the tools answer with the build progress
-and ask to be called again. Later starts are ready immediately.
+```json
+{ "servers": { "clast": { "command": "clast-ai", "env": { "CLAST_PROJECT_DIR": "${workspaceFolder}" } } } }
+```
 
-### Other ways
+Clast indexes the directory in `CLAST_PROJECT_DIR`, else `CLAUDE_PROJECT_DIR`, else the directory the
+agent starts it in. Editors do not always start servers in the project, hence the variable above.
 
-```bash
-# from GitHub, without npm
-npm install -g github:xls/clast
+</details>
 
-# from a clone (also how to work on clast itself)
-git clone https://github.com/xls/clast.git && cd clast
-npm install && npm run build
-claude mcp add -s user clast node /path/to/clast/dist/cli.js
-claude --plugin-dir /path/to/clast        # or: try the plugin from the clone for one session
+<details>
+<summary><strong>Claude Code without the plugin, a team-wide setup, building from source</strong></summary>
+
+**As a plain MCP server** (the tools, without the skill and the slash commands):
+
+```sh
+npm install -g clast-ai
+claude mcp add -s user clast clast-ai
 ```
 
-Per-project registration for a team: put this in `.mcp.json` in the project root.
+Use the plugin or this, not both: with both, every tool is listed twice.
+
+**For a whole team**, put this in `.mcp.json` in the project root:
 
 ```json
 { "mcpServers": { "clast": { "command": "clast-ai" } } }
 ```
 
-The project root is `CLAST_PROJECT_DIR`, else `CLAUDE_PROJECT_DIR`, else the working directory.
+**From source** (also how to work on clast itself):
 
----
+```sh
+git clone https://github.com/xls/clast.git && cd clast
+npm install && npm run build
+claude --plugin-dir /path/to/clast                          # try the plugin for one session
+claude mcp add -s user clast node /path/to/clast/dist/cli.js   # or register the build
+```
 
-## Tools
+</details>
 
-| Tool | Answers | Typical use |
-|------|---------|-------------|
-| `clast_overview` | What is in this repo / directory? | First call in an unfamiliar codebase: languages, layout with sizes, most referenced symbols, hub files, entry points |
-| `clast_file_summary` | What is in this file / directory? | Outline of a file (signatures, line ranges, doc summaries, imports, importers) or a directory listing with main symbols |
-| `clast_search` | Where is X? What is it called? | Ranked symbol search by name, partial name, abbreviation, typo, qualified name or descriptive words (matched against names, signatures, docs and what function bodies mention) |
-| `clast_get_context` | Show me X. | Source of one symbol plus callers, callees, overloads, overrides, subtypes. Batch several names in one call |
-| `clast_call_graph` | Who calls X? What does X call? | Caller / callee tree to depth N, test callers separated, `within` path filter. Works for external names too |
-| `clast_references` | Where is X used? | Every usage of an identifier (calls, types, imports, assignments) with the enclosing symbol of each line |
-| `clast_hierarchy` | What implements / extends / overrides X? | Supertypes and transitive subtypes; Ruby mixins; Go interface satisfaction by method set (names plus parameter / result counts); the same method across related types; `within` path filter |
-| `clast_grep` | Where does this text appear? | Literal or regex search over all text files; each hit is labelled with its enclosing function |
-| `clast_changes` | What did this diff touch? | Symbols changed vs HEAD or a base ref, their callers outside the change, and the tests that exercise them |
-| `clast_impact` | What breaks if I change X? Which tests do I run? | Declarations, overrides and implementations that must change together; every direct caller by file and line; how far it reaches through indirect callers; the test files that call it directly or through its callers |
-| `clast_unused` | What is dead code? | Functions, methods and types nothing references (or only other unused code does), by file with line ranges; code used only by tests; names that only appear in strings or non-code files |
-| `clast_stats` | How many X are there? What does this code base consist of? | Exact totals grouped by directory, file, kind or name; inventory, endpoints, database access, dependencies |
-| `clast_status` | Is the index healthy? | Counts, languages, indexing progress, watcher state |
-| `clast_reindex` | Rebuild | Rarely needed; incremental rescan or forced rebuild |
-| `clast_comment` | Docs for X | Existing doc comment, or one generated by a local LLM (optional) |
+## Made for the questions grep cannot answer
 
-All tools return compact plain text (not JSON): one line per fact, `path:line` locations that can be
-passed straight to an editor, and a hint about the next useful call when something is not found.
+### Know what breaks before you change it
 
-### Addressing symbols
+Ask about one function and get everything a change touches: the overrides and declarations that must
+change with it, every caller with its line, and the tests to run. That includes tests that never name
+the function but reach it through its callers.
 
-Anywhere a tool takes a symbol name you can write:
+```
+> clast_impact  Context.Render                                   (gin)
+
+method Context.Render  context.go:1201-1215
+direct callers: 18 resolved in 1 file (each must be checked when the signature changes):
+  context.go: Context.HTML :1222 (x2), Context.IndentedJSON :1235, Context.SecureJSON :1242, ...
+indirect callers (through the direct ones, up to depth 3): 5 functions in 2 files
+tests to run (11 files: 2 call it directly, 9 reach it through callers):
+  context_test.go     direct  (TestContextRenderIfErr, TestContextRenderSSE, +26)
+  auth_test.go        via Context.String  (TestBasicAuthSucceed, TestBasicAuth401, +3)
+  routes_test.go      via Context.String  (TestRouteQuery, TestRouterMethod, +4)
+  ...
+```
 
-| Form | Example |
-|------|---------|
-| bare name | `parseConfig` |
-| member | `Parser.parse`, `Parser::parse`, `Parser#parse` |
-| inherited member | `Engine.GET` (defined on an embedded / base type) |
-| package or module path | `django.shortcuts.render`, `page.Clear`, `Illuminate\Pipeline\Pipeline` |
-| file and name | `src/db/index.ts:open` |
-| file and line | `src/db/index.ts:120` (the symbol containing that line) |
+### Find the code nobody uses
 
-When a bare name has many unrelated definitions the tools list them instead of guessing.
+Agents write a lot of code and refactors leave helpers behind. `clast_unused` lists functions, methods
+and types that nothing references, and what only that dead code uses, so a removed feature's helpers
+are found with it. Code used only by tests and names that still appear in a string, a template or a
+config file are listed separately, because those need a look before they go.
+
+```
+> clast_unused  path: app                                        (a C++ application)
+
+unused code: 80 symbols, 415 lines in 51 files - the name is never referenced outside
+its own definition, or only from other unused code (10594 symbols judged under app)
+app/panels/agc_ui.cpp  (6 symbols, 109 lines)
+  function reasonText   :12-23    (used only by unused agcGear)
+  function ampNow       :42-49    (used only by unused agcStep)
+  function agcStep      :79-111   exported
+  function agcGear      :126-169  exported
+  ...
+```
+
+Entry points, routes and tests marked by a decorator or attribute, subclasses of library types and
+other things a framework calls for you are left out, and counted so you can see what was skipped.
+
+### Follow the call chain in one step
 
-### Example
+Calls are resolved with declared types, imports, inheritance and argument counts, so `record.topic()`
+goes to the right class and `list.push()` is not mistaken for your `Stack.push`. Ask for depth 2 or 3
+and get the chain, not just the next hop. An edge that is only a name match is marked `?`, so the
+agent knows what to verify.
 
 ```
-> clast_get_context { "name": "cylinderVolume" }
-
-function cylinderVolume  src/math/volume.ts:4-6  [exported]
-3| /** Volume of a cylinder. */
-4| export function cylinderVolume(radius: number, height: number): number {
-5|   return circleArea(radius) * height;
-6| }
-callers (1 resolved):
-  main  src/app.ts:10
-calls (1):
-  circleArea  src/math/area.ts:2-4
+> clast_call_graph  Engine.handleHTTPRequest  depth: 2           (gin)
+
+callers (2 resolved; depth 2):
+  Engine.ServeHTTP  gin.go:701
+    Context.FileFromFS  context.go:1352  ?
+    RouterGroup.createStaticHandler  routergroup.go:273  ?
+  Engine.HandleContext  gin.go:713
 ```
 
+### Describe it. Clast finds it.
+
+No name to search for? Describe the behaviour. Search covers names, signatures, doc comments and
+what function bodies mention, and copes with partial names, abbreviations and typos.
+
 ```
-> clast_call_graph { "name": "MemTable.Add", "direction": "callers" }
-
-method leveldb.MemTable.Add  db/memtable.cc:76-100
-  void MemTable::Add(SequenceNumber s, ValueType type, const Slice& key, const Slice& value)
-callers (3; caller  call-site):
-  leveldb.MemTableInserter.Put  db/write_batch.cc:122
-  leveldb.MemTableInserter.Delete  db/write_batch.cc:126
-  leveldb.MemTableConstructor.FinishImpl  table/table_test.cc:315
+> clast_search  "client ip from forwarded headers"               (gin)
+
+method Context.ClientIP  context.go:997-1046
+  // ClientIP implements one best effort algorithm to return the real client IP.
+method Engine.validateHeader  gin.go:505-524
+  // validateHeader will parse X-Forwarded-For header and return the trusted client IP address
 ```
 
----
+### Count it exactly
+
+How many endpoints, how many receivers, which models does the database layer touch most? `clast_stats`
+returns exact totals grouped by directory, file, kind or name, with production, test and vendored
+code kept apart. `/clast:audit` turns that into a due-diligence inventory: size, structure, HTTP
+endpoints, database access, dependencies and dead code.
+
+### Read the function, not the file
+
+`clast_get_context` returns exactly the lines of one function or class, read fresh from disk, with
+its callers, callees and overrides. The agent spends its context on the code it needs.
+
+### Always current, nothing to maintain
+
+A watcher re-indexes files as they are saved, and every answer re-checks the files it quotes, so line
+numbers are right even a second after the agent edited a file. The index is a cache in `.clast/`:
+delete it whenever you like. Grammars are WebAssembly and storage is Node's built-in SQLite, so
+there is nothing to compile.
+
+**Languages:** TypeScript, TSX, JavaScript, Python, Java, C#, Go, Rust, C, C++, Ruby, PHP, Swift, Dart.
+
+## Measured, not promised
+
+Every figure comes from real headless Claude Code sessions: the same question asked once with clast
+and once with only grep and file reads. The rows below are from OnAir (C++, 7.5k files, 1.6M lines);
+the vscode results (TypeScript, 15.7k files) are in the full tables.
+
+| Kind of work | Tool calls (clast / grep) | Time | Cost |
+| --- | ---: | ---: | ---: |
+| Find dead code in a directory | 2 / 16 | 20 s / 124 s | $0.15 / $1.89 |
+| Multi-hop questions (call chains, subclasses, impact) | 1.2 / 5.9 | 12.5 s / 25.8 s | $0.056 / $0.212 |
+| Code described by behaviour, in a repo the model has not seen | 1.8 / 4.2 | 12.0 s / 20.5 s | $0.068 / $0.197 |
+| Counting ("how many receiver classes") | 1.0 / 3.3 | 11 s / 34 s | about $0.02 / $0.29 |
+| Simple lookups (where is X, who calls X) | 1.7 / 1.7 | 12.7 s / 14.3 s | $0.063 / $0.096 |
+| Cross-cutting refactors (rename a method, add a parameter everywhere) | 8.3 / 8.3 | 27 s / 26 s | $0.26 / $0.25 |
+
+Both sides answered correctly almost everywhere; the difference is how much searching it took.
+
+**Where it does not help.** Looking up one name is a tie: a current model with ripgrep does that in
+one call. Writing code is a tie too: the agent reads the surrounding code before it edits, index or
+not. Clast tells the agent to skip it for those edits, so it adds no calls there, only the fixed size of its tool definitions in the prompt. Clast earns its place on questions that take several hops, on counting, and on dead code. The
+samples are small (two repositories, three runs per question), so read them as direction.
+
+Full tables, method, answer-quality audits and index speed: [docs/benchmarks.md](docs/benchmarks.md).
+
+## Your first minute
+
+Open a project in Claude Code with the plugin installed, then try these:
+
+1. **Get the lie of the land:** "Give me an overview of this repository."
+2. **Trace something:** "Who ends up calling `saveOrder`, two levels up?"
+3. **Plan a change:** `/clast:impact OrderService.save`
+4. **Clean up:** `/clast:deadcode src/billing`
+5. **Take stock:** `/clast:audit`
+
+**Not sure it is running?** `/clast:status` shows the index, and `/mcp` lists the server with 15 tools.
+
+## Reference
+
+<details>
+<summary><strong>All 15 tools</strong></summary>
+
+| Tool | Answers |
+|------|---------|
+| `clast_overview` | What is in this repo or directory? Languages, layout, most referenced symbols, entry points |
+| `clast_file_summary` | What is in this file or directory? Outline with signatures, line ranges, imports |
+| `clast_search` | Where is X, what is it called? By name, partial name, abbreviation, typo, or a description |
+| `clast_get_context` | Show me X: its source plus callers, callees, overloads, overrides, subtypes |
+| `clast_call_graph` | Who calls X, what does X call, to depth N |
+| `clast_references` | Where is X used at all: calls, types, imports, assignments |
+| `clast_hierarchy` | What implements, extends or overrides X? Including Go interfaces by method set |
+| `clast_impact` | What must change with X, who reaches it, which tests to run |
+| `clast_unused` | What is dead code? |
+| `clast_stats` | How many X? Inventory, endpoints, database access, dependencies |
+| `clast_grep` | Where does this text appear? Each hit labelled with its function |
+| `clast_changes` | What did this git diff touch, and who calls it? |
+| `clast_status` | Is the index healthy? |
+| `clast_reindex` | Rebuild (rarely needed) |
+| `clast_comment` | Doc comment for X, optionally generated by a local model |
+
+All tools return compact plain text: one line per fact, `path:line` locations, and a hint about the
+next useful call when something is not found.
+
+**Addressing symbols.** Anywhere a tool takes a name you can write:
 
-## How Claude knows to use it
+| Form | Example |
+|------|---------|
+| bare name | `parseConfig` |
+| member | `Parser.parse`, `Parser::parse`, `Parser#parse` |
+| package or module path | `django.shortcuts.render`, `Illuminate\Pipeline\Pipeline` |
+| file and name | `src/db/index.ts:open` |
+| file and line | `src/db/index.ts:120` (the symbol containing that line) |
 
-The server sends usage instructions to the client when it connects, and every tool description says when
-to prefer it over grep or reading files. Installed as a plugin, the bundled `explore` skill adds a
-short workflow guide. You can also say it once: "use the clast tools to navigate the code".
+When a bare name has many unrelated definitions the tools list them instead of guessing.
 
----
+</details>
 
-## Command line
+<details>
+<summary><strong>Command line</strong></summary>
 
-The same queries are available from a shell, which is handy for scripts, hooks and debugging:
+The same queries work from a shell, for scripts, hooks and debugging:
 
-```bash
+```sh
 clast-ai overview                      # repository map
 clast-ai outline src/db                # directory or file outline
 clast-ai search "resolve import path"  # ranked symbol search
@@ -220,19 +339,21 @@ clast-ai symbol Indexer.indexAll       # source + callers + callees
 clast-ai callers resolveImports --depth 2 --no-tests
 clast-ai hierarchy Shape
 clast-ai refs DEFAULT_CONFIG
-clast-ai grep "TODO" --path src
-clast-ai changes main                  # symbols changed vs main and their impact
 clast-ai impact Shape.area             # what must change with it, callers, tests to run
 clast-ai unused src/billing            # dead code under a directory (or the whole project)
+clast-ai stats endpoints               # exact counts: inventory, symbols, endpoints, database, ...
+clast-ai changes main                  # symbols changed vs main and their impact
+clast-ai guide                         # the usage guide for agents, as Markdown
+clast-ai migrate                       # leftovers of older installs
 clast-ai index --force                 # rebuild the index
-clast-ai parse file.go                 # debug: what the extractor sees
 ```
 
 Add `--root <dir>` to point at another project. `clast-ai` with no arguments runs the MCP server.
 
----
+</details>
 
-## Configuration
+<details>
+<summary><strong>Configuration and languages</strong></summary>
 
 Optional. Create `clast.config.json` (or `.claude/clast.config.json`) in the project root:
 
@@ -258,10 +379,10 @@ Optional. Create `clast.config.json` (or `.claude/clast.config.json`) in the pro
 | `workers` | `0` (auto) | Parser threads for bulk indexing; `1` disables workers |
 | `watch.enabled` | `true` | Re-index files as they change |
 | `watch.debounceMs` | `200` | Debounce for file change events |
-| `llm.*` | disabled | OpenAI-compatible endpoint for `clast_comment` generation |
+| `llm.*` | disabled | OpenAI-compatible endpoint for `clast_comment` (Ollama, LM Studio, vLLM, OpenAI, OpenRouter) |
 
-Environment: `CLAST_PROJECT_DIR` (project root), `CLAST_DB_PATH` (index location override),
-`CLAST_GRAMMARS_DIR` (alternative grammar directory), `CLAST_DEBUG=1` (timings and spec warnings).
+Environment: `CLAST_PROJECT_DIR` (project root), `CLAST_DB_PATH` (index location), `CLAST_GRAMMARS_DIR`
+(alternative grammar directory), `CLAST_NO_MIGRATE=1` (no automatic clean-up), `CLAST_DEBUG=1` (timings).
 
 | Language | id | Extensions |
 |----------|----|------------|
@@ -279,314 +400,88 @@ Environment: `CLAST_PROJECT_DIR` (project root), `CLAST_DB_PATH` (index location
 | Swift | `swift` | `.swift` |
 | Dart | `dart` | `.dart` |
 
-### Optional: generated doc comments
-
-`clast_comment` can ask a local or hosted OpenAI-compatible model (Ollama, LM Studio, vLLM, OpenAI,
-OpenRouter) to write a doc comment for an undocumented symbol. Set `llm.model` to enable it, for example
-`{"llm": {"endpoint": "http://localhost:11434/v1", "model": "qwen2.5-coder:7b"}}` for Ollama. Generated
-text is stored by file path and qualified name, so it survives re-indexing.
-
----
-
-## How it works
-
-1. **Scan** - walk the tree honouring `.gitignore` (root and nested) and `ignoredPaths`; compare size and
-   mtime with the index so an unchanged file costs one `stat`.
-2. **Parse** - changed files are read, hashed and parsed by a pool of worker threads (tree-sitter WASM).
-   A per-language spec turns the syntax tree into symbols (with qualified names, signatures, doc comments,
-   line ranges), calls (with receiver text and declared receiver type), imports, inheritance and
-   identifier occurrences.
-3. **Store** - the main thread writes to SQLite (`node:sqlite`, WAL). A cold index uses a bulk-load mode
-   that builds secondary indexes at the end. Symbol names, signatures and docs also go into an FTS5 index.
-4. **Link at query time** - call edges are stored as "symbol A calls name N on receiver R of type T" and
-   resolved when queried, so nothing goes stale when another file changes. Resolution order: declared
-   receiver type, then imports and same-file definitions, then `this`/`self` and inheritance, then
-   evidence scoring for untyped receivers. Argument counts separate overloads and rule out same-named
-   methods of another shape. A call through an interface or base type counts as a caller of the
-   implementations it can reach (Go's structural interfaces as "possible"); a call bound to a subclass
-   override does not count for the base method, and `super.m()` binds to the inherited method. Types
-   are told apart by more than their name where the language allows it: Go packages (`pkg.Type`
-   against the file's imports), imports and packages in TS / Python / Java / PHP, C# generic arity and
-   partial classes, Ruby lexical constant lookup, Rust module paths.
-5. **Stay fresh** - a watcher re-indexes saved files; in addition every tool re-checks the files it is
-   about to quote and re-parses them on the spot if they changed.
-
-The index lives in `.clast/index.db` and is a pure cache: delete it at any time.
-
-### Performance
-
-Measured with `npm run bench` (Node 24, Windows 11, Ryzen 9950X3D, up to 12 parser workers). Cold index is a first run on an
-empty index; warm rescan is a restart with nothing changed.
-
-<!-- BENCH:START -->
-| repo | files | symbols | cold index | warm rescan | db size | search (name) | search (words) | symbol + callers/callees | callers depth 2 | references |
-| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
-| vscode | 15726 | 461365 | 26.1 s | 1895 ms | 357 MB | 168 ms | 42 ms | 28 ms | 38 ms | 11 ms |
-| aspnetcore | 11470 | 145271 | 10.2 s | 1382 ms | 135 MB | 9.3 ms | 86 ms | 33 ms | 38 ms | 6.6 ms |
-| kafka | 6481 | 126393 | 9.5 s | 863 ms | 144 MB | 26 ms | 33 ms | 25 ms | 962 ms | 5.6 ms |
-| rails | 3580 | 61549 | 3.8 s | 352 ms | 52 MB | 8.7 ms | 15 ms | 22 ms | 35 ms | 3.0 ms |
-| framework | 3180 | 44124 | 3.0 s | 337 ms | 38 MB | 1.4 ms | 46 ms | 23 ms | 23 ms | 2.2 ms |
-| django | 2987 | 60131 | 3.1 s | 522 ms | 42 MB | 29 ms | 41 ms | 21 ms | 48 ms | 2.5 ms |
-| fastapi | 1224 | 10049 | 0.8 s | 161 ms | 7 MB | 5.0 ms | 17 ms | 5.7 ms | 48 ms | 2.4 ms |
-| hugo | 939 | 16896 | 1.1 s | 127 ms | 11 MB | 7.2 ms | 38 ms | 18 ms | 18 ms | 2.4 ms |
-| redis | 919 | 35752 | 1.9 s | 103 ms | 23 MB | 5.7 ms | 16 ms | 7.0 ms | 26 ms | 2.2 ms |
-| tokio | 816 | 12341 | 1.1 s | 85 ms | 11 MB | 3.9 ms | 17 ms | 2.0 ms | 4.2 ms | 1.4 ms |
-| http | 362 | 3947 | 0.7 s | 75 ms | 3 MB | 1.3 ms | 9.6 ms | 3.5 ms | 1.6 ms | 5.3 ms |
-| express | 142 | 439 | 0.4 s | 20 ms | 1 MB | 0.4 ms | 1.0 ms | 0.8 ms | 0.5 ms | 1.6 ms |
-| leveldb | 133 | 3456 | 0.6 s | 14 ms | 2 MB | 2.2 ms | 15 ms | 3.3 ms | 1.8 ms | 2.5 ms |
-| Alamofire | 107 | 4085 | 1.5 s | 23 ms | 4 MB | 2.4 ms | 7.1 ms | 1.5 ms | 530 ms | 1.3 ms |
-| ripgrep | 103 | 4496 | 0.6 s | 13 ms | 3 MB | 1.3 ms | 13 ms | 1.3 ms | 1.4 ms | 0.5 ms |
-| gin | 99 | 2157 | 0.4 s | 12 ms | 2 MB | 1.5 ms | 7.7 ms | 2.2 ms | 4.3 ms | 0.7 ms |
-| spring-petclinic | 50 | 323 | 0.2 s | 11 ms | 1 MB | 0.8 ms | 0.7 ms | 0.6 ms | 0.6 ms | 1.3 ms |
-
-Node v24.7.0, win32 x64. Query times are medians of 5 in-process runs on the most-called function of each repo.
-<!-- BENCH:END -->
-
-Worst case measured: `callers IDisposable.dispose` on vscode (10.7k call sites, 4.7k definitions of
-`dispose`) takes 5-6 s. Scoped with `within` it is fast.
-
----
-
-## Clast vs grep + read
-
-Measured with real headless Claude Code sessions (`bench/ab.mjs`): every question runs in its own
-fresh session, once with clast connected and once with only Read / Grep / Glob. Two large repositories:
-vscode (TypeScript, 15.7k files) and OnAir (C++, 7.5k files, 1.6M lines). The index was fully built
-before the first session. Answers are scored against facts verified in the source beforehand; an
-implementation task is scored on its diff.
-
-"Cost" is the API-price equivalent that Claude Code reports for the session. It weights fresh input and
-output above cached prompt tokens, so it is the closest single number to "tokens that matter".
-
-| Kind of work | Repo | Sessions per arm | Tool calls (clast / grep) | Wall time | Cost per question | Correct |
-| --- | --- | ---: | ---: | ---: | ---: | ---: |
-| Multi-hop questions (call chains, transitive subclasses, impact) | vscode | 18 | 1.3 / 3.1 | 16.0 s / 19.8 s | $0.063 / $0.126 | 18 / 18 |
-| Multi-hop questions | OnAir | 18 | 1.2 / 5.9 | 12.5 s / 25.8 s | $0.056 / $0.212 | 18 / 18 |
-| Simple lookups (where is X, who calls X, what implements X) | vscode | 30 | 1.4 / 1.4 | 13.9 s / 13.9 s | $0.053 / $0.059 | 30 / 29 |
-| Simple lookups | OnAir | 30 | 1.7 / 1.7 | 12.7 s / 14.3 s | $0.063 / $0.096 | 30 / 30 |
-| Counting ("how many receiver classes under core/") | OnAir | 3 | 1.0 / 3.3 | 11 s / 34 s | about $0.02 / $0.29 | 3 / 2 |
-| Small implementation tasks (new provider, new enum value, new subclass) | vscode | 6 | 7.5 / 8.5 | 30 s / 31 s | $0.29 / $0.24 | 6 / 6 |
-| Small implementation tasks | OnAir | 6 | 11.5 / 12.8 | 39 s / 40 s | $0.58 / $0.56 | 6 / 6 |
-| Cross-cutting refactors (rename a method in 28 files, add a parameter and update all callers) | vscode | 4 | 21.8 / 22.0 | 47 s / 48 s | $0.45 / $0.37 | 4 / 4 |
-| Cross-cutting refactors | OnAir | 4 | 9.8 / 7.8 | 26 s / 25 s | $0.25 / $0.24 | 4 / 4 |
-| Before a change (tests that reach a function, files to edit for a signature change, dead functions in a file) | vscode | 9 | 2.3 / 2.2 | 19.3 s / 19.8 s | $0.098 / $0.154 | 9 / 9 |
-| Before a change | OnAir | 9 | 1.7 / 3.6 | 14.3 s / 17.4 s | $0.126 / $0.173 | 9 / 9 |
-| Find dead code in a directory ("five unused functions under app/", answers checked by hand) | OnAir | 2 | 2.0 / 16.0 | 20 s / 124 s | $0.15 / $1.89 | 2 / 2 |
-| Questions that describe behaviour without naming anything ("what takes out the spike in the middle of the spectrum") | OnAir | 12 | 1.8 / 4.2 | 12.0 s / 20.5 s | $0.068 / $0.197 | 12 / 12 |
-| Questions that describe behaviour | vscode | 12 | 1.0 / 1.0 | 11.7 s / 11.8 s | $0.048 / $0.044 | 12 / 12 |
-
-What this says:
-
-- **Multi-hop questions are where clast pays off**: half the cost and 20% less time on vscode, a
-  quarter of the cost and half the time on OnAir. One call returns a call chain or a full inheritance
-  tree that grep needs three to twelve rounds for, and the agent reads 70-85% less tool output.
-- **Simple lookups are a tie.** A current model with ripgrep answers them in one or two calls; clast
-  does not make that faster, it only returns a little less text.
-- **Counting is faster and exact** with `clast_stats`. With grep the agent tallied matches by hand and
-  was off by one in one of three runs.
-- **Finding dead code is the largest gap measured**: one `clast_unused` call and a confirming grep
-  against 11-21 greps, a sixth of the time and a thirteenth of the cost. Every function either arm
-  named was verified unused, and all ten the grep sessions found are in clast's list.
-- **Describing behaviour instead of naming it** works on a repository the model has never seen
-  (OnAir): search over names, comments and what function bodies mention finds the place in one or two
-  calls where grep needs four rounds of guessing words. On vscode it is a tie at one call, because the
-  model already knows where things are in vscode; that row measures the model's memory, not the tools.
-- **Questions before a change are cheaper, not always faster.** With `clast_impact` and `clast_unused`
-  the sessions cost 27-36% less because the agent reads less tool output. The clear win is "which
-  tests reach this function when none names it": 1 call and 11 s against 5.7 calls and 22 s on OnAir.
-  "Which files do I edit for a signature change" is one grep and stays a tie.
-- **Implementation work showed no benefit**, neither small features nor cross-cutting refactors. Both
-  arms made the same edits in the same files in the same time (refactors were also checked for
-  completeness: nothing of the old name or call shape left). Finding every occurrence of one name is
-  a single grep, and before editing the agent reads the neighbouring code either way. Clast costs a
-  little more here because its tool definitions are in the prompt.
-- **Small samples.** Two repositories, three runs per question, questions written by the tool's
-  author. The figures show the direction, not a precise ratio.
-
-One result changed the server itself. Claude Code defers MCP tools behind its tool search by default,
-and in that state the agent never called clast: 0 of 60 sessions, every question answered with Grep.
-The navigation tools now ask the client to keep them loaded, after which the agent used clast in every
-question session where it helped. The cost is about 5k tokens of tool definitions and instructions in
-the cached prompt (measured with 13 tools: 23.7k against 19.3k prompt tokens for a session that calls
-no tool; `clast_impact` and `clast_unused` add about 0.6k).
-
-Reproduce with `node bench/ab.mjs <repo> bench/ab/<set>.json --runs 3`. The question sets are in
-`bench/ab/`.
-
-### Answer quality
-
-Reviewer agents asked deliberately hard questions on 17 real repositories and checked every answer
-against the source. Over the last five rounds the share of first answers judged correct rose from
-roughly 45-60% to 65-78%, with new questions each round.
-
-Two further audits read the cited source lines for call edges that clast shows as certain (no `?`):
-
-| Repo | Language | Wrong | Checked |
-| --- | --- | ---: | ---: |
-| kafka | Java | 0 | 57 |
-| tokio | Rust | 0 | 17 |
-| laravel | PHP | 0 | 19 |
-| vscode | TypeScript | 1 | 45 |
-| django | Python | 1 | 39 |
-| aspnetcore | C# | 1 | 58 |
-| hugo | Go | 1 | 19 |
-| rails | Ruby | 4 | 18 |
-
-The vscode and aspnetcore errors were fixed afterwards; the django, hugo and rails ones are open (see
-Known limitations).
-
----
-
-## Changelog
-
-### 0.2.2
-
-- The clean-up of older installs also finds servers registered as `node .../dist/server/index.js` (how
-  the 0.1 README registered a build from source) and reads the configuration from `CLAUDE_CONFIG_DIR`
-  when that is set. Both were found by installing the plugin into an empty configuration next to an
-  old-style registration.
-
-### 0.2.1
-
-- `clast-ai migrate`: finds and removes what older installs left behind (duplicate MCP registrations
-  next to the plugin, entries written by the old VS Code extension, the v0.1 index file). The plugin
-  runs it automatically, once per version, at the first session after an install or update.
-- The plugin uses a global `clast-ai` only when it is at least as new as the plugin itself, so a
-  plugin update is not held back by an older global install.
-
-### 0.2.0
-
-New tools (7 to 13):
-
-- `clast_references`: every use of a symbol, not just calls.
-- `clast_hierarchy`: supertypes, subtypes, implementers and overrides, including Go structural
-  interfaces and Ruby mixins.
-- `clast_overview`: map of a repository or directory.
-- `clast_grep`: text search over all text files with the enclosing symbol on every hit.
-- `clast_changes`: symbols touched by a git diff, plus their callers.
-- `clast_impact`: for one symbol, what has to change with it (declarations, overrides, implementations,
-  overloads), every direct caller by file and line, the reach through indirect callers, and the test
-  files to run, including tests that only reach it through its callers.
-- `clast_unused`: dead code. A name counts as unused when it is never referenced outside its own
-  definitions, or only from other unused code (so a deleted feature's helpers are found with it).
-  Reported separately: code used only by tests, names that still appear in a string, config or
-  template, and (Java, C#, C, C++, Rust) methods whose every call binds to another definition. Left
-  out, with counts: entry points, decorated or attribute-marked symbols, subclasses of library types
-  and their methods, object-literal members, exported Go methods, C# extension classes.
-- `clast_stats`: exact counts grouped by directory, file, kind or name: inventory, symbols by name
-  pattern, direct and indirect subtypes, call sites by name and receiver, text matches, external
-  dependencies, and pattern-based inventories of HTTP / RPC endpoints and database access.
-
-Call graph:
-
-- Calls are resolved at query time using declared receiver types, imports and aliases, field types
-  across files, return types of call chains, inheritance and `super`.
-- Edges are shown as certain, uncertain, or `?` (matched by name only).
-- Argument counts separate overloads. A bare name means all overloads; `path:line` selects one.
-- A call bound to a subclass override no longer counts as a caller of the base method.
-- Language rules: Go packages and structural interfaces, Rust `impl Trait for Arc<T>` and std types,
-  C# generic arity / partial / static classes, Ruby mixins and bare calls, Java static imports, Python
-  submodule calls and imported instances, TypeScript renamed re-exports, C macro bodies, C++ namespace
-  functions.
-
-Search:
-
-- Ranked by exact name, prefix, abbreviation, typo and plain words.
-- Descriptive queries also match what function bodies mention (marked `[body]`).
-- Overloads fold into one hit.
-
-Performance and storage:
-
-- `node:sqlite` on disk (WAL, FTS5) replaces in-memory sql.js.
-- Parsing runs in worker threads, with an inline fallback if a worker fails.
-- The server connects first and indexes afterwards; on a first build, tools wait for the index.
-- A watcher re-indexes changed files, and every tool re-checks the files it quotes.
-
-Other:
-
-- Swift and Dart added (14 languages).
-- All dependencies updated (MCP SDK 1.32, web-tree-sitter 0.27).
-- 291 tests, plus `bench/bench.mjs`, `bench/resolution.mjs` and the A/B harness `bench/ab.mjs`.
-- Installable as a Claude Code plugin from this repository (`/plugin marketplace add xls/clast`,
-  `/plugin install clast@clast`): the MCP server, a usage skill, and the slash commands
-  `/clast:deadcode`, `/clast:impact`, `/clast:audit` and `/clast:status`. The old VS Code extension
-  scaffold that wrote the server into `.claude/settings.local.json` is removed.
-- The navigation tools ask Claude Code to keep them loaded instead of deferring them behind tool
-  search; deferred, the agent never called them.
-- Ruby classes and their ancestors are compared by qualified name (`Rails::Generators::Base` is not
-  `ActiveRecord::Base`; `Thor::Group` is not a project class called `Group`).
-- C++ functions declared through a head-building macro (`FN(jstring, nativeStart)(args)`) are indexed
-  under their real name.
-- C / C++ function pointers whose calling convention is a macro (`err_t (MY_CALL* find)(args)`) are
-  indexed as a field called `find`, not as a method called `err_t`.
-
-### Upgrading from 0.1
-
-How to upgrade: see [Upgrading from an older install](#upgrading-from-an-older-install). What changed:
-
-- Node.js 22.22+ is required (was 18).
-- The index moved from `.clast/clast.db` (sql.js) to `.clast/index.db` (`node:sqlite`). Nothing is
-  migrated: the index is a cache and is rebuilt on first start. The old file is ignored; the plugin
-  (or `clast-ai migrate --apply`) deletes it.
-- A later schema change deletes and rebuilds the index automatically (the schema is at version 26).
-- Tool output is compact text instead of JSON.
-- `clast_call_graph` defaults to depth 1 and gained `within` and `includeTests`.
-- The binary entry point is `dist/cli.js`; `dist/server/index.js` still starts the server for old configs.
-
----
-
-## Known limitations
+</details>
+
+<details>
+<summary><strong>How it works</strong></summary>
+
+1. **Scan.** Walk the tree honouring `.gitignore` and `ignoredPaths`; compare size and modification
+   time with the index, so an unchanged file costs one `stat`.
+2. **Parse.** Changed files are parsed by a pool of worker threads (tree-sitter WebAssembly). A
+   per-language spec turns the syntax tree into symbols, calls (with the receiver and its declared
+   type), imports, inheritance and identifier occurrences.
+3. **Store.** SQLite (`node:sqlite`, WAL) with a full-text index over names, signatures and docs.
+4. **Link at query time.** A call is stored as "symbol A calls name N on receiver R of type T" and
+   resolved when asked, so nothing goes stale when another file changes. Resolution uses the declared
+   receiver type, then imports and same-file definitions, then `this` / `self` and inheritance, then
+   evidence scoring for untyped receivers. Argument counts separate overloads. A call through an
+   interface or base type counts as a caller of the implementations it can reach; a call bound to a
+   subclass override does not count for the base method.
+5. **Stay fresh.** A watcher re-indexes saved files, and every tool re-checks the files it quotes.
+
+The index lives in `.clast/index.db` and takes about 12-25 MB per 1,000 source files. A cold index of
+vscode (15.7k files) takes about 26 s; a restart with nothing changed about 2 s; most queries are
+under 50 ms.
+
+</details>
+
+<details>
+<summary><strong>Known limitations</strong></summary>
 
 - **Untyped receivers**: `obj.save()` in dynamic code cannot be attributed. Such calls are listed as
   "receiver type unknown", not guessed.
+- **Dead code is judged by name**: a member whose name is also used by other symbols (`get`, `run`,
+  `close`) is never listed, so the list is incomplete for common method names. Calls built from
+  strings at run time are only caught when the prefix is a literal (`getattr(x, "as_" + vendor)`).
+  Code found by convention (Django `AppConfig` classes inside Django itself) can be listed wrongly.
+  Treat the list as candidates and let the compiler or the tests confirm a deletion.
 - **Same-named types**: classes with the same short name in different PHP namespaces or Java packages
   can be confused when the calling file gives no hint.
-- **Ruby**: the least exercised language. The rails audit found 4 wrong edges of 18 with one cause
-  (classes called `Base` in different namespaces treated as one family); classes are now compared by
-  qualified name, which fixes that case, but Ruby has not been re-audited since. Methods defined by
-  metaprogramming are invisible.
 - **Overloads**: those that differ only in parameter types, not count, are one target.
 - **Generics and inference**: no generic substitution; TypeScript return types are known only when
   annotated.
 - **Framework conventions**: Django managers, Laravel facades and container lookups, and services
-  injected by string are not modelled.
+  injected by string are not modelled. Endpoint and database statistics are pattern-based.
 - **Python**: a local variable that holds a class is not followed.
-- **Go**: a call through a chain of fields can be attributed to the wrong type; the module path is
-  inferred from imports, not from go.mod.
-- **Swift**: the grammar fails on some files depending on parse order, which can drop a class while
-  keeping its members. Swift and Dart are new and less exercised.
-- **Dead code is judged by name**: a member whose name is also used by other symbols (`get`, `run`,
-  `close`) is never listed, so the list is incomplete for common method names; calls built from
-  strings at run time are only caught when the prefix is a literal (`getattr(x, "as_" + vendor)`).
-  In a spot check of 8-12 random findings per repository (kafka, aspnetcore, vscode, django, tokio,
-  hugo, OnAir) against a word grep, the remaining wrong ones were convention-based discovery (Django
-  `AppConfig` classes inside Django itself). Treat the list as candidates and let the compiler or the
-  tests confirm a deletion.
+- **Go**: the module path is inferred from imports, not from go.mod.
+- **Ruby, Swift, Dart**: the least exercised languages. Ruby methods defined by metaprogramming are
+  invisible; the Swift grammar fails on some files.
 - **Search is lexical**: a description that shares no word with the code finds the neighbourhood, not
   always the function.
 - **Not indexed**: Kotlin, Scala and other languages without a bundled grammar. `clast_grep` still
   searches those files as text.
-- **Size and cold start**: the index takes about 12-25 MB per 1,000 source files; a cold index of
-  vscode takes about 26 s.
+- **Prompt cost**: the tool definitions add about 5k tokens to every session.
+
+More detail and examples: [docs/v0.2-summary.md](docs/v0.2-summary.md).
+
+</details>
 
-The full list with examples is in [docs/v0.2-summary.md](docs/v0.2-summary.md).
+## Try it. Tell us what you think.
 
----
+Point clast at a code base you know well and ask it something you already know the answer to. If an
+answer is wrong, a language construct is missed, or an agent you use needs something different,
+[open an issue](https://github.com/xls/clast/issues). Include the language, the question you asked and
+the clast version (`clast-ai --version`).
 
-## Development
+<details>
+<summary><strong>Working on clast</strong></summary>
 
-```bash
+```sh
 npm install
 npm run build        # tsc
-npm test             # node:test, 260+ tests incl. an end-to-end MCP session
+npm test             # node:test, incl. an end-to-end MCP session
 npm run bench -- /path/to/dir-with-repos
 ```
 
 Adding a language: create `src/parser/langs/<name>.ts` exporting a `LangSpec` (see `typescript.ts` and
-`python.ts` for the two reference implementations), register it in `src/parser/registry.ts`, and add a
-test under `test/langs/`. `clast-ai ast <file>` dumps the syntax tree and `clast-ai parse <file>` shows what
-your spec extracts. The grammar must be available in `@repomix/tree-sitter-wasms`.
+`python.ts`), register it in `src/parser/registry.ts`, and add a test under `test/langs/`.
+`clast-ai ast <file>` dumps the syntax tree and `clast-ai parse <file>` shows what your spec extracts.
+The grammar must be available in `@repomix/tree-sitter-wasms`.
+
+The A/B harness that produced the figures above is `bench/ab.mjs`; the question sets are in `bench/ab/`.
+
+</details>
 
 ## License
 
-MIT
+[MIT](LICENSE). Free to use, modify and share.