opencode-session-restart/README.md

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.

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 via the SDK session.summarize endpoint with the current session 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) 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). If no explicit model is given, the tool resolves the current session model from the last user message.
• 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