f991c4d0f8
Compacts the current session (summarize) to advance the context boundary, then prompts the focused task into the same session with promptAsync. The session ID never changes and older messages stay visible in the transcript.
85 lines
No EOL
3.8 KiB
Markdown
85 lines
No EOL
3.8 KiB
Markdown
# 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 |