codebase-index 2.0.0__tar.gz → 2.1.0__tar.gz

codebase_index-2.1.0/.claude/skills/codebase-index/.skill_version

@@ -0,0 +1 @@
+2.1.0

codebase_index-2.1.0/.claude/skills/codebase-index/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: codebase-index
+description: Use before answering repository questions about architecture, implementation, symbols, references, dependencies, refactoring impact, data flow, or bugs. Query the local hybrid index first so the agent reads only evidence-bearing file:line ranges instead of scanning the repository, and verify evidence gathered earlier before relying on it.
+allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Bash(codebase-index architecture *), Bash(codebase-index symbol *), Bash(codebase-index refs *), Bash(codebase-index impact *), Bash(codebase-index diff-impact *), Bash(codebase-index path *), Bash(codebase-index describe *), Bash(codebase-index verify *), Bash(codebase-index graph *), Bash(codebase-index stats *), Bash(codebase-index doctor *), Bash(codebase-index update *), Bash(codebase-index index *), Bash(cbx *), Read, Grep, Glob
+---
+
+# Codebase Index
+
+Use the local index before reading repository files. It answers with ranked,
+numbered lines, so most answers need no Read and no Grep at all.
+
+## Route the question — always `--compact`
+
+| Intent | Command |
+|---|---|
+| Where / how does X work? | `codebase-index search "X" --compact --session <tag>` |
+| Overview of a feature | `codebase-index explain "X" --compact --session <tag>` |
+| Every caller / call site of X | `codebase-index refs "Owner.member" --compact` |
+| What breaks if X changes (incl. other modules) | `codebase-index impact "Owner.member" --compact` |
+| Find a definition | `codebase-index symbol "X"` |
+| A class: members, who uses it | `codebase-index describe "Class" --json` |
+| What does my diff affect? | `codebase-index diff-impact --json` |
+| Is what I read earlier still true? | `codebase-index verify --session <tag> --json` |
+
+`--compact` prints `path:start-end symbol` per result with the matching lines
+numbered underneath (`  24| public static final String FILE_ID = ...`). Cite
+those lines as `path:24` directly. Read a range only when the lines shown do not
+answer the question — and then only that range, never the whole file.
+
+Name members as `Owner.member` (`TownService.refresh`, `activation::place`,
+`CoreError::ObjectDamaged`) so same-named methods of other types are excluded.
+`refs --compact` lines are `path:line kind caller -> target`: the list of call
+sites with the calling function is usually the whole answer. Add
+`--exclude-tests` for production-only lists and `--path <prefix>` for one module.
+`kind reference` is a non-call use, e.g. an enum variant matched in a `match` arm.
+
+`impact --compact` starts with `# module <m>: build files depending on it: ...`
+— the answer to "does another module depend on this", with no build-file grep.
+
+## Protocol
+
+1. Pick one session tag per conversation (e.g. `auth-fix-1`); pass it to
+   `search`/`explain`. Results already sent in this session print as
+   `(already sent)` — use your earlier copy.
+2. A header saying `index stale` → run `codebase-index update` once; `NO INDEX`
+   → `codebase-index index`.
+3. Batch independent questions into one Bash call (`cmd1; echo ---; cmd2`).
+4. `# partial:` on refs/impact means the list may be incomplete. For
+   `Owner.member` it lists `possible_call` sites (calls on a variable the index
+   cannot type), nearest first: check those few lines, do not grep the repo.
+5. Before relying on evidence from earlier in a long task, run
+   `codebase-index verify --session <tag> --json`.
+6. Grep only when the index returns nothing relevant or for non-code text.
+
+Edge confidence: `extracted` exact, `inferred` heuristic (receiver matched a
+type), `ambiguous` unresolved. Never present an inferred chain as certain.
+
+## Answer
+
+Lead with the answer, then the minimum `file:line` evidence. State uncertainty
+only when evidence is partial, inferred or stale.
+
+Options and JSON fields: [references/commands.md](references/commands.md),
+[references/response-contract.md](references/response-contract.md),
+session memory: [references/memory.md](references/memory.md).

{codebase_index-2.0.0 → codebase_index-2.1.0}/.claude/skills/codebase-index/references/commands.md

@@ -37,6 +37,24 @@ codebase-index describe "<file-or-symbol>" --json
 
 - `architecture` reads module analysis cached at index time.
 - `refs` finds definitions, calls, and graph-backed references.
+  For a method whose name several types share, pass `Owner.member`
+  (`TownService.refresh`, or `module::fn` for a top-level function); each site
+  names its `caller` and the `target` it resolved to. Calls the index cannot type
+  (`chest.holdings().take(..)`) come back as `possible_call`, nearest first, with
+  `coverage.partial: true`: read those before claiming a complete list.
+  `impact` and `symbol` accept the same form.
+  Filters: `--exclude-tests`, `--path <prefix>` (repeatable). `--compact` prints
+  `path:line kind caller -> target [confidence]`, one site per line.
+- `search`, `explain` and `impact` also take `--compact`: agent text instead of
+  JSON. For search/explain, each result is `path:start-end symbols` followed by up
+  to eight numbered lines that carry the match (rarer query words first);
+  evidence already sent to the session prints as `(already sent)`. For impact,
+  one `d<hops> path:line name via edge` line per node, after a
+  `# module ...` line naming the build files that depend on the target's module.
+- `symbol` returns exact matches alone when there are any and reports how many
+  prefix matches it left out (`more_prefix_matches`); `--exact` drops them.
+- `describe` on a class, enum, struct or trait also lists its `members` and
+  folds their edges into `used_by` / `uses` (code outside the type).
 - `impact` walks dependents (`up`), dependencies (`down`), or both.
 - `diff-impact` aggregates impact for tracked changes relative to a verified
   Git commit; new or excluded files are reported as unresolved.

{codebase_index-2.0.0 → codebase_index-2.1.0}/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "codebase-index",
   "displayName": "Codebase Index",
   "description": "Give Claude a precise local map of your codebase: find implementations, trace behavior, and predict change impact with file-line evidence.",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "author": {
     "name": "codebase-index contributors"
   },

codebase_index-2.1.0/.codex/skills/codebase-index/.skill_version

@@ -0,0 +1 @@
+2.1.0

codebase_index-2.1.0/.codex/skills/codebase-index/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: codebase-index
+description: Use before answering repository questions about architecture, implementation, symbols, references, dependencies, refactoring impact, data flow, or bugs. Query the local hybrid index first so the agent reads only evidence-bearing file:line ranges instead of scanning the repository, and verify evidence gathered earlier before relying on it.
+allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Bash(codebase-index architecture *), Bash(codebase-index symbol *), Bash(codebase-index refs *), Bash(codebase-index impact *), Bash(codebase-index diff-impact *), Bash(codebase-index path *), Bash(codebase-index describe *), Bash(codebase-index verify *), Bash(codebase-index graph *), Bash(codebase-index stats *), Bash(codebase-index doctor *), Bash(codebase-index update *), Bash(codebase-index index *), Bash(cbx *), Read, Grep, Glob
+---
+
+# Codebase Index
+
+Use the local index before reading repository files. It answers with ranked,
+numbered lines, so most answers need no Read and no Grep at all.
+
+## Route the question — always `--compact`
+
+| Intent | Command |
+|---|---|
+| Where / how does X work? | `codebase-index search "X" --compact --session <tag>` |
+| Overview of a feature | `codebase-index explain "X" --compact --session <tag>` |
+| Every caller / call site of X | `codebase-index refs "Owner.member" --compact` |
+| What breaks if X changes (incl. other modules) | `codebase-index impact "Owner.member" --compact` |
+| Find a definition | `codebase-index symbol "X"` |
+| A class: members, who uses it | `codebase-index describe "Class" --json` |
+| What does my diff affect? | `codebase-index diff-impact --json` |
+| Is what I read earlier still true? | `codebase-index verify --session <tag> --json` |
+
+`--compact` prints `path:start-end symbol` per result with the matching lines
+numbered underneath (`  24| public static final String FILE_ID = ...`). Cite
+those lines as `path:24` directly. Read a range only when the lines shown do not
+answer the question — and then only that range, never the whole file.
+
+Name members as `Owner.member` (`TownService.refresh`, `activation::place`,
+`CoreError::ObjectDamaged`) so same-named methods of other types are excluded.
+`refs --compact` lines are `path:line kind caller -> target`: the list of call
+sites with the calling function is usually the whole answer. Add
+`--exclude-tests` for production-only lists and `--path <prefix>` for one module.
+`kind reference` is a non-call use, e.g. an enum variant matched in a `match` arm.
+
+`impact --compact` starts with `# module <m>: build files depending on it: ...`
+— the answer to "does another module depend on this", with no build-file grep.
+
+## Protocol
+
+1. Pick one session tag per conversation (e.g. `auth-fix-1`); pass it to
+   `search`/`explain`. Results already sent in this session print as
+   `(already sent)` — use your earlier copy.
+2. A header saying `index stale` → run `codebase-index update` once; `NO INDEX`
+   → `codebase-index index`.
+3. Batch independent questions into one Bash call (`cmd1; echo ---; cmd2`).
+4. `# partial:` on refs/impact means the list may be incomplete. For
+   `Owner.member` it lists `possible_call` sites (calls on a variable the index
+   cannot type), nearest first: check those few lines, do not grep the repo.
+5. Before relying on evidence from earlier in a long task, run
+   `codebase-index verify --session <tag> --json`.
+6. Grep only when the index returns nothing relevant or for non-code text.
+
+Edge confidence: `extracted` exact, `inferred` heuristic (receiver matched a
+type), `ambiguous` unresolved. Never present an inferred chain as certain.
+
+## Answer
+
+Lead with the answer, then the minimum `file:line` evidence. State uncertainty
+only when evidence is partial, inferred or stale.
+
+Options and JSON fields: [references/commands.md](references/commands.md),
+[references/response-contract.md](references/response-contract.md),
+session memory: [references/memory.md](references/memory.md).

{codebase_index-2.0.0/.opencode → codebase_index-2.1.0/.codex}/skills/codebase-index/references/commands.md

@@ -37,6 +37,24 @@ codebase-index describe "<file-or-symbol>" --json
 
 - `architecture` reads module analysis cached at index time.
 - `refs` finds definitions, calls, and graph-backed references.
+  For a method whose name several types share, pass `Owner.member`
+  (`TownService.refresh`, or `module::fn` for a top-level function); each site
+  names its `caller` and the `target` it resolved to. Calls the index cannot type
+  (`chest.holdings().take(..)`) come back as `possible_call`, nearest first, with
+  `coverage.partial: true`: read those before claiming a complete list.
+  `impact` and `symbol` accept the same form.
+  Filters: `--exclude-tests`, `--path <prefix>` (repeatable). `--compact` prints
+  `path:line kind caller -> target [confidence]`, one site per line.
+- `search`, `explain` and `impact` also take `--compact`: agent text instead of
+  JSON. For search/explain, each result is `path:start-end symbols` followed by up
+  to eight numbered lines that carry the match (rarer query words first);
+  evidence already sent to the session prints as `(already sent)`. For impact,
+  one `d<hops> path:line name via edge` line per node, after a
+  `# module ...` line naming the build files that depend on the target's module.
+- `symbol` returns exact matches alone when there are any and reports how many
+  prefix matches it left out (`more_prefix_matches`); `--exact` drops them.
+- `describe` on a class, enum, struct or trait also lists its `members` and
+  folds their edges into `used_by` / `uses` (code outside the type).
 - `impact` walks dependents (`up`), dependencies (`down`), or both.
 - `diff-impact` aggregates impact for tracked changes relative to a verified
   Git commit; new or excluded files are reported as unresolved.

codebase_index-2.1.0/.opencode/skills/codebase-index/.skill_version

@@ -0,0 +1 @@
+2.1.0

codebase_index-2.1.0/.opencode/skills/codebase-index/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: codebase-index
+description: Use before answering repository questions about architecture, implementation, symbols, references, dependencies, refactoring impact, data flow, or bugs. Query the local hybrid index first so the agent reads only evidence-bearing file:line ranges instead of scanning the repository, and verify evidence gathered earlier before relying on it.
+allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Bash(codebase-index architecture *), Bash(codebase-index symbol *), Bash(codebase-index refs *), Bash(codebase-index impact *), Bash(codebase-index diff-impact *), Bash(codebase-index path *), Bash(codebase-index describe *), Bash(codebase-index verify *), Bash(codebase-index graph *), Bash(codebase-index stats *), Bash(codebase-index doctor *), Bash(codebase-index update *), Bash(codebase-index index *), Bash(cbx *), Read, Grep, Glob
+---
+
+# Codebase Index
+
+Use the local index before reading repository files. It answers with ranked,
+numbered lines, so most answers need no Read and no Grep at all.
+
+## Route the question — always `--compact`
+
+| Intent | Command |
+|---|---|
+| Where / how does X work? | `codebase-index search "X" --compact --session <tag>` |
+| Overview of a feature | `codebase-index explain "X" --compact --session <tag>` |
+| Every caller / call site of X | `codebase-index refs "Owner.member" --compact` |
+| What breaks if X changes (incl. other modules) | `codebase-index impact "Owner.member" --compact` |
+| Find a definition | `codebase-index symbol "X"` |
+| A class: members, who uses it | `codebase-index describe "Class" --json` |
+| What does my diff affect? | `codebase-index diff-impact --json` |
+| Is what I read earlier still true? | `codebase-index verify --session <tag> --json` |
+
+`--compact` prints `path:start-end symbol` per result with the matching lines
+numbered underneath (`  24| public static final String FILE_ID = ...`). Cite
+those lines as `path:24` directly. Read a range only when the lines shown do not
+answer the question — and then only that range, never the whole file.
+
+Name members as `Owner.member` (`TownService.refresh`, `activation::place`,
+`CoreError::ObjectDamaged`) so same-named methods of other types are excluded.
+`refs --compact` lines are `path:line kind caller -> target`: the list of call
+sites with the calling function is usually the whole answer. Add
+`--exclude-tests` for production-only lists and `--path <prefix>` for one module.
+`kind reference` is a non-call use, e.g. an enum variant matched in a `match` arm.
+
+`impact --compact` starts with `# module <m>: build files depending on it: ...`
+— the answer to "does another module depend on this", with no build-file grep.
+
+## Protocol
+
+1. Pick one session tag per conversation (e.g. `auth-fix-1`); pass it to
+   `search`/`explain`. Results already sent in this session print as
+   `(already sent)` — use your earlier copy.
+2. A header saying `index stale` → run `codebase-index update` once; `NO INDEX`
+   → `codebase-index index`.
+3. Batch independent questions into one Bash call (`cmd1; echo ---; cmd2`).
+4. `# partial:` on refs/impact means the list may be incomplete. For
+   `Owner.member` it lists `possible_call` sites (calls on a variable the index
+   cannot type), nearest first: check those few lines, do not grep the repo.
+5. Before relying on evidence from earlier in a long task, run
+   `codebase-index verify --session <tag> --json`.
+6. Grep only when the index returns nothing relevant or for non-code text.
+
+Edge confidence: `extracted` exact, `inferred` heuristic (receiver matched a
+type), `ambiguous` unresolved. Never present an inferred chain as certain.
+
+## Answer
+
+Lead with the answer, then the minimum `file:line` evidence. State uncertainty
+only when evidence is partial, inferred or stale.
+
+Options and JSON fields: [references/commands.md](references/commands.md),
+[references/response-contract.md](references/response-contract.md),
+session memory: [references/memory.md](references/memory.md).

{codebase_index-2.0.0/.codex → codebase_index-2.1.0/.opencode}/skills/codebase-index/references/commands.md

@@ -37,6 +37,24 @@ codebase-index describe "<file-or-symbol>" --json
 
 - `architecture` reads module analysis cached at index time.
 - `refs` finds definitions, calls, and graph-backed references.
+  For a method whose name several types share, pass `Owner.member`
+  (`TownService.refresh`, or `module::fn` for a top-level function); each site
+  names its `caller` and the `target` it resolved to. Calls the index cannot type
+  (`chest.holdings().take(..)`) come back as `possible_call`, nearest first, with
+  `coverage.partial: true`: read those before claiming a complete list.
+  `impact` and `symbol` accept the same form.
+  Filters: `--exclude-tests`, `--path <prefix>` (repeatable). `--compact` prints
+  `path:line kind caller -> target [confidence]`, one site per line.
+- `search`, `explain` and `impact` also take `--compact`: agent text instead of
+  JSON. For search/explain, each result is `path:start-end symbols` followed by up
+  to eight numbered lines that carry the match (rarer query words first);
+  evidence already sent to the session prints as `(already sent)`. For impact,
+  one `d<hops> path:line name via edge` line per node, after a
+  `# module ...` line naming the build files that depend on the target's module.
+- `symbol` returns exact matches alone when there are any and reports how many
+  prefix matches it left out (`more_prefix_matches`); `--exact` drops them.
+- `describe` on a class, enum, struct or trait also lists its `members` and
+  folds their edges into `used_by` / `uses` (code outside the type).
 - `impact` walks dependents (`up`), dependencies (`down`), or both.
 - `diff-impact` aggregates impact for tracked changes relative to a verified
   Git commit; new or excluded files are reported as unresolved.

{codebase_index-2.0.0 → codebase_index-2.1.0}/CHANGELOG.md

@@ -6,6 +6,101 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-09-24
+
+Agent-efficiency release. An agent answering five code questions on a 5.9k-file
+Java/Rust monorepo spent **19% fewer tokens (83.5k vs 103.0k) and 25% fewer tool calls
+(9 vs 12)** with the skill than with Grep/Read alone, three runs per arm, with no
+overlap between the arms' ranges; before this release the two were at parity. The
+gain comes from answer-ready output (`--compact`: ranked files with numbered matching
+lines), `refs`/`impact` that resolve `Owner.member` targets exactly and say when a list
+may be incomplete, build-module awareness in `impact`, and ranking measured over 342
+queries (MRR +0.010, p=0.031). Index schema 4: the first `update` rebuilds the index
+once.
+
+### Fixed
+
+- `refs`, `impact` and `symbol` accept a qualified `Owner.member` target
+  (`TownService.refresh`, also `pkg.Owner.member`, `Owner::member`, `Owner#member`),
+  where the owner is a type or a module (`activation::place`). Before, a qualified name
+  matched nothing and a bare name that several types share (`refresh`) returned every
+  same-named method's callers mixed together.
+- Calls written against a type or module (`TownService.refresh(server)`, `Foo::new()`,
+  `activation::place(..)`) now resolve across files when exactly one type or module of
+  that name defines the callee, so `impact` walks them. These edges are marked
+  `inferred`.
+- Call resolution no longer invents edges: a call never binds across languages (a
+  Python `queue.take()` to a Java `take`), a call on another type
+  (`ApprenticeService.take`) no longer binds to the repo's only `take` when that one
+  belongs to a different type, and a call on a type the file does not define no
+  longer binds to a same-named method in the calling file. Name uniqueness is now
+  judged per language family (JVM, JS/TS, C/C++), so a Rust `place` resolves even
+  when Java also defines one.
+- `refs "Owner.member"` no longer reports a confident empty answer when calls it
+  cannot type exist (`chest.holdings().take(..)`): they are listed as
+  `possible_call`, nearest to the definition first, and `coverage.partial` is true.
+- `refs` and `impact` report `coverage.partial: true` with a reason when the target
+  matches no indexed definition or call site, instead of an empty answer that looked
+  like "no callers".
+- `update` parses changed files in a process pool, like a full build. It used to parse
+  them one at a time, so a large change set was slower to update than to rebuild
+  (2009 changed files: 149 s, against 13 s for a full build of all 5904).
+- A class is returned instead of its same-named constructor. The constructor's
+  `new X()` callers gave it the higher in-degree, so it took the file's one slot on
+  the page with a one-line body while the class never appeared.
+- Kotlin call sites are extracted (with their receiver). Kotlin's `call_expression`
+  has no named fields, so no Kotlin call edge was ever recorded.
+
+### Added
+
+- Rust enum variants, Java enum constants and C# enum members are indexed as
+  `variant` symbols (`CoreError.ObjectDamaged`), and a Rust `Owner::name` path used in a
+  pattern or as a value (`Err(CoreError::ObjectDamaged(_)) =>`, `if let Kind::A = ..`)
+  is recorded as a `reference` edge. `refs` reports these as `kind: "reference"`, so it
+  finds where a variant is handled, not only where it is constructed.
+- `refs --exclude-tests`, `refs --path <prefix>` (repeatable; also on the MCP
+  `find_refs` tool) and `refs --compact`, which prints one line per site:
+  `path:line kind caller -> target [confidence]`.
+- `describe` on a class, enum, struct or trait lists its `members` and folds their
+  edges from and to code outside the type into `used_by` / `uses`. It used to report
+  zero callers and callees for a class, whose methods, not the class, are called.
+- `--session` is accepted by `symbol`, `refs` and `impact`, so one tag can be passed to
+  every read command.
+- `search --compact` / `explain --compact`: agent text instead of JSON. Each result is
+  `path:start-end symbols` with up to eight numbered lines underneath that carry the
+  match (rarer query words first), so an agent can cite `file:line` without a Read or
+  a `grep -n`. On a benchmark query the packet went from 9.6 KB of JSON to 3.7 KB.
+  Evidence already sent to the session prints as `(already sent)`.
+- `impact --compact`, and a `modules` field on `impact`: the build-system module the
+  target lives in (Gradle, Maven, Cargo, npm, Go, Python) and the lines of other
+  build files that name it, split into workspace membership and dependencies. "Does
+  another module depend on this?" no longer needs a grep over build files.
+- The skill routes every question through `--compact` and is 40% shorter.
+
+### Changed
+
+- Ranking, measured over 342 queries on six query sets (five repositories, including
+  24 natural-language "how does X work" questions): MRR +0.010 (p=0.036), recall@10
+  +0.015 (p=0.038), nDCG@10 +0.009 (p=0.018), useful@budget +0.020 (p=0.015), 15 fewer
+  snippet tokens per query; no corpus regressed. On the natural-language questions MRR
+  went 0.428 → 0.475 and recall@10 0.708 → 0.833. Three signals, each ablatable:
+  - `resource_priors`: localisation catalogues (`lang/en_us.json`, `i18n/*.json`,
+    `.po`) and workflow artifacts (review `.diff`/`.patch` files, agent scratch
+    directories such as `.superpowers/`) are demoted like generated code;
+  - `stem_match`: a file named after a query term (`Treasury.java` for a question
+    about the treasury) gets a small bonus;
+  - `question_pool_floor`: a question-form query ("how is a crop loaded") gets a
+    40-deep candidate pool, so the class it paraphrases reaches the reranker.
+- `symbol` returns exact matches alone when there are any, with a count of the prefix
+  matches it left out (`more_prefix_matches`), instead of burying the one symbol asked
+  for among twenty `TreasuryX` prefix matches.
+
+- Every `refs` site carries `caller` (the function it sits in), `target` (the
+  definition it resolved to) and `receiver` (what the call was made on), so callers can
+  be named and same-named methods told apart without reading each file.
+- Index schema 4: call edges store their receiver. The first `update` after upgrading
+  rebuilds the index once; read commands keep working on an older index until then.
+
 ## [2.0.0] - 2026-09-14
 
 Evidence release. Everything an agent reads through `codebase-index` is now identified
@@ -773,7 +868,8 @@ Pooled over 305 queries (Python, Java, TypeScript), v1.8.0 → 1.9.0:
 - Hooks example + `watch` mode for keeping the index fresh without blocking the edit loop (M8).
 - `doctor`, `stats`, `clean` diagnostics/maintenance commands.
 
-[Unreleased]: https://github.com/denfry/codebase-index/compare/v2.0.0...HEAD
+[Unreleased]: https://github.com/denfry/codebase-index/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/denfry/codebase-index/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/denfry/codebase-index/compare/v1.9.0...v2.0.0
 [1.10.0]: https://github.com/denfry/codebase-index/compare/v1.9.0...abb67df
 [1.9.0]: https://github.com/denfry/codebase-index/compare/v1.8.0...v1.9.0

{codebase_index-2.0.0 → codebase_index-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebase-index
-Version: 2.0.0
+Version: 2.1.0
 Summary: A precise local codebase map for AI coding agents: find, trace, and predict with file-line evidence.
 Project-URL: Homepage, https://github.com/denfry/codebase-index
 Project-URL: Documentation, https://github.com/denfry/codebase-index/tree/main/docs
@@ -180,13 +180,16 @@ affected files (8): src/flask/app.py, src/flask/ctx.py, src/flask/globals.py, ..
 
 More: `explain "how are blueprints registered"`, `describe dispatch_request`,
 `architecture` (modules, god nodes, surprising links), `graph User --output graph.html`.
-Add `--json` to any command for the machine-readable packet.
+Name a method as `Owner.member` (`SessionInterface.open_session`) to leave out
+same-named methods of other types. Add `--json` to any command for the
+machine-readable packet, or `--compact` (search, explain, refs, impact) for the
+agent format: `path:start-end symbol` with the matching lines numbered underneath.
 
 ## Agent integrations
 
 | Agent | Setup | What it gets |
 |---|---|---|
-| **Claude Code** | `codebase-index init --target claude`, or the plugin: `/plugin marketplace add denfry/codebase-index` then `/plugin install codebase-index@codebase-index` | A skill that routes repository questions to the index and reads only `recommended_reads` ranges; optional PostToolUse hook keeps the index fresh |
+| **Claude Code** | `codebase-index init --target claude`, or the plugin: `/plugin marketplace add denfry/codebase-index` then `/plugin install codebase-index@codebase-index` | A skill that routes repository questions to the index and answers from `--compact` output (ranked files with numbered matching lines, `refs` with the calling function per site); optional PostToolUse hook keeps the index fresh |
 | **Codex CLI** | `codebase-index init --target codex` | A managed block in `AGENTS.md` plus the skill resources |
 | **OpenCode** | `codebase-index init --target opencode` | `/codebase-index` command, agent file, skill resources |
 | **Any MCP client** (Claude Desktop, Cursor, VS Code, Zed, Windsurf, ...) | `pip install "codebase-index[mcp]"` then `codebase-index mcp --root /path/to/repo` | 11 tools (`search_code`, `find_refs`, `impact_of`, `impact_of_diff`, `path_between`, ...) with a versioned JSON envelope |
@@ -222,10 +225,14 @@ significant on a pooled multi-language query set
 ([tests/eval](tests/eval/README.md)). 1.9.0 removed two signals that could not
 show a benefit and rejected five plausible ones.
 
-**What is not measured yet**: whether an *agent* completes tasks better with the
-index. That needs model calls and a rubric and is the top item in
-[BENCHMARKS.md](docs/BENCHMARKS.md#future-work-in-priority-order). Please do not
-quote task-success numbers for this project; there are none.
+**Agent pilot (2.1.0).** The same five code questions on a 5.9k-file Java/Rust
+monorepo, answered by a coding agent three times with the skill and three times with
+Grep/Read only: **19% fewer tokens and 25% fewer tool calls** with the skill, all
+answers correct in both arms, no overlap between the arms' token ranges. It is one
+private repository and five questions, so read it as a direction:
+[raw runs and caveats](tests/eval/results/2026-09-24-agent-pilot.md). A broader
+task-level evaluation is still the top item in
+[BENCHMARKS.md](docs/BENCHMARKS.md#future-work-in-priority-order).
 
 ## How it works
 

{codebase_index-2.0.0 → codebase_index-2.1.0}/README.md

@@ -130,13 +130,16 @@ affected files (8): src/flask/app.py, src/flask/ctx.py, src/flask/globals.py, ..
 
 More: `explain "how are blueprints registered"`, `describe dispatch_request`,
 `architecture` (modules, god nodes, surprising links), `graph User --output graph.html`.
-Add `--json` to any command for the machine-readable packet.
+Name a method as `Owner.member` (`SessionInterface.open_session`) to leave out
+same-named methods of other types. Add `--json` to any command for the
+machine-readable packet, or `--compact` (search, explain, refs, impact) for the
+agent format: `path:start-end symbol` with the matching lines numbered underneath.
 
 ## Agent integrations
 
 | Agent | Setup | What it gets |
 |---|---|---|
-| **Claude Code** | `codebase-index init --target claude`, or the plugin: `/plugin marketplace add denfry/codebase-index` then `/plugin install codebase-index@codebase-index` | A skill that routes repository questions to the index and reads only `recommended_reads` ranges; optional PostToolUse hook keeps the index fresh |
+| **Claude Code** | `codebase-index init --target claude`, or the plugin: `/plugin marketplace add denfry/codebase-index` then `/plugin install codebase-index@codebase-index` | A skill that routes repository questions to the index and answers from `--compact` output (ranked files with numbered matching lines, `refs` with the calling function per site); optional PostToolUse hook keeps the index fresh |
 | **Codex CLI** | `codebase-index init --target codex` | A managed block in `AGENTS.md` plus the skill resources |
 | **OpenCode** | `codebase-index init --target opencode` | `/codebase-index` command, agent file, skill resources |
 | **Any MCP client** (Claude Desktop, Cursor, VS Code, Zed, Windsurf, ...) | `pip install "codebase-index[mcp]"` then `codebase-index mcp --root /path/to/repo` | 11 tools (`search_code`, `find_refs`, `impact_of`, `impact_of_diff`, `path_between`, ...) with a versioned JSON envelope |
@@ -172,10 +175,14 @@ significant on a pooled multi-language query set
 ([tests/eval](tests/eval/README.md)). 1.9.0 removed two signals that could not
 show a benefit and rejected five plausible ones.
 
-**What is not measured yet**: whether an *agent* completes tasks better with the
-index. That needs model calls and a rubric and is the top item in
-[BENCHMARKS.md](docs/BENCHMARKS.md#future-work-in-priority-order). Please do not
-quote task-success numbers for this project; there are none.
+**Agent pilot (2.1.0).** The same five code questions on a 5.9k-file Java/Rust
+monorepo, answered by a coding agent three times with the skill and three times with
+Grep/Read only: **19% fewer tokens and 25% fewer tool calls** with the skill, all
+answers correct in both arms, no overlap between the arms' token ranges. It is one
+private repository and five questions, so read it as a direction:
+[raw runs and caveats](tests/eval/results/2026-09-24-agent-pilot.md). A broader
+task-level evaluation is still the top item in
+[BENCHMARKS.md](docs/BENCHMARKS.md#future-work-in-priority-order).
 
 ## How it works
 

{codebase_index-2.0.0 → codebase_index-2.1.0}/docs/BENCHMARKS.md

@@ -178,6 +178,25 @@ Every ranking signal that ships has an ablation row. 1.9.0 removed two signals
 that could not demonstrate a benefit and rejected several plausible ones
 (IDF-weighted coverage, stemming, graph propagation, MMR, a file-length prior).
 
+## Agent pilot (2.1.0)
+
+The first task-level measurement: five code questions on one private 5.9k-file
+Java/Rust monorepo, a Claude Code subagent answering each set three times with the
+skill and three times with Grep/Read only
+([raw runs, questions, ground truth, caveats](../tests/eval/results/2026-09-24-agent-pilot.md)).
+
+| arm | mean tokens | range | mean tool calls | correct |
+|---|---:|---|---:|---|
+| skill 2.1.0 | **83.5k** | 82.1k–85.0k | **9.0** | 15/15 |
+| Grep/Read only | 103.0k | 98.7k–107.1k | 12.0 | 15/15 |
+| skill, pre-2.1.0 template | 100.6k | 96.1k–103.5k | 16.7 | 15/15 |
+
+The 2.1.0 ranking changes were gated separately over 342 queries (six query sets,
+five repositories, 24 of them natural-language questions): MRR +0.010 (p=0.031),
+recall@10 +0.019 (p=0.017), nDCG@10 +0.011 (p=0.005), useful@budget +0.022
+(p=0.008), no corpus regressing
+([log](../tests/eval/results/2026-09-24-retrieval-2.1.0.txt)).
+
 ## Evidence memory
 
 `tests/eval/memory_eval.py` replays a repository's own history: for every git-derived
@@ -223,16 +242,15 @@ Do not write, imply, or ship any of these until a run with published logs exists
 - Any *token savings* multiplier without naming the read model. Under
   symmetric accounting the index costs about the same as disciplined grep.
 - Latency comparisons against external tools.
-- Any statement about *LLM agent task success*. The baselines here are
-  retrieval metrics; nobody has measured whether an agent with the index
-  finishes tasks faster or better. That is the most important open item.
+- Any general statement about *LLM agent task success* or savings beyond the
+  pilot above (one private repository, five questions, one model). Quote the
+  pilot with its scope or not at all.
 
 ## Future work, in priority order
 
-1. **Agent task-level evaluation**: the same questions, an actual coding agent
-   (Claude Code or Codex CLI) with and without the skill, measuring answer
-   correctness, files read, tokens, and wall time. Needs model calls and a
-   grading rubric; not started.
+1. **Agent task-level evaluation**: the pilot above covers one repository and
+   five questions. Next: public repositories, natural-language and debugging
+   tasks, more runs per arm, and a second agent (Codex CLI).
 2. **Large repository run**: a 500k–1M LOC monorepo, reporting index build
    time, incremental update latency, memory, and the same retrieval metrics.
 3. **Graph task benchmark**: hand-labelled `refs`, `impact`, and

{codebase_index-2.0.0 → codebase_index-2.1.0}/docs/installer.md

@@ -110,7 +110,7 @@ pwsh ./install.ps1 -Target claude -InstallDir "D:\skills\codebase-index"
 **Pin to a branch or tag** (reproducibility and safety):
 
 ```sh
-sh install.sh --branch v2.0.0
+sh install.sh --branch v2.1.0
 ```
 
 ---

{codebase_index-2.0.0 → codebase_index-2.1.0}/requirements.lock

@@ -1,3 +1,3 @@
-codebase-index @ https://github.com/denfry/codebase-index/archive/refs/tags/v2.0.0.tar.gz
+codebase-index @ https://github.com/denfry/codebase-index/archive/refs/tags/v2.1.0.tar.gz
 tree-sitter==0.25.2
 tree-sitter-language-pack==1.8.1

codebase_index-2.1.0/skill/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: codebase-index
+description: Use before answering repository questions about architecture, implementation, symbols, references, dependencies, refactoring impact, data flow, or bugs. Query the local hybrid index first so the agent reads only evidence-bearing file:line ranges instead of scanning the repository, and verify evidence gathered earlier before relying on it.
+allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Bash(codebase-index architecture *), Bash(codebase-index symbol *), Bash(codebase-index refs *), Bash(codebase-index impact *), Bash(codebase-index diff-impact *), Bash(codebase-index path *), Bash(codebase-index describe *), Bash(codebase-index verify *), Bash(codebase-index graph *), Bash(codebase-index stats *), Bash(codebase-index doctor *), Bash(codebase-index update *), Bash(codebase-index index *), Bash(cbx *), Read, Grep, Glob
+---
+
+# Codebase Index
+
+Use the local index before reading repository files. It answers with ranked,
+numbered lines, so most answers need no Read and no Grep at all.
+
+## Route the question — always `--compact`
+
+| Intent | Command |
+|---|---|
+| Where / how does X work? | `codebase-index search "X" --compact --session <tag>` |
+| Overview of a feature | `codebase-index explain "X" --compact --session <tag>` |
+| Every caller / call site of X | `codebase-index refs "Owner.member" --compact` |
+| What breaks if X changes (incl. other modules) | `codebase-index impact "Owner.member" --compact` |
+| Find a definition | `codebase-index symbol "X"` |
+| A class: members, who uses it | `codebase-index describe "Class" --json` |
+| What does my diff affect? | `codebase-index diff-impact --json` |
+| Is what I read earlier still true? | `codebase-index verify --session <tag> --json` |
+
+`--compact` prints `path:start-end symbol` per result with the matching lines
+numbered underneath (`  24| public static final String FILE_ID = ...`). Cite
+those lines as `path:24` directly. Read a range only when the lines shown do not
+answer the question — and then only that range, never the whole file.
+
+Name members as `Owner.member` (`TownService.refresh`, `activation::place`,
+`CoreError::ObjectDamaged`) so same-named methods of other types are excluded.
+`refs --compact` lines are `path:line kind caller -> target`: the list of call
+sites with the calling function is usually the whole answer. Add
+`--exclude-tests` for production-only lists and `--path <prefix>` for one module.
+`kind reference` is a non-call use, e.g. an enum variant matched in a `match` arm.
+
+`impact --compact` starts with `# module <m>: build files depending on it: ...`
+— the answer to "does another module depend on this", with no build-file grep.
+
+## Protocol
+
+1. Pick one session tag per conversation (e.g. `auth-fix-1`); pass it to
+   `search`/`explain`. Results already sent in this session print as
+   `(already sent)` — use your earlier copy.
+2. A header saying `index stale` → run `codebase-index update` once; `NO INDEX`
+   → `codebase-index index`.
+3. Batch independent questions into one Bash call (`cmd1; echo ---; cmd2`).
+4. `# partial:` on refs/impact means the list may be incomplete. For
+   `Owner.member` it lists `possible_call` sites (calls on a variable the index
+   cannot type), nearest first: check those few lines, do not grep the repo.
+5. Before relying on evidence from earlier in a long task, run
+   `codebase-index verify --session <tag> --json`.
+6. Grep only when the index returns nothing relevant or for non-code text.
+
+Edge confidence: `extracted` exact, `inferred` heuristic (receiver matched a
+type), `ambiguous` unresolved. Never present an inferred chain as certain.
+
+## Answer
+
+Lead with the answer, then the minimum `file:line` evidence. State uncertainty
+only when evidence is partial, inferred or stale.
+
+Options and JSON fields: [references/commands.md](references/commands.md),
+[references/response-contract.md](references/response-contract.md),
+session memory: [references/memory.md](references/memory.md).