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"]]
}

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.

Development

bun install
bunx tsc --noEmit

License

MIT