opencode-session-restart

opencode plugin that lets the agent restart a session into a fresh child session with a clean context window and a focused prompt, dodging context compaction loss.

When a session runs long enough to trigger compaction, opencode summarizes the conversation into a prompt and keeps going — fidelity you did not choose. This plugin gives the agent a first-class escape hatch: start a new child session on the same project, prompt it with a curated fresh prompt, and (by default) keep the current session alive so its full history stays readable. The single focused task continues in a fresh window.

Install

Add the plugin to your opencode config:

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

or from a local clone:

{
  "plugin": [["/path/to/opencode-session-restart", { "disable_compaction_continue": true }]]
}

What it does

The plugin registers one tool, session_restart, that the agent can call when the session is getting long:

• Creates a child session (via the SDK session.create with parentID), so it shows up in the session tree under the original.
• Immediately prompts it (via session.promptAsync) with the focused task plus optional carry-over notes and a fresh-start preamble that points at the parent session for the full earlier conversation and tells the new session to orient itself from the working tree.
• Leaves the current session running, so its full history stays visible and readable in the session tree.
• Returns the new session ID so the agent can tell you where to switch.

Static handoff text

A static text that is always included in the restart prompt, when defined:

• Per agent (overrides the global default): add a handoff_text key to any agent in opencode.json (or any frontmatter key in agent/*.md — unknown keys fold into the agent's options and are read from there). The text of the agent the restarted session runs under is used.

  {
    "agent": {
      "build": {
        "handoff_text": "Always start by reviewing the open PRs on git.jilits.se before touching any code."
      }
    }
  }
  

• Global fallback: set the static_text plugin option. It applies to every restart whenever the agent defines no handoff_text of its own.

  {
    "plugin": [["/path/to/opencode-session-restart", { "static_text": "..." }]]
  }
  

Either way the text is prepended to the handoff prompt under a STANDING INSTRUCTIONS section. Precedence: agent handoff_text (direct key, or md-frontmatter handoff_text) → static_text plugin option → nothing.

Tool arguments

argument	type	default	description
task	string	—	The single focused task for the restarted session, written as a fresh prompt.
notes	string	—	Durable context to carry over: decisions, constraints, files touched, unfinished steps. Omit to rely on the working tree only.
model	string	current	"providerID/modelID" for the restarted session.
agent	string	current	Agent for the restarted session.

Notes on behavior

• The new session keeps the fresh prompt as its user-turn text and immediately starts working. On-disk state (git status, staged or uncommitted changes) carries over because it is the same project directory.
• The original session is always left running and its full transcript remains in the session tree — the clean context lives in the child session. The handoff prompt includes the parent session ID so both you and the model know where to read the earlier conversation.
• disable_compaction_continue (default true) rejects the synthetic "continue" turn opencode would append after a compaction, so a compaction that does slip through never silently continues. Set it to false to keep stock behavior.

Development

bun install
bunx tsc --noEmit

License

MIT