v1.9.7: first-class opencode plugin + setup auto-wiring

Author: keshrath

CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.9.7 (2026-04-21) — first-class OpenCode plugin + setup auto-wiring
+
+OpenCode parity for the lifecycle hooks that were previously Claude-Code-only.
+
+### Added
+
+- **`scripts/plugins/opencode/agent-knowledge.ts`** — in-repo opencode plugin, exposed via the new `"./opencode"` subpath export in `package.json`. Users register it with a single line in `opencode.json`: `"plugin": ["agent-knowledge/opencode"]`. Covers four of the six Claude Code lifecycle hooks:
+  - `event: session.created` → session-start announce (dashboard URL toast + clears stale first-prompt marker on resume)
+  - `chat.message` → first-prompt-inject (searches KB via dashboard `/api/knowledge/search`, prepends rendered hits block to user parts, sets marker, emits a `"injected N hits"` toast)
+  - `experimental.session.compacting` → precompact-flush (pushes the "save unsaved knowledge before compaction" nudge into `output.context`)
+  - `event: session.deleted` → sessionend-distill (walks `client.session.messages`, writes `~/agent-knowledge/projects/session-opencode-<slug>.md` with turn counts, tool uses, and first 20 user prompts)
+
+  Honours the same env vars as the Claude hooks (`AGENT_KNOWLEDGE_MEMORY_DIR`, `AGENT_KNOWLEDGE_DATA_DIR`, `AGENT_KNOWLEDGE_PORT`, `AGENT_KNOWLEDGE_FIRSTPROMPT_*`). Fails open on every handler — search timeout, toast failure (CLI mode), SDK error on session walk, disk write failure — so the user is never blocked.
+
+- **`scripts/setup.js --host=opencode|all`** — new flag alongside the existing `--agent` (kept for back-compat). Auto-detects `~/.config/opencode/opencode.json` (Linux/macOS) or `%APPDATA%\opencode\opencode.json` (Windows); `--workspace=<path>` configures a project-local config. Idempotently ensures `mcp.agent-knowledge` + `plugin` array contain the plugin id.
+
+- **`tests/plugins/opencode.test.ts`** — direct-import vitest suite covering plugin shape, first-prompt gating (short / slash / bang prompts skipped, marker set even on zero-hit, second turn does not re-inject), `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT=0` kill-switch, compacting context push, session.deleted distill disk output, and fail-open on toast + session-walk errors.
+
+### Not ported (no opencode analog)
+
+- `session-start-ingest.mjs` — paired with the `/knowledge-ingest` skill flow, which is Claude-Code-specific.
+- `precompact-distill.mjs` — opencode compaction does not expose the transcript to plugins.
+- L0 identity auto-load — opencode has no `additionalContext` equivalent; identity lives in `AGENTS.md` or on-demand `knowledge(action="wakeup")` calls.
+
+### Tests
+
+571 → 583 passing (12 new assertions across plugin shape, first-prompt gating, compacting context, and session.deleted distill). No changes to the Claude hook suite.
+
 ## 1.9.6 (2026-04-21) — visible SessionEnd receipts + live dashboard toasts
 
 Three-layer visibility for the SessionEnd distill hook, so "did it actually run?" never has to be guessed again.

agent-desk-plugin.json

@@ -2,7 +2,7 @@
   "id": "agent-knowledge",
   "name": "Knowledge",
   "icon": "psychology",
-  "version": "1.9.6",
+  "version": "1.9.7",
   "description": "Knowledge base — entries, sessions, search, graph relationships",
   "ui": "./dist/ui/app.js",
   "css": "./dist/ui/styles.css",

docs/SETUP.md

@@ -258,24 +258,62 @@ See [`docs/HOOKS.md`](HOOKS.md) for the full hook reference including environmen
 
 ### OpenCode Plugins
 
-OpenCode supports lifecycle hooks via JavaScript/TypeScript plugins. Create a plugin in `.opencode/plugins/` or `~/.config/opencode/plugins/`:
+agent-knowledge ships a first-class opencode plugin at `scripts/plugins/opencode/agent-knowledge.ts`, exposed via the `"./opencode"` subpath export. Register it by adding one line to your `opencode.json`:
 
-```typescript
-// .opencode/plugins/agent-knowledge.ts
-import type { Plugin } from '@opencode-ai/plugin';
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "agent-knowledge": {
+      "type": "local",
+      "command": ["node", "/absolute/path/to/agent-knowledge/dist/index.js"],
+      "enabled": true,
+      "timeout": 60000
+    }
+  },
+  "plugin": ["agent-knowledge/opencode"]
+}
+```
 
-export const AgentKnowledgePlugin: Plugin = async ({ client }) => {
-  return {
-    event: async (event) => {
-      if (event.type === 'session.created') {
-        // Knowledge base instructions provided via AGENTS.md
-      }
-    },
-  };
-};
+Or let `scripts/setup.js` wire it automatically:
+
+```bash
+node scripts/setup.js --host=opencode                      # global ~/.config/opencode/opencode.json
+node scripts/setup.js --host=opencode --workspace=/proj    # workspace-local opencode.json
+node scripts/setup.js --host=all                           # both Claude Code and OpenCode
 ```
 
-Available events: `session.created`, `session.idle`, `tool.execute.before`, `tool.execute.after`, `message.updated`, `file.edited`.
+#### What the plugin does
+
+Mirrors the Claude Code hooks where opencode has an equivalent event:
+
+| Claude Code hook          | OpenCode analog                   | Behavior                                                              |
+| ------------------------- | --------------------------------- | --------------------------------------------------------------------- |
+| `session-start.js`        | `event: session.created`          | Dashboard URL toast + clears stale first-prompt marker on resume.     |
+| `first-prompt-inject.mjs` | `chat.message`                    | Searches the KB and prepends a rendered hits block to the user parts. |
+| `precompact-flush.mjs`    | `experimental.session.compacting` | Pushes a "save unsaved knowledge before compaction" nudge.            |
+| `sessionend-distill.mjs`  | `event: session.deleted`          | Writes `~/agent-knowledge/projects/session-opencode-<slug>.md`.       |
+
+Not ported (opencode has no equivalent surface):
+
+- `session-start-ingest.mjs` (paired with the `/knowledge-ingest` skill flow).
+- `precompact-distill.mjs` (opencode compaction does not expose the transcript to plugins).
+- L0 identity auto-load (no `additionalContext` equivalent — put identity in `AGENTS.md` or call `knowledge(action="wakeup")` manually).
+
+#### Environment variables
+
+Same as the Claude hooks, all optional:
+
+| Variable                               | Default             | Description                                              |
+| -------------------------------------- | ------------------- | -------------------------------------------------------- |
+| `AGENT_KNOWLEDGE_MEMORY_DIR`           | `~/agent-knowledge` | Knowledge base root.                                     |
+| `AGENT_KNOWLEDGE_DATA_DIR`             | `<memory>/.data`    | Marker/cache dir (first-prompt-seen markers live here).  |
+| `AGENT_KNOWLEDGE_PORT`                 | `3423`              | Dashboard port (plugin queries `/api/knowledge/search`). |
+| `AGENT_KNOWLEDGE_FIRSTPROMPT_INJECT`   | `1`                 | Set `0` / `false` / `off` to disable inject entirely.    |
+| `AGENT_KNOWLEDGE_FIRSTPROMPT_BUDGET`   | `600`               | Max inject tokens (chars/4), clamped `[100, 8000]`.      |
+| `AGENT_KNOWLEDGE_FIRSTPROMPT_MAX_HITS` | `4`                 | Max rendered hits, clamped `[1, 20]`.                    |
+
+Every hook fails open — errors during search, toast, session walk, or disk write are swallowed and the user is never blocked.
 
 Combine with `AGENTS.md` instructions (see below).
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-knowledge",
-  "version": "1.9.6",
+  "version": "1.9.7",
   "description": "Cross-session memory and recall for AI agents — git-synced knowledge base, knowledge graph, confidence scoring, hybrid semantic+TF-IDF search, auto-distillation with secrets scrubbing",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
     "./dist/lib.js": {
       "types": "./dist/lib.d.ts",
       "default": "./dist/lib.js"
-    }
+    },
+    "./opencode": "./scripts/plugins/opencode/agent-knowledge.ts"
   },
   "bin": {
     "agent-knowledge": "dist/index.js"
@@ -67,7 +68,8 @@
     "model-context-protocol",
     "ai-agents",
     "coding-assistants",
-    "claude-code"
+    "claude-code",
+    "opencode"
   ],
   "author": "keshrath",
   "mcpName": "io.github.keshrath/agent-knowledge",