@andrewhampton/opencode-handoff 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Hampton
+
+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,58 @@
+# opencode-handoff
+
+An [OpenCode](https://opencode.ai) plugin that implements the `/handoff` command, allowing you to transfer context from one session to a new one.
+
+## What it does
+
+When you run `/handoff <instruction>`, the plugin:
+
+1. Asks the AI to summarize the current thread context
+2. Creates a new session
+3. Sends the handoff prompt (with your instruction) to the new session
+4. Shows a toast notification when complete
+
+The new session uses the same model as the original session.
+
+## Installation
+
+Add the plugin and command to your `opencode.json` (or `opencode.jsonc`). The plugin is available on npm as `opencode-handoff`, and OpenCode will install it automatically when you restart:
+
+```json
+{
+  "plugin": ["opencode-handoff"],
+  "command": {
+    "handoff": {
+      "description": "Create a handoff prompt in a new session",
+      "template": "Create a handoff prompt based on the instruction:\n\n$ARGUMENTS\n\nRequirements:\n- Review the current thread before responding.\n- Produce a prompt for a new thread that includes relevant context from this thread.\n- Conclude with a verbatim copy of the instruction above."
+    }
+  }
+}
+```
+
+Then restart OpenCode.
+
+> **Note:** Both the plugin and command are required. The command tells the AI how to generate the handoff summary, and the plugin listens for the command's completion to create the new session.
+
+## Usage
+
+In any OpenCode session, type:
+
+```
+/handoff <your instruction>
+```
+
+For example:
+```
+/handoff Continue implementing the user authentication feature
+```
+
+The AI will review the current thread, create a summary with relevant context, and start a new session with that context plus your instruction.
+
+## Limitations
+
+- No API to auto-switch to the new session (you need to manually switch via `ctrl+p` > sessions)
+- The command runs after completion, so there's a brief delay while the AI generates the handoff prompt
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1 @@
+export { HandoffPlugin } from "./plugin/handoff.ts"

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@andrewhampton/opencode-handoff",
+  "version": "0.1.0",
+  "description": "Handoff command plugin for OpenCode - transfer context to a new session",
+  "type": "module",
+  "main": "index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "types": "./index.ts",
+  "files": [
+    "index.ts",
+    "plugin/"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "opencode",
+    "plugin",
+    "handoff",
+    "session",
+    "context"
+  ],
+  "author": "Andrew Hampton",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrewhampton/opencode-handoff.git"
+  },
+  "bugs": {
+    "url": "https://github.com/andrewhampton/opencode-handoff/issues"
+  },
+  "homepage": "https://github.com/andrewhampton/opencode-handoff#readme",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin/handoff.ts

@@ -0,0 +1,182 @@
+import type { Plugin } from "@opencode-ai/plugin"
+
+const getResponseData = <T>(response: { data?: T } | T): T => {
+  if (typeof response === "object" && response !== null && "data" in response) {
+    return response.data as T
+  }
+
+  return response as T
+}
+
+type MessageEntry = {
+  info: {
+    id: string
+    role: "user" | "assistant"
+    parentID?: string
+    providerID?: string
+    modelID?: string
+  }
+  parts: Array<{ type: string; text?: string }>
+}
+
+export const HandoffPlugin: Plugin = async ({ client }) => {
+  const log = async (level: "info" | "error", message: string, extra?: object) => {
+    try {
+      await client.app.log({
+        body: {
+          service: "handoff",
+          level,
+          message,
+          extra,
+        },
+      })
+    } catch {
+      // Ignore log failures
+    }
+  }
+
+  const promptForInstruction = async () => {
+    await client.tui.showToast({
+      body: {
+        message: "Provide a handoff instruction after /handoff",
+        variant: "warning",
+      },
+    })
+    await client.tui.appendPrompt({ body: { text: "/handoff " } })
+  }
+
+  const extractMessageText = (entry?: MessageEntry) => {
+    if (!entry) {
+      return ""
+    }
+
+    return entry.parts
+      .filter((part) => part.type === "text")
+      .map((part) => part.text ?? "")
+      .join("")
+      .trim()
+  }
+
+  const buildHandoff = async (sessionID: string, assistantMessageID: string, instruction: string) => {
+    await log("info", "buildHandoff called", { sessionID, assistantMessageID })
+
+    let messages: Array<MessageEntry>
+    try {
+      const response = await client.session.messages({
+        path: { id: sessionID },
+      })
+      messages = getResponseData<Array<MessageEntry>>(response)
+      await log("info", `Fetched ${messages.length} messages`)
+    } catch (err) {
+      await log("error", `Failed to fetch messages: ${err}`)
+      throw err
+    }
+
+    // The messageID from command.executed is the assistant message itself
+    const assistantMessage = messages.find(
+      (message) => message.info.id === assistantMessageID
+    )
+
+    await log("info", `Looking for message id=${assistantMessageID}`)
+    await log("info", `Assistant message found: ${!!assistantMessage}`)
+
+    const handoffText = extractMessageText(assistantMessage)
+
+    if (!handoffText) {
+      await log("error", "No handoff text found")
+      throw new Error("No handoff content returned from the command")
+    }
+
+    await log("info", `Handoff text length: ${handoffText.length}`)
+
+    // Get the model from the assistant message
+    const providerID = assistantMessage?.info.providerID
+    const modelID = assistantMessage?.info.modelID
+    await log("info", `Using model: ${providerID}/${modelID}`)
+
+    let createdSessionId: string
+    try {
+      const created = await client.session.create({ body: {} })
+      const createdSession = getResponseData<{ id: string }>(created)
+      createdSessionId = createdSession.id
+      await log("info", `Created session: ${createdSessionId}`)
+    } catch (err) {
+      await log("error", `Failed to create session: ${err}`)
+      throw err
+    }
+
+    // Show toast immediately so user knows handoff is ready
+    await client.tui.showToast({
+      body: {
+        message: `Handoff session created`,
+        variant: "success",
+        duration: 5000,
+      },
+    })
+
+    // Send the prompt and trigger AI response (don't await - let it run in background)
+    const promptBody: {
+      parts: Array<{ type: "text"; text: string }>
+      model?: { providerID: string; modelID: string }
+    } = {
+      parts: [{ type: "text", text: handoffText }],
+    }
+
+    if (providerID && modelID) {
+      promptBody.model = { providerID, modelID }
+    }
+
+    client.session.prompt({
+      path: { id: createdSessionId },
+      body: promptBody,
+    }).then(() => {
+      log("info", "AI response completed in handoff session")
+    }).catch((err) => {
+      log("error", `AI response failed: ${err}`)
+    })
+
+    await log("info", "Handoff session created, AI responding in background")
+  }
+
+  return {
+    event: async ({ event }) => {
+      try {
+        if (event.type === "command.executed") {
+          await log("info", `Event received: ${event.type}`, { name: (event.properties as { name?: string }).name })
+          
+          if ((event.properties as { name?: string }).name !== "handoff") {
+            return
+          }
+
+          const props = event.properties as {
+            name: string
+            sessionID: string
+            messageID: string
+            arguments?: string
+          }
+
+          await log("info", "Handoff command matched", props)
+
+          const instruction = props.arguments?.trim() ?? ""
+          if (!instruction) {
+            await promptForInstruction()
+            return
+          }
+
+          await log("info", "About to call buildHandoff")
+          await buildHandoff(props.sessionID, props.messageID, instruction)
+          await log("info", "buildHandoff completed")
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err)
+        await log("error", `Event handler error: ${message}`)
+        await client.tui.showToast({
+          body: {
+            message: `Handoff failed: ${message}`,
+            variant: "error",
+          },
+        })
+      }
+    },
+  }
+}