@broskees/opencode-codebase-graph 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @broskees/opencode-codebase-graph
+
+OpenCode plugin that injects a live codebase structural map into every LLM system prompt.
+
+## How It Works
+
+1. On plugin load, spawns `codebase-graph --watch` as a child process to keep `.codebase.md` up to date
+2. On every LLM call, reads `.codebase.md` from disk and pushes it onto the system prompt
+3. The agent always has a current structural map of the codebase — modules, symbols, hierarchies, dependencies
+
+## Installation
+
+### 1. Install the CLI tool
+
+```bash
+pip install codebase-graph
+```
+
+### 2. Add the plugin to OpenCode
+
+In your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@broskees/opencode-codebase-graph"]
+}
+```
+
+That's it. The plugin auto-starts the watcher and injects the map on every LLM call.
+
+## Verifying It Works
+
+1. Start OpenCode in a project directory
+2. Check that `.codebase.md` appears in the project root (may take a moment on first run)
+3. The structural map is automatically included in every LLM call — no action needed
+
+## Troubleshooting
+
+### `.codebase.md` not appearing
+
+- Ensure `codebase-graph` is in your PATH: `which codebase-graph`
+- Try running it manually: `codebase-graph --watch --dir .`
+- Check that the project directory contains supported files (`.py`, `.ts`, `.tsx`, `.js`, `.jsx`)
+
+### Plugin not loading
+
+- Check OpenCode logs for plugin errors
+- Ensure `@opencode-ai/plugin` peer dependency is satisfied
+
+## How It Integrates
+
+```
+codebase-graph --watch     →  writes .codebase.md on disk
+                               ↓
+OpenCode plugin hook       →  reads .codebase.md on every LLM call
+                               ↓
+System prompt              →  agent sees live structural map
+```
+
+The plugin is ~25 lines of TypeScript. All the heavy lifting (parsing, watching, TOON serialization) happens in the `codebase-graph` binary.

package/index.ts

@@ -0,0 +1,25 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import { readFileSync } from "fs"
+import { join } from "path"
+import { spawn } from "child_process"
+
+export const CodebaseGraph: Plugin = async ({ directory }) => {
+  const briefingPath = join(directory, ".codebase.md")
+
+  // Spawn watcher daemon — dies when plugin/OpenCode exits
+  spawn("codebase-graph", ["--watch", "--dir", directory], {
+    stdio: "ignore",
+    detached: false,
+  })
+
+  return {
+    "experimental.chat.system.transform": async (_incoming, output) => {
+      try {
+        const briefing = readFileSync(briefingPath, "utf-8")
+        output.system.push(briefing)
+      } catch {
+        // File doesn't exist yet (first index in progress), skip
+      }
+    },
+  }
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@broskees/opencode-codebase-graph",
+  "version": "0.1.0",
+  "description": "OpenCode plugin that injects a live codebase structural map into the system prompt",
+  "main": "index.ts",
+  "types": "index.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/broskees/codebase-graph.git",
+    "directory": "plugins/opencode"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "codebase",
+    "ai",
+    "coding-agent",
+    "structural-map"
+  ],
+  "files": [
+    "index.ts",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  }
+}