opencode-btw 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 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.
+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 is picked up on the next LLM call, including during tool loops.
 
 ## Install
 
@@ -19,30 +19,54 @@ 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
+/btw use the Edit tool instead of sed       # add transient hint (auto-clears)
+/btw pin always use pnpm, not npm           # add persistent hint (manual clear)
+/btw clear                                  # remove all hints
+/btw clear last                             # remove the most recently added hint
+/btw                                        # show all active hints
 ```
 
-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).
+A confirmation message appears in the chat after each command. The model does not see this confirmation — only the hints themselves (via the system prompt).
+
+### Stacking hints
+
+Hints stack — each `/btw` adds to the list rather than replacing. This lets you layer corrections:
+
+```
+/btw pin always use TypeScript              # persistent base hint
+/btw fix the bug in auth.ts first           # transient nudge on top
+```
+
+After the model finishes its turn, the transient hint auto-clears while the pinned one remains.
+
+### Transient vs. pinned hints
+
+- **`/btw <hint>`** — auto-clears after the model finishes its current turn (including all tool calls). Use for one-off corrections and nudges.
+- **`/btw pin <hint>`** — persists until you run `/btw clear`. Use for session-wide preferences like "always use pnpm" or "focus on the auth module".
 
 ## 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
+2. On every subsequent LLM call, the `experimental.chat.system.transform` hook reads all hints and appends them to the system prompt
+3. When the model's turn finishes (`session.idle` event), transient hints are automatically removed while pinned hints stay
+4. `/btw clear` removes all hints, `/btw clear last` removes the most recent one
 
-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/`.
+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/`. Hint files are cleaned up automatically when sessions are deleted.
 
 ## 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`
+- **Tool preference**: `/btw pin 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?`
 
+## Development
+
+```bash
+bun test        # run test suite
+```
+
 ## License
 
 MIT

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "opencode-btw",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Hint injection plugin for OpenCode — nudge the model mid-task without interrupting its flow",
   "main": "src/plugin.ts",
+  "scripts": {
+    "test": "bun test"
+  },
   "files": [
-    "src",
+    "src/plugin.ts",
+    "src/core.ts",
     "LICENSE"
   ],
   "keywords": [

package/src/core.ts

@@ -0,0 +1,143 @@
+import { createHash } from "crypto"
+import { mkdirSync, unlinkSync } from "fs"
+
+export interface HintEntry {
+  text: string
+  pinned: boolean
+}
+
+export interface HintFile {
+  hints: HintEntry[]
+}
+
+export type ParsedCommand =
+  | { action: "clear"; which: "all" | "last" }
+  | { action: "status" }
+  | { action: "set"; text: string; pinned: boolean }
+  | { action: "error"; message: string }
+
+export const BTW_HANDLED = "__BTW_HANDLED__"
+
+export 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>`
+
+export function projectHash(directory: string): string {
+  return createHash("md5").update(directory).digest("hex").slice(0, 12)
+}
+
+export function btwDir(directory: string): string {
+  return `${process.env.HOME}/.cache/opencode/btw/${projectHash(directory)}`
+}
+
+export function hintPath(dir: string, sessionID: string): string {
+  return `${dir}/${sessionID}.json`
+}
+
+export function ensureDir(dir: string): void {
+  try {
+    mkdirSync(dir, { recursive: true })
+  } catch {}
+}
+
+export async function readHints(filePath: string): Promise<HintEntry[]> {
+  try {
+    const file = Bun.file(filePath)
+    if (await file.exists()) {
+      const data = await file.json()
+      // Handle new array format
+      if (Array.isArray(data?.hints) && data.hints.length > 0) {
+        return data.hints as HintEntry[]
+      }
+      // Handle legacy single-hint format
+      if (data?.text) {
+        return [{ text: data.text, pinned: data.pinned ?? false }]
+      }
+    }
+  } catch {}
+  return []
+}
+
+export async function writeHints(
+  filePath: string,
+  hints: HintEntry[],
+): Promise<void> {
+  if (hints.length === 0) {
+    await clearHints(filePath)
+    return
+  }
+  await Bun.write(filePath, JSON.stringify({ hints } satisfies HintFile))
+}
+
+export async function addHint(
+  filePath: string,
+  entry: HintEntry,
+): Promise<void> {
+  const existing = await readHints(filePath)
+  existing.push(entry)
+  await writeHints(filePath, existing)
+}
+
+export async function clearHints(filePath: string): Promise<void> {
+  try {
+    unlinkSync(filePath)
+  } catch {}
+}
+
+export async function removeTransient(filePath: string): Promise<boolean> {
+  const hints = await readHints(filePath)
+  const pinned = hints.filter((h) => h.pinned)
+  if (pinned.length === hints.length) return false // nothing removed
+  await writeHints(filePath, pinned)
+  return true
+}
+
+export async function removeLast(filePath: string): Promise<HintEntry | null> {
+  const hints = await readHints(filePath)
+  if (hints.length === 0) return null
+  const removed = hints.pop()!
+  await writeHints(filePath, hints)
+  return removed
+}
+
+export function parseCommand(rawArgs: string): ParsedCommand {
+  const args = rawArgs.trim()
+
+  if (args === "clear" || args === "reset") {
+    return { action: "clear", which: "all" }
+  }
+
+  if (args === "clear last") {
+    return { action: "clear", which: "last" }
+  }
+
+  if (!args) {
+    return { action: "status" }
+  }
+
+  if (args === "pin" || args.startsWith("pin ")) {
+    const text = args.slice(3).trim()
+    if (!text) {
+      return { action: "error", message: "Usage: /btw pin <hint>" }
+    }
+    return { action: "set", text, pinned: true }
+  }
+
+  return { action: "set", text: args, pinned: false }
+}
+
+export function buildSystemBlock(hints: HintEntry[]): string {
+  if (hints.length === 0) return ""
+  const hintBlocks = hints
+    .map((h) => `<btw-active-hint>\n${h.text}\n</btw-active-hint>`)
+    .join("\n\n")
+  return [BTW_SYSTEM_INSTRUCTIONS, "", hintBlocks].join("\n")
+}

package/src/plugin.ts

@@ -1,69 +1,39 @@
 import type { Plugin } from "@opencode-ai/plugin"
-import { createHash } from "crypto"
-import { mkdirSync } from "fs"
+
+import {
+  BTW_HANDLED,
+  addHint,
+  buildSystemBlock,
+  btwDir,
+  clearHints,
+  ensureDir,
+  hintPath,
+  parseCommand,
+  readHints,
+  removeLast,
+  removeTransient,
+} from "./core"
 
 // 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).
+// Uses three hooks:
+//   1. command.execute.before — intercepts /btw, saves hint, throws sentinel
+//      to cancel the LLM call entirely.
+//   2. experimental.chat.system.transform — appends hints to the system prompt
+//      on every LLM call (including tool-loop iterations).
+//   3. event — listens for session.idle to auto-clear transient hints, and
+//      session.deleted to clean up hint files.
 //
 // 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__"
+//     <sessionID>.json       # { hints: [{ text, pinned }] }
 
 export const BtwPlugin: Plugin = async ({ directory, client }) => {
   const dir = btwDir(directory)
+  ensureDir(dir)
 
-  try {
-    mkdirSync(dir, { recursive: true })
-  } catch {}
-
-  const hintPath = (sessionID: string) => `${dir}/${sessionID}.txt`
+  const hint = (sessionID: string) => hintPath(dir, sessionID)
 
-  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({
@@ -73,73 +43,109 @@ export const BtwPlugin: Plugin = async ({ directory, client }) => {
           parts: [{ type: "text" as const, text, ignored: true }],
         },
       })
-    } catch {
-      // Prompt API unavailable — silently skip
-    }
+    } catch {}
   }
 
   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)",
+          "Inject a hint into the model's context (stacks; transient by default, use 'pin' to persist)",
         template: "$ARGUMENTS",
       }
     },
 
-    // Intercept /btw: save hint, send visible message, throw sentinel to prevent LLM call.
+    event: async ({ event }) => {
+      // Auto-clear transient hints when the model finishes a complete turn
+      if (event.type === "session.idle") {
+        const sessionID = (event as any).properties?.sessionID
+        if (typeof sessionID !== "string") return
+
+        const removed = await removeTransient(hint(sessionID))
+        if (removed) {
+          await sendVisibleMessage(sessionID, "[btw] Transient hints auto-cleared")
+        }
+      }
+
+      // Clean up hint files when sessions are deleted
+      if (event.type === "session.deleted") {
+        const sessionID = (event as any).properties?.sessionID
+        if (typeof sessionID === "string") {
+          await clearHints(hint(sessionID))
+        }
+      }
+    },
+
     "command.execute.before": async (input, _output) => {
       if (input.command !== "btw") return
 
-      const args = (input.arguments ?? "").trim()
       const sessionID = input.sessionID
+      const parsed = parseCommand(input.arguments ?? "")
+
+      switch (parsed.action) {
+        case "clear":
+          if (parsed.which === "last") {
+            const removed = await removeLast(hint(sessionID))
+            if (removed) {
+              await sendVisibleMessage(
+                sessionID,
+                `[btw] Removed last hint: "${removed.text}"`,
+              )
+            } else {
+              await sendVisibleMessage(sessionID, "[btw] No hints to remove")
+            }
+          } else {
+            await clearHints(hint(sessionID))
+            await sendVisibleMessage(sessionID, "[btw] All hints cleared")
+          }
+          throw new Error(BTW_HANDLED)
+
+        case "status": {
+          const hints = await readHints(hint(sessionID))
+          if (hints.length === 0) {
+            await sendVisibleMessage(sessionID, "[btw] No hints set")
+          } else {
+            const lines = hints.map((h, i) => {
+              const label = h.pinned ? "pinned" : "transient"
+              return `  ${i + 1}. [${label}] "${h.text}"`
+            })
+            await sendVisibleMessage(
+              sessionID,
+              `[btw] Active hints:\n${lines.join("\n")}`,
+            )
+          }
+          throw new Error(BTW_HANDLED)
+        }
 
-      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)
+        case "error":
+          await sendVisibleMessage(sessionID, `[btw] ${parsed.message}`)
+          throw new Error(BTW_HANDLED)
+
+        case "set":
+          await addHint(hint(sessionID), {
+            text: parsed.text,
+            pinned: parsed.pinned,
+          })
+          const verb = parsed.pinned ? "Pinned hint" : "Hint"
+          await sendVisibleMessage(
+            sessionID,
+            `[btw] ${verb} added: "${parsed.text}"`,
+          )
+          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"),
-          )
+        const hints = await readHints(hint(sessionID))
+        if (hints.length > 0) {
+          output.system.push(buildSystemBlock(hints))
         }
-      } catch {
-        // File read failed — no hint to inject
-      }
+      } catch {}
     },
   }
 }