@javierkaiser/opencode-indexing 0.2.4 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,106 @@ 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
+- **`indexing_build` and `indexing_import` now also start codegraph** for the
+  workspace, so the semantic index and the code graph are built by the same
+  action instead of one silently going stale. `init` the first time a folder is
+  seen, `sync` afterwards — the second is what covers the case where codegraph's
+  daemon has already shut down, which it does after five minutes without
+  clients.
+
+  **codegraph is a companion, not a dependency.** Nothing about this plugin
+  requires it: with the CLI absent, `available()` returns false, nothing is
+  spawned, no build fails, and no line is added to the output. That path is
+  covered by a test that hides codegraph from `PATH` and runs the real spawner,
+  not a fake — an injected runner would have proved the logic while leaving the
+  wiring unchecked.
+
+- `codegraph` setting, on by default (`/indexing-config set codegraph=false` to
+  turn it off). Read as `!== false`, because the key is in no config file anyone
+  has and a default that required it to be present would never apply.
+
+- One line in `indexing_status` saying whether codegraph is indexed for the
+  folder. Read from the filesystem, so it costs no process — status runs on
+  every search through the footer.
+
+### Changed
+- The build summary reports the codegraph command it started, and always in the
+  past tense of a *launch*, never of a success: the process is detached, so at
+  the moment the tool answers, codegraph has only begun. Anything that goes
+  wrong afterwards lands in `.codegraph/daemon.log`, which is where the message
+  points.
+
+### Notes for review
+- A dangerous workspace root — the home directory or a drive root — is refused
+  rather than indexed. codegraph has `-f` for exactly that case, and passing it
+  because a tool call said so would index the whole machine.
+- Launches are rate-limited per workspace to one per 15 seconds, because
+  codegraph runs its own daemon with a file watcher and two `sync` invocations
+  seconds apart contend for the same SQLite database.
+- `.codegraph/` was already excluded from the scanner (every dot-directory that
+  is not explicitly allowed is skipped), and there is now a test pinning it:
+  codegraph writes a multi-megabyte SQLite database plus a WAL there, and
+  letting the scanner walk it would embed another indexer's storage into this
+  one, for money, forever.
+
 ## [0.2.4] - 2026-10-16
 
 ### Fixed
@@ -237,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`)
 
@@ -155,6 +190,7 @@ Settable keys (case-insensitive):
 | `ollamaurl` | Ollama base URL |
 | `openaicompatibleurl` / `openaicompatiblekey` | OpenAI-compatible endpoint |
 | `importfromkilo` | `true` to import from Kilo when building, `false` to start from scratch |
+| `codegraph` | `false` to stop also running the `codegraph` CLI on build. On by default; a no-op when codegraph is not installed |
 | `autorefresh` | Refresh the own index automatically on search |
 | `enabled` | Master switch. `false` pauses writing and refreshing; search keeps reading Kilo's index |
 | `searchmaxresults` | Result cap per search |
@@ -400,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:
@@ -439,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
@@ -471,23 +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.
+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.
+
+### 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**.
 
-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.
+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.
 
-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).
+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
 
@@ -505,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.2.4",
+  "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

@@ -0,0 +1,265 @@
+import * as fs from "node:fs"
+import * as path from "node:path"
+
+import { assessScope } from "./scope.ts"
+
+/**
+ * Companion integration with CodeGraph, the code-graph indexer.
+ *
+ * Two indexes, two signals: this plugin answers "where is the code that does
+ * something like X", codegraph answers "who calls X, what breaks if I change
+ * it". They are complementary, and indexing only one leaves the other stale.
+ *
+ * The decision this module makes is narrow on purpose. It never searches, never
+ * parses, never reads codegraph's database: it either launches `codegraph init`
+ * or `codegraph sync` and reports what it launched. Everything it knows about
+ * codegraph comes from running its CLI.
+ */
+
+/** 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.
+ *
+ * codegraph is not the only writer of `.codegraph/`: it runs a daemon with a
+ * file watcher that auto-syncs on change. Two `sync` invocations seconds apart
+ * contend for the same database, so the second one is skipped rather than
+ * allowed to collide. Also the cheap defence against a user hammering build.
+ */
+const MIN_LAUNCH_INTERVAL_MS = 15_000
+
+export interface CodegraphLaunch {
+  /** `init` on a folder that was never indexed, `sync` otherwise. */
+  action: "init" | "sync"
+  /** Command as run, for the message the user sees. */
+  command: string
+  /** Why it ran, or why it did not. Always present. */
+  detail: string
+}
+
+export type CodegraphOutcome =
+  | { kind: "launched"; launch: CodegraphLaunch }
+  /** Nothing was started; `reason` is user-facing and complete on its own. */
+  | { kind: "skipped"; reason: string }
+  /** Could not start at all. Never fatal: the semantic index does not depend on this. */
+  | { kind: "failed"; reason: string }
+
+/**
+ * The seam that keeps the test suite away from real processes.
+ *
+ * `src/` had no `child_process` use before this, so there is no precedent to
+ * follow. Defaulting to the real spawner and injecting in tests keeps the module
+ * honest without making every test shell out.
+ */
+export interface CodegraphRunner {
+  /** Resolves true when the `codegraph` CLI answers. Never throws. */
+  available(): Promise<boolean>
+  /**
+   * Starts the command and returns immediately.
+   *
+   * Deliberately not awaited to completion: `init` on a large monorepo can run
+   * for minutes, and a tool call that blocks that long is worse than one that
+   * finishes. The caller therefore reports "started", never "succeeded".
+   */
+  launch(args: string[], cwd: string): Promise<void>
+}
+
+/** Monotonic-enough clock, injectable so tests do not have to wait 15 seconds. */
+export interface CodegraphClock {
+  now(): number
+}
+
+const realClock: CodegraphClock = { now: () => Date.now() }
+
+/** Last launch per workspace, so the interval gate survives across calls. */
+const lastLaunch = new Map<string, number>()
+
+/** Whether `.codegraph/` exists. Sync rather than async: it runs on every build. */
+export function isCodegraphInitialized(root: string): boolean {
+  try {
+    return fs.existsSync(path.join(root, CODEGRAPH_DIR))
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Spawn options shared by both commands.
+ *
+ * `shell` is true on Windows and false elsewhere, and it is not a stylistic
+ * choice: npm installs its executables as `codegraph.cmd` / `codegraph.ps1`
+ * shims, which `spawn` cannot resolve on its own — it reports ENOENT for a
+ * binary that is installed and working. Verified by running both shapes.
+ *
+ * The arguments are fixed literals chosen here, never user input, so there is
+ * no path for quoting to matter; `shell` is what buys Windows compatibility.
+ */
+function spawnOptions(cwd?: string): Record<string, unknown> {
+  return {
+    cwd,
+    stdio: "ignore",
+    windowsHide: true,
+    shell: process.platform === "win32",
+  }
+}
+
+/**
+ * The CLI runner.
+ *
+ * `version` is the cheapest command that proves both existence and runnability;
+ * `init --help` would do too but prints help. stdio is ignored rather than
+ * inherited so codegraph's output cannot corrupt the TUI, and `--yes` on init is
+ * what keeps it from blocking on a prompt nobody can answer.
+ */
+export const realRunner: CodegraphRunner = {
+  async available() {
+    const { spawn } = await import("node:child_process")
+    return new Promise<boolean>((resolve) => {
+      try {
+        const child = spawn("codegraph", ["version"], spawnOptions())
+        child.once("error", () => resolve(false))
+        child.once("close", (code) => resolve(code === 0))
+      } catch {
+        resolve(false)
+      }
+    })
+  },
+  async launch(args, cwd) {
+    const { spawn } = await import("node:child_process")
+    await new Promise<void>((resolve) => {
+      let child: ReturnType<typeof spawn>
+      try {
+        child = spawn("codegraph", args, {
+          ...spawnOptions(cwd),
+          // Detached so the index keeps building after the service restarts.
+          // Without this a restart mid-init orphans a half-written database.
+          // Not on Windows: a detached shell process is not unref-able the same
+          // way, and the host holds the handle anyway.
+          detached: process.platform !== "win32",
+        })
+        // Nothing is awaited on purpose: see the interface note. `unref` only
+        // exists on non-Windows, where detached was requested at all.
+        child.unref()
+      } catch {
+        resolve()
+        return
+      }
+      child.once("error", () => resolve())
+      child.once("spawn", () => resolve())
+    })
+  },
+}
+
+export interface CodegraphOptions {
+  root: string
+  enabled: boolean
+  runner?: CodegraphRunner
+  clock?: CodegraphClock
+}
+
+/**
+ * Launch codegraph for a workspace, if it makes sense to.
+ *
+ * Returns what happened; the caller decides how to say it. Never throws: a
+ * companion indexer must not be able to fail the semantic one.
+ */
+export async function indexWithCodegraph(options: CodegraphOptions): Promise<CodegraphOutcome> {
+  const { root, enabled } = options
+  if (!enabled) return { kind: "skipped", reason: "codegraph indexing is turned off (set codegraph=true)" }
+
+  const runner = options.runner ?? realRunner
+  const clock = options.clock ?? realClock
+
+  // A home directory or a drive root is reported rather than indexed. codegraph
+  // has `-f` for exactly this case; passing it here would index the user's whole
+  // machine because a tool call said so.
+  const scope = assessScope(root)
+  if (scope.level === "warn") {
+    return { kind: "skipped", reason: `${root} is ${scope.reason}; codegraph indexing was not started` }
+  }
+
+  const last = lastLaunch.get(root)
+  const now = clock.now()
+  if (last !== undefined && now - last < MIN_LAUNCH_INTERVAL_MS) {
+    return { kind: "skipped", reason: "codegraph was launched for this workspace moments ago" }
+  }
+
+  // "Not installed" arrives as either a false or a throw: spawn() reports a
+  // missing binary as ENOENT on the error event. Both mean the same ordinary
+  // thing, so both are a skip. A throw here is not a failure of this plugin —
+  // it is the absence of an optional companion, which is the case the whole
+  // design has to get right.
+  let available: boolean
+  try {
+    available = await runner.available()
+  } catch {
+    available = false
+  }
+  if (!available) {
+    return { kind: "skipped", reason: `the codegraph CLI is not installed (npm i -g ${CODEGRAPH_PACKAGE})` }
+  }
+
+  const initialized = isCodegraphInitialized(root)
+  const args = initialized ? ["sync"] : ["init", "--yes"]
+  const action = initialized ? "sync" : "init"
+
+  // Recorded before launching, so a failed launch still rate-limits: otherwise
+  // a broken CLI would be spawned again on every single build.
+  lastLaunch.set(root, now)
+
+  try {
+    await runner.launch(args, root)
+  } catch (error) {
+    return { kind: "failed", reason: `could not start \`codegraph ${args.join(" ")}\`: ${message(error)}` }
+  }
+
+  return {
+    kind: "launched",
+    launch: {
+      action,
+      command: `codegraph ${args.join(" ")}`,
+      detail: initialized
+        ? "syncing changes since the last index"
+        : "building the first index for this folder",
+    },
+  }
+}
+
+/** Test seam: forget the rate-limit state. */
+export function resetCodegraphLaunchState(): void {
+  lastLaunch.clear()
+}
+
+/**
+ * One line for `indexing_status`, or "" when there is nothing worth saying.
+ *
+ * Deliberately does not run the CLI: status is called on every search via the
+ * footer, and spawning a process to decorate a status line is not a trade worth
+ * making. The directory's existence is the whole answer.
+ */
+export function codegraphStatusLine(root: string): string {
+  try {
+    if (!fs.existsSync(root)) return ""
+    const initialized = isCodegraphInitialized(root)
+    return initialized
+      ? "codegraph: indexed (synced on the next indexing_build)"
+      : "codegraph: not indexed (initialised on the next indexing_build)"
+  } catch {
+    return ""
+  }
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/config.ts

@@ -38,6 +38,8 @@ export interface PluginOptionsInput {
   /** Master switch: when false the own index is neither written nor refreshed. */
   enabled?: boolean
   importFromKilo?: boolean
+  /** Also launch the codegraph CLI on build. Absent means on; see IndexingSettings. */
+  codegraph?: boolean
   /** Disable reading Kilo's config file entirely. */
   ignoreKiloConfig?: boolean
   homeDir?: string
@@ -283,6 +285,11 @@ export function resolveSettings(options: PluginOptionsInput): IndexingSettings {
   // but nothing is written and nothing is auto-refreshed. Toggled from the TUI
   // footer indicator or `/indexing-config set enabled false`.
   const enabled = options.enabled ?? file?.enabled !== false
+  // Companion indexer. On by default, and a no-op when codegraph is not
+  // installed, so enabling it costs nothing for someone who does not use it.
+  // `!== false` rather than `=== true`: the key is absent from most configs and
+  // absent has to mean "on" or the default would never apply.
+  const codegraph = options.codegraph ?? file?.codegraph !== false
 
   return {
     provider,
@@ -306,6 +313,7 @@ export function resolveSettings(options: PluginOptionsInput): IndexingSettings {
     autoRefresh,
     importFromKilo,
     enabled,
+    codegraph,
     credentials,
     warnings,
   }

package/src/scanner.ts

@@ -59,8 +59,14 @@ export const DEFAULT_IGNORE_GLOBS: readonly string[] = [
 
 const DEFAULT_MAX_FILE_SIZE_BYTES = 1024 * 1024
 
-/** Dot-directories that are still walked because they hold indexable config. */
-const ALLOWED_DOT_DIRS: ReadonlySet<string> = new Set([
+/**
+ * Dot-directories that are still walked because they hold indexable config.
+ *
+ * Exported for the test that pins `.codegraph` out of it: codegraph's SQLite
+ * database sits in that directory, and letting the scanner walk it would embed
+ * another indexer's storage into this one.
+ */
+export const ALLOWED_DOT_DIRS: ReadonlySet<string> = new Set([
   ".github",
   ".vscode",
   ".gitlab",

package/src/settings-commands.ts

@@ -265,6 +265,14 @@ const KEY_SPECS: Record<string, KeySpec> = {
     toPatch: (value) => ({ enabled: Boolean(value) }),
     display: (settings) => (settings.enabled === false ? "false" : "true"),
   },
+  codegraph: {
+    group: "behavior",
+    kind: "boolean",
+    description: "Also run the codegraph CLI on build (companion code graph; no-op when codegraph is not installed)",
+    toPatch: (value) => ({ codegraph: Boolean(value) }),
+    // `!== false`, matching how the value resolves: absent means on.
+    display: (settings) => (settings.codegraph === false ? "false" : "true"),
+  },
   searchmaxresults: {
     group: "search",
     kind: "integer",

package/src/settings.ts

@@ -39,6 +39,8 @@ export interface SettingsFile {
   autoRefresh?: boolean
   /** Master switch: when false the own index is neither written nor refreshed. */
   enabled?: boolean
+  /** Also launch the codegraph CLI on build. Absent means on; a no-op if not installed. */
+  codegraph?: boolean
   searchMinScore?: number | null
   searchMaxResults?: number
   embeddingBatchSize?: number

package/src/tools.ts

@@ -5,6 +5,7 @@ import { indexStatusLine } from "./index-state.ts"
 import { discoverKiloSources, importFromKilo, type KiloSourceInfo } from "./import.ts"
 import { createOwnStore, createSettingsQdrant } from "./store-factory.ts"
 import { assessScope } from "./scope.ts"
+import { codegraphStatusLine, indexWithCodegraph, type CodegraphOutcome } from "./codegraph.ts"
 import type { IndexingSettings, KVStore } from "./types.ts"
 import type { Qdrant } from "./qdrant.ts"
 
@@ -72,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.
 
@@ -81,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.
@@ -95,6 +98,11 @@ Behavior:
 - \`rebuild: true\` drops the own index first and re-imports/re-indexes everything.
 - \`skipImport: true\` forces indexing from scratch even when a Kilo index exists.
 
+If the codegraph CLI is installed, it is also started for this folder in the
+background (\`init\` the first time, \`sync\` afterwards) so the companion code
+graph stays in step. It never blocks this tool and never fails it: without
+codegraph this build is identical.
+
 This can take a while for large workspaces and may consume embedding API credits (except when importing).`
 
 const IMPORT_DESCRIPTION = `Import an existing Kilo Code index into the plugin's own index WITHOUT re-embedding.
@@ -103,7 +111,9 @@ Vectors and chunks are copied as-is (zero embedding API cost), which requires a
 - Kilo's Qdrant collection (\`ws-*\`).
 - Kilo's local LanceDB database for this workspace, when present.
 
-Use indexing_status to list detected sources. If profiles do not match, rebuild with the matching model instead.`
+Use indexing_status to list detected sources. If profiles do not match, rebuild with the matching model instead.
+
+If the codegraph CLI is installed, it is also started for this folder in the background, so the companion code graph covers the files this import brought in. Without codegraph this import is identical.`
 
 const jsonSchema = (properties: Record<string, unknown>, required: string[] = []): Record<string, unknown> => ({
   type: "object",
@@ -242,6 +252,13 @@ export function createTools(deps: ToolDeps): ToolDefinition[] {
             `Freshness: ${status.freshness.total} files scanned, ${status.freshness.added} new, ${status.freshness.maybeStale} possibly changed, ${status.freshness.deleted} deleted.`,
           )
         }
+        // Only when the companion indexer is actually in play: saying
+        // "codegraph: not indexed" to someone who never asked for codegraph is
+        // noise. Read from the filesystem, so this costs no process.
+        if (settings.codegraph !== false) {
+          const codegraph = codegraphStatusLine(root)
+          if (codegraph) lines.push(codegraph)
+        }
         lines.push(`Recommendation: ${status.recommendation}`)
         if (status.warnings.length > 0) lines.push(`Warnings: ${status.warnings.join("; ")}`)
         return { output: lines.join("\n"), metadata: status as unknown as Record<string, unknown> }
@@ -298,9 +315,9 @@ export function createTools(deps: ToolDeps): ToolDefinition[] {
           { mode: "build", rebuild: input.rebuild === true, skipImport: input.skipImport === true },
         )
         const summary = formatReport("build", report)
-        const warning = scopeWarning(root)
+        const lines = [scopeWarning(root), summary, await codegraphLine(root, settings)].filter(Boolean)
         return {
-          output: warning ? `${warning}\n${summary}` : summary,
+          output: lines.join("\n"),
           metadata: report as unknown as Record<string, unknown>,
         }
       },
@@ -368,14 +385,38 @@ export function createTools(deps: ToolDeps): ToolDefinition[] {
         const lines = [
           `Imported ${report.imported} chunks from ${report.source.kind} ${report.source.name} in ${(report.durationMs / 1000).toFixed(1)}s.`,
           `Batches: ${report.batches}, skipped: ${report.skipped}. Embedding API calls: 0.`,
+          await codegraphLine(root, settings),
         ]
         if (report.errors.length > 0) lines.push(`Errors: ${report.errors.join("; ")}`)
-        return { output: lines.join("\n"), metadata: report as unknown as Record<string, unknown> }
+        return { output: lines.filter(Boolean).join("\n"), metadata: report as unknown as Record<string, unknown> }
       },
     },
   ]
 }
 
+/**
+ * One line about the companion indexer, for the write tools.
+ *
+ * Never throws and never reports success: the launch is detached, so by the time
+ * this returns the CLI has only started. Anything that went wrong afterwards
+ * lands in `.codegraph/daemon.log`, which is where the message points.
+ */
+async function codegraphLine(root: string, settings: IndexingSettings): Promise<string> {
+  let outcome: CodegraphOutcome
+  try {
+    outcome = await indexWithCodegraph({ root, enabled: settings.codegraph !== false })
+  } catch (error) {
+    return `Codegraph: not indexed (${error instanceof Error ? error.message : String(error)})`
+  }
+  if (outcome.kind === "launched") {
+    return `Codegraph: \`${outcome.launch.command}\` started in the background — ${outcome.launch.detail}.`
+  }
+  // A skip while the CLI is absent is the common case and not worth a line on
+  // every build; the other two say something the user may want to act on.
+  if (outcome.reason.startsWith("the codegraph CLI is not installed")) return ""
+  return `Codegraph: not indexed (${outcome.reason})`
+}
+
 function makeProgress(context: { progress?: (m: unknown) => Promise<void> }): (update: {
   phase: string
   processed: number

package/src/types.ts

@@ -96,6 +96,16 @@ export interface IndexingSettings extends EmbeddingProfile {
   importFromKilo: boolean
   /** Master switch: when false nothing is written to nor refreshed in the own index. */
   enabled: boolean
+  /**
+   * Also launch the codegraph CLI when the workspace is indexed.
+   *
+   * Optional so that every fixture, every caller and every consumer that builds
+   * settings by hand keeps compiling: a companion that must be threaded through
+   * eight test doubles to exist is a dependency, not a companion. Callers read
+   * it as `settings.codegraph !== false`, which treats absent as "try it" —
+   * and "try it" is a no-op when the CLI is not installed.
+   */
+  codegraph?: boolean
   credentials: ProviderCredentials
   /** Warnings produced while resolving configuration. */
   warnings: string[]