# 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:

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

or from a local clone:

```json
{
  "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.

  ```json
  {
    "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.

  ```json
  {
    "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

```bash
bun install
bunx tsc --noEmit
```

## License

MIT