opencode-btw 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kldzj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,52 @@
+# opencode-btw
+
+Hint injection plugin for [OpenCode](https://opencode.ai) — nudge the model mid-task without interrupting its flow.
+
+When the model is stuck in a loop or heading in the wrong direction, `/btw` lets you inject a hint into its context without sending a new message. The hint persists in the system prompt until you clear it and is picked up on the next LLM call, including during tool loops.
+
+## Install
+
+Add to your `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-btw@latest"]
+}
+```
+
+Restart OpenCode after adding the plugin.
+
+## Usage
+
+```
+/btw use the Edit tool instead of sed
+/btw focus on error handling, you keep missing edge cases
+/btw clear
+/btw                              # show current hint
+```
+
+A confirmation message appears in the chat after each command. The model does not see this confirmation — only the hint itself (via the system prompt).
+
+## How it works
+
+1. `/btw <hint>` saves the hint to a file on disk and cancels the command before an LLM call is made
+2. On every subsequent LLM call, the `experimental.chat.system.transform` hook reads the hint and appends it to the system prompt
+3. `/btw clear` removes the hint file
+
+Hints are **session-scoped** (each session has its own) and **project-scoped** (stored under a hash of the project directory). All data lives in `~/.cache/opencode/btw/`.
+
+## Use cases
+
+- **Error loops**: the model keeps making the same mistake — `/btw you're using the wrong API, check the docs for v2`
+- **Tool preference**: `/btw use Edit instead of sed, use Grep instead of grep`
+- **Scope nudge**: `/btw focus only on the auth module, don't touch other files`
+- **Strategy shift**: `/btw try a completely different approach, the current one won't work`
+- **Direct questions**: `/btw what file are you currently editing?`
+
+## License
+
+MIT
+
+---
+
+This is a community plugin and is not affiliated with or endorsed by the OpenCode project.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "opencode-btw",
+  "version": "0.1.0",
+  "description": "Hint injection plugin for OpenCode — nudge the model mid-task without interrupting its flow",
+  "main": "src/plugin.ts",
+  "files": [
+    "src",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "copilot",
+    "context-injection",
+    "btw"
+  ],
+  "author": "kldzj",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kldzj/opencode-btw.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kldzj/opencode-btw/issues"
+  },
+  "homepage": "https://github.com/kldzj/opencode-btw#readme",
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,145 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import { createHash } from "crypto"
+import { mkdirSync } from "fs"
+
+// btw — inject hints into the model's context without sending a new message.
+//
+// Uses two patterns:
+//   1. Sentinel error throw from command.execute.before — cancels the command
+//      before prompt() is called. No LLM request is made.
+//   2. experimental.chat.system.transform — appends the hint to the system
+//      prompt on every LLM call (including tool-loop iterations).
+//
+// File layout:
+//   ~/.cache/opencode/btw/<project-hash>/
+//     <sessionID>.txt       # hint content
+
+// System prompt instructions — explains the btw system
+const BTW_SYSTEM_INSTRUCTIONS = `<btw-hint-system>
+The user may inject real-time hints via the /btw command. These hints appear below as <btw-active-hint> blocks.
+When a hint is present:
+- Treat it as a direct, high-priority instruction from the user — equivalent to them telling you something face-to-face
+- Apply it IMMEDIATELY to your current and future actions — do not wait for a "good moment"
+- If the hint is a behavioral correction (e.g. "use Edit instead of sed"), adjust silently without calling attention to the change
+- If the hint is a direct request or question (e.g. "explain what you're doing"), respond to it naturally
+- If the hint contradicts your current approach, change course
+- The hint persists until the user clears it — apply it to every action, not just the next one
+- If the hint says to focus on specific files/areas, prioritize those and deprioritize others
+</btw-hint-system>`
+
+function projectHash(directory: string): string {
+  return createHash("md5").update(directory).digest("hex").slice(0, 12)
+}
+
+function btwDir(directory: string): string {
+  return `${process.env.HOME}/.cache/opencode/btw/${projectHash(directory)}`
+}
+
+// Sentinel error — thrown to prevent OpenCode from calling prompt() after the
+// command hook. Prevents an LLM call from being made for /btw commands.
+const BTW_HANDLED = "__BTW_HANDLED__"
+
+export const BtwPlugin: Plugin = async ({ directory, client }) => {
+  const dir = btwDir(directory)
+
+  try {
+    mkdirSync(dir, { recursive: true })
+  } catch {}
+
+  const hintPath = (sessionID: string) => `${dir}/${sessionID}.txt`
+
+  const readHint = async (sessionID: string): Promise<string> => {
+    try {
+      const file = Bun.file(hintPath(sessionID))
+      if (await file.exists()) {
+        return (await file.text()).trim()
+      }
+    } catch {}
+    return ""
+  }
+
+  const writeHint = async (sessionID: string, hint: string) => {
+    await Bun.write(hintPath(sessionID), hint)
+  }
+
+  // Send a no-op message that appears in the chat UI but is invisible to the
+  // LLM (noReply prevents inference, ignored: true hides it from message transforms).
+  const sendVisibleMessage = async (sessionID: string, text: string) => {
+    try {
+      await client.session.prompt({
+        path: { id: sessionID },
+        body: {
+          noReply: true,
+          parts: [{ type: "text" as const, text, ignored: true }],
+        },
+      })
+    } catch {
+      // Prompt API unavailable — silently skip
+    }
+  }
+
+  return {
+    // Register /btw as a command so it appears in /help and autocomplete.
+    // The template is minimal — command.execute.before intercepts before it's used.
+    config: (config) => {
+      ;(config as any).command = (config as any).command ?? {}
+      ;(config as any).command["btw"] = {
+        description:
+          "Inject a hint into the model's context (persists in system prompt until cleared)",
+        template: "$ARGUMENTS",
+      }
+    },
+
+    // Intercept /btw: save hint, send visible message, throw sentinel to prevent LLM call.
+    "command.execute.before": async (input, _output) => {
+      if (input.command !== "btw") return
+
+      const args = (input.arguments ?? "").trim()
+      const sessionID = input.sessionID
+
+      if (args === "clear" || args === "reset") {
+        await writeHint(sessionID, "")
+        await sendVisibleMessage(sessionID, "[btw] Hint cleared")
+        throw new Error(BTW_HANDLED)
+      }
+
+      if (!args) {
+        const hint = await readHint(sessionID)
+        await sendVisibleMessage(
+          sessionID,
+          hint ? `[btw] Current hint: "${hint}"` : "[btw] No hint set",
+        )
+        throw new Error(BTW_HANDLED)
+      }
+
+      // Set the hint
+      await writeHint(sessionID, args)
+      await sendVisibleMessage(sessionID, `[btw] Hint set: "${args}"`)
+      throw new Error(BTW_HANDLED)
+    },
+
+    // Inject hint into system prompt on every LLM call (including tool loops).
+    "experimental.chat.system.transform": async (input, output) => {
+      const sessionID = (input as Record<string, unknown>)?.sessionID
+      if (typeof sessionID !== "string" || !sessionID) return
+
+      try {
+        const hint = await readHint(sessionID)
+
+        if (hint) {
+          output.system.push(
+            [
+              BTW_SYSTEM_INSTRUCTIONS,
+              "",
+              "<btw-active-hint>",
+              hint,
+              "</btw-active-hint>",
+            ].join("\n"),
+          )
+        }
+      } catch {
+        // File read failed — no hint to inject
+      }
+    },
+  }
+}