@javierkaiser/opencode-indexing 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,61 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-10-16
+
+### Documentation
+- The README's code-graph section is no longer a roadmap. It said the plugin
+  "deliberately stays on the semantic side" and offered `indexing_graph_*` tools
+  as a future major version — both untrue once codegraph became a companion.
+  Rewritten around the two indexes: what each costs to keep fresh, what the
+  benchmark does and does not measure, how to move from one to the other, and an
+  explicit note that the graph tools are withdrawn rather than pending. The
+  install-time detail moved to *Install*, where `--with-codegraph` already
+  lives, instead of being restated here.
+
+### Fixed
+- **The installer named the wrong package.** `install.mjs` and the skip message
+  in `src/codegraph.ts` both said `codegraph`, which on npm is an unrelated 2024
+  library by a different author with no binary at all. `npm install -g codegraph`
+  exits 0, puts nothing on `PATH`, and the step then reports success — the worst
+  shape of failure for an installer. The real package is
+  `@colbymchenry/codegraph`, which is what the CLI already on this machine came
+  from. Both call sites now use the scoped name, and a test reads `install.mjs`
+  and asserts the unscoped install never appears.
+- **The PowerShell wrapper could not pass `--with-codegraph`.** `install.mjs`
+  implemented the flag and `install.sh` forwards every argument, but
+  `install.ps1` declared only five switches, so on Windows the recommended
+  install was impossible through the wrapper. The switch exists now, and both
+  wrappers record the preferred `npx` form.
+- The prompt-footer skill now tells the model that codegraph exists. It listed
+  `Grep` as the answer for exact symbols and never mentioned the graph tools at
+  all, so an assistant had no way to know the structural half was available —
+  the same class of problem as an indicator that renders nothing: the capability
+  was there and invisible. The guidance is conditional on the MCP server being
+  present, because it is optional.
+- `THIRD_PARTY_NOTICES.md` was missing four packages it distributes:
+  `solid-js`, `@opentui/core`, `@opentui/solid` (shipped since 0.2.4) and
+  `apache-arrow`, which had never been listed. Licenses read from the installed
+  manifests, not from memory. CodeGraph gets its own section: not bundled, MIT
+  per its manifest, and the license text is linked rather than reproduced
+  because the package ships no `LICENSE` file and declares no author, so there
+  is no copyright line this project can verify.
+- *How it works* and *Where each index lives* now show codegraph. The diagram
+  had one index and the table had two; there are three.
+- `indexing_search` and `indexing_status` descriptions mention the companion.
+
+### CI
+- The release workflow now creates the GitHub Release itself, attaching the
+  tarball that was actually published and taking its notes from this file. It
+  also stopped hiding its own failures: the download ran under `--silent`
+  inside a `pipefail` pipeline, so a registry hiccup failed the step with no
+  output at all to explain it — which is how three versions shipped without a
+  release page.
+- Dependabot groups only what can move together. The old type-based groups
+  paired dependencies that contradict each other (`apache-arrow` against
+  `@lancedb/lancedb`'s peer ceiling, `@opencode/plugin` against the pinned
+  `@opentui` packages), and `npm ci` failed with ERESOLVE before any test ran.
+
 ## [0.3.0] - 2026-10-16
 
 ### Added
@@ -282,7 +337,12 @@ First public release.
 - Cross-platform installer (`install.mjs`, plus `install.sh` / `install.ps1`
   wrappers).
 
-[Unreleased]: https://github.com/Javierkaiser/opencode-indexing/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/Javierkaiser/opencode-indexing/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/Javierkaiser/opencode-indexing/releases/tag/v0.3.1
+[0.3.0]: https://github.com/Javierkaiser/opencode-indexing/releases/tag/v0.3.0
+[0.2.4]: https://github.com/Javierkaiser/opencode-indexing/releases/tag/v0.2.4
+[0.2.3]: https://github.com/Javierkaiser/opencode-indexing/releases/tag/v0.2.3
+[0.2.1]: https://github.com/Javierkaiser/opencode-indexing/releases/tag/v0.2.1
 [0.2.0]: https://github.com/Javierkaiser/opencode-indexing/releases/tag/v0.2.0
 [0.1.1]: https://github.com/Javierkaiser/opencode-indexing/releases/tag/v0.1.1
 [0.1.0]: https://github.com/Javierkaiser/opencode-indexing/releases/tag/v0.1.0

package/README.md

@@ -55,6 +55,36 @@ npx @javierkaiser/opencode-indexing --with-codegraph
 | `--no-restart` | Do not restart the service |
 | `--with-codegraph` | Install and register codegraph as a companion MCP (opt-in, `--package` only) |
 
+### The codegraph companion
+
+[CodeGraph](https://github.com/colbymchenry/codegraph) is a separate tool — a
+local code-graph indexer exposed as an MCP server — and this plugin drives it
+rather than reimplementing it. If it is not installed yet:
+
+```bash
+npm install -g @colbymchenry/codegraph
+```
+
+The package is scoped, and that matters: `codegraph` unscoped on npm is an
+unrelated 2024 library with no CLI, so installing that name exits 0 and leaves
+nothing on `PATH`.
+
+Installing it is only half of it. `indexing_build` and `indexing_import` also
+start the CLI for the workspace, so both indexes are built by the same action:
+`codegraph init --yes` the first time a folder is seen, `codegraph sync`
+afterwards. codegraph is a **companion, not a dependency** — with the CLI absent
+nothing is spawned, no build fails, and no line is added to the output. Turn it
+off with `/indexing-config set codegraph=false`, and see
+[Semantic search and code graphs](#semantic-search-and-code-graphs) for why the
+two belong together.
+
+The launch is detached and reported as started, never as finished: on a large
+monorepo `init` runs for minutes, and a tool call that blocked that long would
+be worse than one that returns. Anything that fails afterwards lands in
+`.codegraph/daemon.log`. A home directory or a drive root is refused rather than
+indexed, and launches are limited to one per 15 seconds per workspace because
+codegraph's own daemon already watches files.
+
 ### With the OpenCode CLI
 
 ```bash
@@ -82,7 +112,7 @@ The other six tools only read. OpenCode's base policy already allows everything
 write them out only if you want to tighten the set.
 
 `install.sh` and `install.ps1` are thin wrappers over it; PowerShell also accepts
-`-Local`, `-Package`, `-Spec`, `-SkipDeps` and `-NoRestart`.
+`-Local`, `-Package`, `-Spec`, `-SkipDeps`, `-NoRestart` and `-WithCodegraph`.
 
 `--package` deletes any copied plugin it finds: both sources define the same
 plugin id and the config directory is scanned automatically, so leaving both
@@ -108,12 +138,17 @@ resolve from the config file containing the entry:
 ```
 OpenCode ──► indexing_search ──┬──► Kilo's index (read-only)      Qdrant ws-*  ·  Kilo LanceDB
                                └──► own index (read/write)        own LanceDB (default)  ·  Qdrant oc-*
+
+OpenCode ──► codegraph_*  ───────► codegraph's graph (its own)    .codegraph/codegraph.db
+             ▲
+             └── indexing_build / indexing_import keep it in step
 ```
 
 - **Read-only reuse**: the plugin computes the same collection name Kilo uses (`ws-` + sha256 of the workspace path, first 16 hex chars), validates the embedding profile stored in the metadata point, and queries with an embedding from the *same* model (e.g. Mistral `codestral-embed-2505`, 1536d).
 - **Import without re-embedding**: `indexing_build` (or `indexing_import`) can copy vectors + chunks from an existing Kilo index — both its Qdrant collections and its local LanceDB database — at **zero embedding cost**, then incrementally index only the delta.
 - **Own index**: manifest-based incremental indexer (per-file sha256) writing to `oc-*` collections or an embedded LanceDB database, using the same chunk payload shape as Kilo (`filePath`, `fileHash`, `codeChunk`, `startLine`, `endLine`, `segmentHash`, `pathSegments`).
 - **Merge**: results from Kilo + own are merged; own (fresher) hits win on overlap; ghost hits (deleted files) are filtered out.
+- **Companion graph**: the same build starts codegraph for the workspace, which keeps its own index in `.codegraph/` and serves it over its own MCP server. This plugin never reads or writes that database — see [Semantic search and code graphs](#semantic-search-and-code-graphs).
 
 ## Tools (namespace `indexing`)
 
@@ -401,12 +436,13 @@ Word about data safety: Kilo's indexes (`ws-*` collections and its LanceDB direc
 ### Where each index lives
 
 The own index and Kilo's index are independent, and each one is chosen on its
-own:
+own. codegraph keeps a third, and it is the one this plugin never writes to:
 
 | Index | Default | Configured by |
 | --- | --- | --- |
 | Own index | embedded LanceDB, under `~/.local/state/opencode-indexing/lancedb` | `vectorStore` |
 | Kilo index (read-only) | whatever `kilo.jsonc` says | Kilo itself |
+| codegraph's graph | `.codegraph/` inside the workspace | codegraph itself |
 
 Kilo's `vectorStore` used to decide where this plugin's own index was written,
 because both were read from the same setting chain. That is no longer the case:
@@ -440,20 +476,31 @@ that. Set vectorStore=qdrant explicitly in
 Set `vectorStore=qdrant` in `~/.config/opencode/indexing.json` (or run
 `/indexing-config set vectorstore=qdrant`) to use a Qdrant server instead.
 
-## Semantic search vs. code graphs (roadmap)
+## Semantic search and code graphs
+
+Two indexes, not two options. This plugin builds and searches the semantic one;
+it also keeps codegraph's code graph in step for the same folder, so a single
+`indexing_build` leaves both current. Neither replaces the other, and this is not
+a fork of codegraph — see [The codegraph companion](#the-codegraph-companion)
+for the install side.
 
-`opencode-indexing` implements **semantic (vector) search**. It is worth being
-explicit about how it compares to **code-graph** tooling (call graphs, symbol
-graphs, SCIP-style indexes), because they answer different questions and are
-complementary:
+### The two indexes
 
-| | Semantic index (this plugin) | Code graph |
+| | Semantic index (this plugin) | Code graph (codegraph) |
 | --- | --- | --- |
 | Question it answers | "Where is the code that does something like X?" | "Who calls X? What breaks if I change it? Path from A to B?" |
 | Signal | Meaning (embeddings over chunks) | Structure (symbols, `CALLS`, `DEFINES`, `IMPORTS` edges) |
 | Strengths | Natural language, concepts without known identifiers, cross-language | Exact structural facts, multi-hop traversals, no similarity false positives |
 | Weaknesses | "Similar" is not "relevant"; no notion of connections | Cannot find a concept with no known symbol; fragile on dynamic code |
-| Cost profile | Embedding API + vector DB | Local parsing + small graph store |
+| What it costs to stay fresh | **Paid**: the embedding API, re-run when the model changes | **Free**: local parsing and a small graph store, re-run on every edit |
+
+That last row is what shapes the setup. A semantic index is re-embedded only when
+the model changes, and that is money; a graph is synced whenever a file is
+touched, and that is CPU. Two cadences for two economies — which is the reason
+to keep both pointed at one folder rather than at two projects that quietly
+drift apart.
+
+### Measuring the difference
 
 We measured this rather than assuming it. [`bench/`](./bench) runs the same
 real questions about code through four methods — word matching, symbol-name
@@ -472,37 +519,43 @@ What it found:
   better on both: more files found on one codebase, a better position on the
   other.
 
-One caveat that matters for reading that: the benchmark measures `codegraph
-query`, the one subcommand that matches names. It does **not** measure what a
-graph is actually good for — who calls what, what breaks if you change it,
-paths between two places. Those are the graph's real strength and they are not
-in the numbers above.
-
-The broader consensus points the same way: use embeddings to find the entry node
-by intent, then walk the graph for exact relationships. Cursor reported ~12.5%
-retrieval-accuracy improvement combining semantic search with grep; Sourcegraph
-layers semantic search over a SCIP graph; Aider uses tree-sitter + PageRank with
-no embeddings at all for repo maps.
-
-This plugin deliberately stays on the semantic side and coexists with grep/read
-(see the tool descriptions and the bundled skill). A code-graph mode (tree-sitter
-symbol/edge extraction into SQLite, exposed as `indexing_graph_*` tools that
-chain after `indexing_search`) is a candidate for a future major version; the
-tree-sitter infrastructure is already in place. Independently, the installer can itself install and register codegraph as a companion MCP (`--with-codegraph`, opt-in, published-package mode only).
-
-**Indexing both at once.** `indexing_build` and `indexing_import` also start
-codegraph for the workspace, so the two indexes are built by the same action:
-`codegraph init --yes` the first time a folder is seen, `codegraph sync`
-afterwards. codegraph is a **companion, not a dependency** — with the CLI absent
-nothing is spawned, no build fails and no line is added to the output. Turn it
-off with `/indexing-config set codegraph=false`.
+One caveat, and it is larger than it looks. The benchmark measures
+`codegraph query`, the one subcommand that matches **names**. It does **not**
+measure what a graph is actually good for — who calls what, what breaks if you
+change it, paths between two places. So the fusion above is *semantic + name
+matching*, **not** *semantic + graph traversal*. What would actually justify
+reaching for the graph is not in those numbers, and this section does not claim
+it is.
 
-The launch is detached and reported as started, never as finished: on a large
-monorepo `init` runs for minutes, and a tool call that blocked that long would
-be worse than one that returns. Anything that fails afterwards lands in
-`.codegraph/daemon.log`. A home directory or a drive root is refused rather than
-indexed, and launches are limited to one per 15 seconds per workspace because
-codegraph's own daemon already watches files.
+### Using them together
+
+The division of labour is the one the wider field converges on: use embeddings
+to find the entry node **by intent**, then walk the graph for **exact
+relationships**.
+
+1. `indexing_search` — "where is the retry logic for failed webhooks". Finds the
+   neighbourhood from meaning alone, with no identifier to know in advance.
+2. `codegraph_explore` — the same area, returning the verbatim source of the
+   relevant symbols, the call paths between them, and what depends on them.
+3. `codegraph_impact` / `codegraph_callers` — once the question becomes "what
+   breaks if I change this", the graph answers exactly, and a similarity search
+   cannot.
+
+Both are live in the same session, so an assistant moves between them without
+being asked to.
+
+### Why there are no graph tools in this plugin
+
+There are no `indexing_graph_*` tools here, and that is a decision rather than a
+gap. An earlier version of this section proposed adding tree-sitter symbol and
+edge extraction into SQLite as a candidate for a future major version. Once
+codegraph was available as a companion, that plan would have reimplemented
+something another tool already does better — in a second store, behind a second
+indexer that has to be kept alive and fresh.
+
+The plugin stays on the semantic side and coexists with grep/read (see the tool
+descriptions and the bundled skill). What it adds for the structural half is to
+keep it current, not to duplicate it.
 
 ## Development
 
@@ -520,7 +573,9 @@ node test/cli.ts build      --vector-store lancedb --root .
 
 ## Acknowledgements
 
-This plugin interoperates with the open-source [Kilo Code](https://github.com/Kilo-Org/kilocode) indexing format (MIT License, Copyright (c) 2026 Kilo Code). The line-based chunker and the tree-sitter queries are ports of Kilo Code's implementation. It also builds on [opencode](https://github.com/anomalyco/opencode) (MIT), [LanceDB](https://github.com/lancedb/lancedb) (Apache-2.0), [web-tree-sitter](https://github.com/tree-sitter/tree-sitter) (MIT), [tree-sitter-wasms](https://github.com/Gregoor/tree-sitter-wasms) (Unlicense) and [ignore](https://github.com/kaelzhang/node-ignore) (MIT).
+This plugin interoperates with the open-source [Kilo Code](https://github.com/Kilo-Org/kilocode) indexing format (MIT License, Copyright (c) 2026 Kilo Code). The line-based chunker and the tree-sitter queries are ports of Kilo Code's implementation. It also builds on [opencode](https://github.com/anomalyco/opencode) (MIT), [LanceDB](https://github.com/lancedb/lancedb) (Apache-2.0), [Apache Arrow](https://github.com/apache/arrow) (Apache-2.0), [web-tree-sitter](https://github.com/tree-sitter/tree-sitter) (MIT), [tree-sitter-wasms](https://github.com/Gregoor/tree-sitter-wasms) (Unlicense), [ignore](https://github.com/kaelzhang/node-ignore) (MIT), and — for the terminal UI — [SolidJS](https://github.com/solidjs/solid) (MIT) and [OpenTUI](https://github.com/sst/opentui) (MIT).
+
+The companion code graph is [CodeGraph](https://github.com/colbymchenry/codegraph) (MIT), a separate project this one installs and drives rather than bundles. Its npm package is `@colbymchenry/codegraph`; the unscoped `codegraph` on npm is a different, unrelated project.
 
 Kilo Code is a trademark of its owners; this project is **unofficial and not affiliated** with Kilo Code or the OpenCode project.
 

package/THIRD_PARTY_NOTICES.md

@@ -56,10 +56,35 @@ SOFTWARE.
 | Package | License | Copyright |
 | --- | --- | --- |
 | [`@lancedb/lancedb`](https://github.com/lancedb/lancedb) | Apache-2.0 | LanceDB, Inc. |
+| [`apache-arrow`](https://github.com/apache/arrow) | Apache-2.0 | The Apache Software Foundation |
 | [`web-tree-sitter`](https://github.com/tree-sitter/tree-sitter) | MIT | Tree-sitter contributors |
 | [`tree-sitter-wasms`](https://github.com/Gregoor/tree-sitter-wasms) | Unlicense | Gregor (packaging); grammars by their respective authors |
 | [`ignore`](https://github.com/kaelzhang/node-ignore) | MIT | Kael Zhang and contributors |
+| [`solid-js`](https://github.com/solidjs/solid) | MIT | Ryan Carniato and contributors |
+| [`@opentui/core`](https://github.com/sst/opentui) | MIT | SST and OpenTUI contributors |
+| [`@opentui/solid`](https://github.com/sst/opentui) | MIT | SST and OpenTUI contributors |
+
+`solid-js`, `@opentui/core` and `@opentui/solid` are what the terminal UI is
+rendered with. They are optional dependencies: without them the prompt-footer
+indicator and the settings page are absent, and everything else works.
 
 Tree-sitter grammar `.wasm` files bundled by `tree-sitter-wasms` are distributed
 under their upstream licenses (mostly MIT or Apache-2.0); see the
 `tree-sitter-wasms` package for details.
+
+## CodeGraph (github.com/colbymchenry/codegraph)
+
+Not bundled and not required. CodeGraph is a separate program that this plugin
+can install, register as an MCP server and keep in step; it is listed here
+because the plugin drives it and points at it by name.
+
+License: **MIT**, as declared in the package manifest
+(`@colbymchenry/codegraph@1.6.2`).
+
+The published package carries no `LICENSE` file of its own and declares no
+author, so the authoritative license text is the one in the upstream repository:
+<https://github.com/colbymchenry/codegraph>. It is not reproduced here rather
+than reproduced with a copyright holder this project cannot verify.
+
+The npm package is `@colbymchenry/codegraph`. The unscoped `codegraph` on npm is
+an unrelated project and is not what this plugin installs.

package/index.ts

@@ -79,6 +79,24 @@ plugin's own incremental index (Qdrant or LanceDB backend).
 - Verifying whether code exists that must be fresh: the index may lag behind
   recent edits; check \`indexing_status\` (freshness) or use Grep for certainty.
 
+## If codegraph is also installed
+
+When the codegraph MCP server is present, its tools are available alongside this
+one, and together they answer more than either can alone:
+
+- \`codegraph_explore\` — the area around a finding, with the verbatim source of
+  the relevant symbols, the call paths between them, and what depends on them.
+- \`codegraph_callers\` / \`codegraph_impact\` — "who calls this" and "what breaks
+  if I change it". Exact, structural answers that a similarity search cannot
+  give.
+- \`indexing_search\` still goes first when the intent is known and the
+  identifier is not: it finds the entry node by meaning, and the graph then
+  explains it.
+
+The two indexes are kept current together, so neither is stale relative to the
+other. If those tools are not available, everything above still applies and
+Grep remains the right fallback.
+
 ## Configuration
 
 \`indexing_config\` reports the effective settings (backend, model, credentials —

package/install.mjs

@@ -330,6 +330,15 @@ function hasCodegraphBin() {
   }
 }
 
+/**
+ * The npm package that provides the `codegraph` CLI.
+ *
+ * Scoped, and it has to be. The unscoped `codegraph` on npm is an unrelated
+ * 2024 library with no binary, so installing that name succeeds and leaves
+ * nothing on PATH — a silent no-op that looks like a working install.
+ */
+const CODEGRAPH_PACKAGE = "@colbymchenry/codegraph"
+
 /**
  * Install codegraph and register its MCP with OpenCode.
  *
@@ -342,16 +351,17 @@ function installCodegraph() {
   log("  installing codegraph as a companion MCP server...")
 
   if (!hasCodegraphBin()) {
-    log("  codegraph CLI missing; running npm install -g codegraph...")
+    log(`  codegraph CLI missing; running npm install -g ${CODEGRAPH_PACKAGE}...`)
     const npm = isWindows ? "npm.cmd" : "npm"
-    // --omit=... is not needed here: codegraph stands on its own, and a global
-    // install is what its own documentation assumes.
-    const installed = spawnSync(npm, ["install", "-g", "codegraph"], {
+    // Scoped on purpose. `codegraph` on the unscoped registry is an unrelated
+    // 2024 library with no CLI at all, and installing it would look successful
+    // while leaving nothing on PATH to register.
+    const installed = spawnSync(npm, ["install", "-g", CODEGRAPH_PACKAGE], {
       stdio: "inherit",
       shell: isWindows,
     })
     if (installed.error || installed.status !== 0) {
-      warn("  could not install codegraph (npm install -g codegraph failed); skipping MCP registration")
+      warn(`  could not install codegraph (npm install -g ${CODEGRAPH_PACKAGE} failed); skipping MCP registration`)
       return
     }
   }

package/install.ps1

@@ -2,14 +2,19 @@
 # Thin wrapper: the cross-platform logic lives in install.mjs, so Windows, Linux
 # and macOS all run the same code instead of drifting copies.
 #
+# The preferred form from npm is:
+#   npx @javierkaiser/opencode-indexing --with-codegraph
+# This wrapper forwards to the same install.mjs, so it accepts the same flags.
+#
 # Usage:
-#   powershell -ExecutionPolicy Bypass -File install.ps1 [-Local|-Package] [-Spec <spec>] [-SkipDeps] [-NoRestart]
+#   powershell -ExecutionPolicy Bypass -File install.ps1 [-Local|-Package] [-Spec <spec>] [-SkipDeps] [-NoRestart] [-WithCodegraph]
 param(
   [switch]$Local,
   [switch]$Package,
   [string]$Spec,
   [switch]$SkipDeps,
-  [switch]$NoRestart
+  [switch]$NoRestart,
+  [switch]$WithCodegraph
 )
 
 $ErrorActionPreference = "Stop"
@@ -20,6 +25,7 @@ if ($Package) { $forward += "--package" }
 if ($Spec) { $forward += $Spec }
 if ($SkipDeps) { $forward += "--skip-deps" }
 if ($NoRestart) { $forward += "--no-restart" }
+if ($WithCodegraph) { $forward += "--with-codegraph" }
 
 if (Get-Command node -ErrorAction SilentlyContinue) {
   & node $script @forward

package/install.sh

@@ -2,8 +2,12 @@
 # Installs opencode-indexing into the global OpenCode config directory.
 # Thin wrapper: the cross-platform logic lives in install.mjs.
 #
+# The preferred form from npm is:
+#   npx @javierkaiser/opencode-indexing --with-codegraph
+# This wrapper forwards to the same install.mjs, so it accepts the same flags.
+#
 # Usage:
-#   sh install.sh [--local|--package] [spec] [--skip-deps] [--no-restart]
+#   sh install.sh [--local|--package] [spec] [--skip-deps] [--no-restart] [--with-codegraph]
 set -eu
 
 dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@javierkaiser/opencode-indexing",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "OpenCode plugin: semantic code search that reuses Kilo Code indexes (Qdrant/LanceDB) and maintains its own independent index",
   "license": "MIT",
   "author": "Carlos Javier Lust <javierkaiser@gmail.com>",

package/src/codegraph.ts

@@ -19,6 +19,16 @@ import { assessScope } from "./scope.ts"
 /** Directory codegraph writes its index into. Its presence is the "is it indexed" answer. */
 const CODEGRAPH_DIR = ".codegraph"
 
+/**
+ * The npm package that provides the `codegraph` CLI.
+ *
+ * Scoped, and it has to be: the unscoped `codegraph` on npm is an unrelated
+ * 2024 library with no binary. Installing that name exits 0 and leaves nothing
+ * on PATH, which is the worst shape of failure for an installer step — it looks
+ * like it worked.
+ */
+const CODEGRAPH_PACKAGE = "@colbymchenry/codegraph"
+
 /**
  * Minimum seconds between launches for one workspace.
  *
@@ -197,7 +207,7 @@ export async function indexWithCodegraph(options: CodegraphOptions): Promise<Cod
     available = false
   }
   if (!available) {
-    return { kind: "skipped", reason: "the codegraph CLI is not installed (npm i -g codegraph)" }
+    return { kind: "skipped", reason: `the codegraph CLI is not installed (npm i -g ${CODEGRAPH_PACKAGE})` }
   }
 
   const initialized = isCodegraphInitialized(root)

package/src/tools.ts

@@ -73,7 +73,8 @@ Use this tool early for open-ended exploration when you know the intent but not
 Notes:
 - The index combines Kilo Code's index (when present and profile-compatible) with the plugin's own index, which can be backed by Qdrant or LanceDB.
 - If the index reports stale/incomplete, results may be incomplete — indexed files might not include recent edits.
-- Pass \`path\` to limit results to a subdirectory, relative to the workspace root.`
+- Pass \`path\` to limit results to a subdirectory, relative to the workspace root.
+- This finds code by meaning. For structure — who calls a symbol, what depends on it, what breaks if it changes — use the codegraph tools when that MCP server is available; a similarity search cannot answer those.`
 
 const STATUS_DESCRIPTION = `Report the state of the project's semantic code index.
 
@@ -82,6 +83,7 @@ Shows:
 - Kilo Code index sources available for import (Qdrant collection and/or local LanceDB database), with embedding profile and compatibility.
 - The plugin's own index (points, completion, embedding profile, last run).
 - Freshness: number of workspace files that were never indexed, possibly changed, or deleted since the last run.
+- The codegraph companion's state for this folder, when that setting is on: whether it is indexed, and that the next build will sync it.
 - A recommended next action (import/build/refresh).`
 
 const REFRESH_DESCRIPTION = `Incrementally update the plugin's own code index for this workspace.