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) freeze the old session. 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", { "abort_current": 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 tells the new session not to reconstruct the old conversation and to orient itself from the working tree.
Aborts the current session by default, so only the restarted session stays active.
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.
`abort_current`	boolean	`true`	Abort this session after restarting.

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.
abort_current freezes the original session after the new one is started. Because abort cancels the current agent turn, the tool's returned text may not be delivered to the old session — the side effects (create + prompt) complete first.
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

3.9 KiB Raw Blame History