opencode-session-restart

opencode plugin that lets the agent restart a session in place: clear the model context and continue working in the same session with a fresh, focused prompt, dodging context compaction loss and runaway context windows.

Works with OpenCode V1 (1.18.x) and V2 (2.x) from one package: the default export carries both the V1 server() implementation and the V2 setup(ctx) entrypoint, and V2 also accepts the legacy plugin config key.

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: it compacts the current session (pruning the old conversation from the model context while keeping it visible in the transcript) and then prompts a curated fresh task into the same session. No session switching, no child sessions.

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:

1. Compacts the current session — through the SDK session.summarize endpoint on the V1 plugin host, or ctx.session.compact on the V2 host (where compaction runs with the session's own model; there is no separate compaction model). Compaction advances the context boundary: earlier messages fall out of the model context but stay in the session transcript, exactly like a manual /compact.
2. Prompts the same session (via session.promptAsync on V1, ctx.session.prompt on V2) with the focused task plus optional carry-over notes and a fresh-start preamble stating that the earlier conversation remains readable in the transcript but is no longer part of the model context.
3. Returns immediately; the hand-off work continues in the same session.

The session ID never changes and the full history stays visible in the scrollback.

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" to compact with.
agent	string	current	Agent for the restarted session.

Notes on behavior

• Compaction runs one model call (the default summarize behavior on V1). On V1, if no explicit model is given, the tool resolves the current session model from the last user message; on V2, compaction always runs with the session's current model (an explicit model switches it first).
• The same session continues; on-disk state (git status, staged or uncommitted changes) carries over because it is the same project directory.
• The handoff message is a normal user turn in the same session, so it shows up in the transcript and is not counted as a fork/child session.

Development

bun install
bunx tsc --noEmit

License

MIT