opencode-handoff-plus

Model-authored structured session handoffs for OpenCode with file-based persistence.

Forked from opencode-handoff. This version keeps the plugin server-only and lets the current model author the handoff instead of synthesizing it in plugin code.

How it works

When you run /handoff, the plugin:

1. Prompts the current model with an OMO-quality handoff template.
2. The model writes the structured handoff in the current session.
3. The model calls write_handoff_file with the full completed handoff text and optional key files.
4. The tool persists identical handoff text to:
   • .planning/session/YYYY-MM-DD-HHMM-handoff.md
   • .planning/session/HANDOFF-latest.md
5. The tool opens a new session with only a small resume prompt:
   • Resume from .planning/session/HANDOFF-latest.md. Read it first, then continue the work.

The full handoff is not pasted into the new session. The new session reads the latest handoff file first, then continues from there.

Handoff sections

The /handoff prompt asks the model to produce these sections:

• HANDOFF CONTEXT — Source session and optional user direction
• USER REQUESTS (AS-IS) — Important requests and constraints
• GOAL — Primary continuation objective
• WORK COMPLETED — Concrete changes, decisions, commands, and results
• CURRENT STATE — Repo/session state, test status, blockers, uncommitted work
• PENDING TASKS — Next actions in priority order
• KEY FILES — Workspace-relative files to inspect or continue editing
• IMPORTANT DECISIONS — Design choices and rationale
• EXPLICIT CONSTRAINTS — Active user/developer constraints
• CONTEXT FOR CONTINUATION — Extra resume notes and when to use read_session

Tools

• write_handoff_file — saves the completed model-authored handoff to dated/latest files and opens a new session with a short resume prompt.
• read_session — reads a previous session transcript when the continuation agent needs details not included in the handoff.

Install

opencode plugin install opencode-handoff-plus

Local development install:

opencode plugin install file:///home/openclaw/github/opencode-handoff-plus

Or add to .opencode/plugins.json:

{
  "opencode-handoff-plus": "file:///home/openclaw/github/opencode-handoff-plus"
}

Usage

/handoff

With direction:

/handoff Finish the remaining tests and fix the flaky CI job

Files

| File | Purpose | |------|---------| | src/plugin.ts | Server-only plugin entry point, command registration, resume file hydration | | src/tools.ts | read_session and write_handoff_file tool definitions | | src/session-files.ts | Writes dated/latest handoff files | | src/files.ts | @file reference parsing and synthetic file part building | | src/vendor.ts | OpenCode Read tool format helpers |

Development

npm install
bun run typecheck
npm pack

Troubleshooting checklist

• Durable global plugin spec should be opencode-handoff-plus@latest
• Avoid local overrides in ~/.agents/.opencode/opencode.json
• Clear stale cache if needed: rm -rf ~/.cache/opencode/packages/opencode-handoff-plus@latest
• Reinstall globally: opencode plugin opencode-handoff-plus@latest --global --force
• Check runtime logs in ~/.local/share/opencode/log/

License

MIT