opencode-session-handoff

An OpenCode plugin for seamless session continuation when context windows fill up.

Installation

Add to your ~/.config/opencode/opencode.json:

{
  "plugin": ["opencode-session-handoff"]
}

Then restart OpenCode. The plugin will auto-update when new versions are released.

What it does

When your OpenCode session gets too long, use session_handoff to:

1. Create a new session titled "Handoff: {previous title}"
2. Transfer a compact continuation prompt (~100-200 tokens)
3. Preserve your agent mode and model settings
4. Open the session picker so you can switch to it

Tools

session_handoff

Creates a new session with continuation context.

Usage: Say "handoff" or "handoff <goal>"

Examples:

• handoff - Creates a handoff with summary of current work
• handoff implement the login feature - Creates a handoff with goal "implement the login feature"
• handoff fix the failing tests - Creates a handoff with goal "fix the failing tests"

Arguments (provided by the assistant):

• summary (required): 1-3 sentence summary of current state
• goal (optional): What the user wants to accomplish in the next session (extracted from "handoff ")
• next_steps (optional): Remaining tasks
• blocked (optional): Current blocker
• key_decisions (optional): Important decisions made
• files_modified (optional): Key files changed

Auto-fetched:

• Todo list status (completed/in-progress/pending)
• Agent mode (e.g., Sisyphus, build, plan)
• Model configuration (provider + model ID)

read_session

Reads messages from the previous session for additional context.

Usage: In a handoff session, ask to "read the previous session" if you need more details.

Use sparingly—fetches the last 20 messages which uses significant tokens.

Auto-Update

The plugin checks for updates on every new session. When a new version is available:

1. Updates your opencode.json config
2. Invalidates the cached package
3. Runs bun install
4. Shows a toast notification

Restart OpenCode to apply updates.

Development

See CONTRIBUTING.md for development setup and guidelines.

How it works

1. Agent provides a summary of current work
2. Plugin fetches todo list and model config from current session
3. Builds a compact handoff prompt
4. Creates new session via session.create
5. Sends the prompt via session.promptAsync
6. Opens session picker via tui.openSessions

Inspired by Amp's handoff feature.

License

MIT