opencode-handoff

Create focused handoff prompts for continuing work in new sessions.

Inspired by Amp's handoff command - see their post and manual about it.

Features

• /handoff <goal> command that analyzes the conversation and generates a continuation prompt
• Guides the AI to include relevant @file references so the next session starts with context loaded
• Opens the handoff prompt in an editable review dialog, then starts a new session with it and the referenced files
• read_session tool for retrieving full conversation transcripts from previous sessions when the handoff summary isn't sufficient

Requirements

• OpenCode v2.1.2 or later (opencode-handoff v0.5.0 is the last release for OpenCode v1)

Installation

Add to your OpenCode config (~/.config/opencode/opencode.json):

{
  "plugins": ["opencode-handoff"]
}

Restart OpenCode and you're ready to go.

Optionally, pin to a specific version for stability:

{
  "plugins": ["[email protected]"]
}

OpenCode fetches unpinned plugins from npm on each startup; pinned versions are cached and require a manual version bump to update.

Usage

1. Have a conversation in OpenCode with some context
2. When ready to continue in a fresh session, type /handoff <your goal>
3. A review dialog opens with the handoff draft; edit it if needed and press Enter to send (Esc cancels)
4. A new session starts with the prompt and the referenced files, and the TUI switches to it

Example:

/handoff implement the user authentication feature we discussed

The AI analyzes the conversation, extracts key decisions and relevant files, generates a focused prompt, and opens it for review before starting a new session.

Every @path in the sent text is attached, so editing the references changes the attached files. Review needs the terminal UI showing the source session; otherwise (for example with opencode run or the desktop app) the session starts without review.

To always skip review, set the review option to false:

{
  "plugins": [{ "package": "opencode-handoff", "options": { "review": false } }]
}

Reading Previous Session Transcripts

When you use /handoff, the generated prompt includes a session reference line:

Continuing work from session sess_01jxyz123. When you lack specific information you can use read_session to get it.

This gives the AI in the new session access to the read_session tool, which can fetch the full conversation transcript from the source session. If the handoff summary doesn't include something you need, just ask - the AI can look it up.

Example:

You: What were the specific error messages we saw earlier?

The AI will use read_session to retrieve details from the previous session that weren't included in the handoff summary.

Contributing

Contributions are welcome! Here's how to set up for development:

git clone https://github.com/joshuadavidthomas/opencode-handoff
cd opencode-handoff
bun install

Then point your OpenCode config at the checkout:

{
  "plugins": ["file:///path/to/opencode-handoff"]
}

License

opencode-handoff is licensed under the MIT license. See the LICENSE file for more information.

opencode-handoff is not built by, or affiliated with, the OpenCode team.

OpenCode is ©2025 Anomaly.