83 lines
No EOL
3.7 KiB
Markdown
83 lines
No EOL
3.7 KiB
Markdown
# 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 |