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

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

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.

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

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

## License

MIT