@javierkaiser/opencode-indexing 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,84 @@ 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.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
+- **The prompt-footer indicator stopped rendering after OpenCode 2.0.30.** The
+  footer view imports `createSignal` from `solid-js` as a value, and `solid-js`,
+  `@opentui/core` and `@opentui/solid` were declared as *optional
+  peerDependencies* — which means npm never installs them, on the assumption that
+  the host already provides them. 2.0.30 stopped providing them, the plugin's own
+  `import()` of the footer view failed, the `catch` swallowed it, and the slot
+  rendered nothing. Everything else kept working, because nothing else needs
+  JSX: the command palette comes from `tui.ts` itself, which is what made it look
+  like a cosmetic regression rather than a missing dependency.
+
+  The three packages are now `optionalDependencies`. That still tolerates a
+  failed install, but unlike an optional peer it actually puts them on disk, so
+  the indicator no longer depends on what the host happens to supply.
+
+- **A package listed in both `optionalDependencies` and `devDependencies` is not
+  installed at all.** npm 12 lets the dev list win, so `--omit=dev` skips the
+  package and the optionalDependency never reaches disk — and `package.json`
+  still reads as though it is declared. This is why moving the three packages
+  was not by itself enough; they had to leave `devDependencies` as well.
+
+- `tsconfig.json` is published. `jsx: react-jsx` with
+  `jsxImportSource: "@opentui/solid"` is what makes a `.tsx` file load at all, and
+  it was not in `files`.
+
+### Added
+- `test/package-deps.test.ts` guards the manifest against all three of the
+  above, and asserts that every value import in the published sources resolves
+  to something the manifest installs — so the next third-party import fails a
+  test instead of becoming another silent missing module at load time.
+
 ## [0.2.3] - 2026-10-16
 
 ### Added

package/README.md

@@ -155,6 +155,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 |
@@ -383,6 +384,12 @@ Word about data safety: Kilo's indexes (`ws-*` collections and its LanceDB direc
 ## Requirements
 
 - OpenCode v2 (plugin API `@opencode/plugin@2.x`).
+- **For the prompt-footer indicator:** `solid-js`, `@opentui/core` and
+  `@opentui/solid`, which the plugin installs itself (~14 MB). They used to be
+  declared as optional *peer* dependencies, on the assumption that the host
+  already had them; OpenCode 2.0.30 stopped providing them and the indicator
+  silently stopped rendering. Everything else works without them — the settings
+  page degrades to dialogs and the footer is simply absent.
 - **For the own index: nothing to run.** The default store is embedded LanceDB
   (`@lancedb/lancedb@0.26.2`), so there is no server to start, no port to free and
   no container to keep alive.
@@ -483,6 +490,20 @@ 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`.
+
+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.
+
 ## Development
 
 ```powershell

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@javierkaiser/opencode-indexing",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "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>",
@@ -37,6 +37,7 @@
     "tui.ts",
     "tui",
     "src",
+    "tsconfig.json",
     "install.mjs",
     "install.sh",
     "install.ps1",
@@ -65,23 +66,20 @@
     "@lancedb/lancedb": "0.26.2",
     "tree-sitter-wasms": "0.1.13",
     "web-tree-sitter": "0.25.10",
-    "apache-arrow": "18.1.0"
+    "apache-arrow": "18.1.0",
+    "solid-js": "^1.9.12",
+    "@opentui/core": "0.5.14",
+    "@opentui/solid": "0.5.14"
   },
   "devDependencies": {
     "@opencode/plugin": "2.0.23",
     "@opencode/theme": "^2.0.23",
-    "@opentui/core": "^0.5.14",
-    "@opentui/solid": "^0.5.14",
     "@types/node": "^24.0.0",
-    "solid-js": "^1.9.12",
     "typescript": "^5.8.2"
   },
   "peerDependencies": {
     "@opencode/plugin": ">=2.0.0",
-    "@opencode/theme": ">=2.0.23",
-    "@opentui/core": ">=0.5.14",
-    "@opentui/solid": ">=0.5.14",
-    "solid-js": ">=1.9.12"
+    "@opencode/theme": ">=2.0.23"
   },
   "peerDependenciesMeta": {
     "@opencode/plugin": {
@@ -89,15 +87,6 @@
     },
     "@opencode/theme": {
       "optional": true
-    },
-    "@opentui/core": {
-      "optional": true
-    },
-    "@opentui/solid": {
-      "optional": true
-    },
-    "solid-js": {
-      "optional": true
     }
   }
 }

package/src/codegraph.ts

@@ -0,0 +1,255 @@
+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"
+
+/**
+ * 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)" }
+  }
+
+  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"
 
@@ -95,6 +96,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 +109,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 +250,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 +313,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 +383,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[]

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["node"],
+    "jsx": "react-jsx",
+    "jsxImportSource": "@opentui/solid",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["index.ts", "tui.ts", "tui/**/*.ts", "tui/**/*.tsx", "src/**/*.ts", "test/**/*.ts"]
+}