Skip to content

Instantly share code, notes, and snippets.

@cassiodias
Created June 28, 2026 19:47
Show Gist options
  • Select an option

  • Save cassiodias/83a56ad40e1add6b95ab9b7dc9d99963 to your computer and use it in GitHub Desktop.

Select an option

Save cassiodias/83a56ad40e1add6b95ab9b7dc9d99963 to your computer and use it in GitHub Desktop.
opencode session-bootstrap.js
// OpenCode session-bootstrap plugin -- generic skeleton.
//
// Demonstrates the `session.created` pattern discussed in
// sst/opencode#5409: run a one-time setup step when a new session begins,
// surface a short status to the user, and inject a brief primer for the model.
//
// Two non-obvious things this guards against, both hit in real use:
//
// 1. `session.created` fires on the first real interaction, not at TUI launch.
// Subscribing to the event (not the plugin `init`) is what catches a new
// session.
//
// 2. The plugin factory can be evaluated more than once per process (e.g. the
// same plugin present in more than one loaded config layer), so the handler
// can see `session.created` twice for ONE new session. A module-level Set of
// already-seen session ids makes the bootstrap at-most-once. The id is added
// BEFORE the async work so a second event arriving mid-flight is still
// dropped.
//
// What this does NOT solve: resume. `--continue` / `--resume` / `/resume` emit
// no bus event, so a resumed session never reaches this handler. That gap is the
// motivation for a native `session.start` hook with a `source` matcher.
const seen = new Set();
// Replace with your own setup work (gather git status, install deps, load
// context, etc.). Must never throw -- a failed bootstrap should not crash the
// session. Return whatever you want to surface, or null for a silent no-op.
async function bootstrap({ directory }) {
try {
// example: const out = await Bun.spawn(["./scripts/setup.sh"], { cwd: directory, stdout: "pipe" });
return { status: "session bootstrapped" };
} catch (_err) {
return null;
}
}
export const plugin = async ({ client, directory: inputDirectory }) => {
return {
event: async ({ event }) => {
if (!event || event.type !== "session.created") return;
const info = event.properties && event.properties.info;
// Skip child / subagent sessions -- only bootstrap a top-level session.
if (info && info.parentID) return;
const sessionID = info && info.id;
if (!sessionID) return;
// At-most-once per session id. Set BEFORE the async work so a second
// event for the same session (double factory eval) is dropped.
if (seen.has(sessionID)) return;
seen.add(sessionID);
// Prefer the session's own workspace dir; fall back to the plugin cwd.
const directory = (info && info.directory) || inputDirectory;
const result = await bootstrap({ directory });
if (!result) return;
// Short status to the user (single-line toast).
if (client && client.tui && typeof client.tui.showToast === "function") {
try {
await client.tui.showToast({
...(directory ? { query: { directory } } : {}),
body: { message: result.status, variant: "info", title: "bootstrap" },
});
} catch (_err) {
/* toast failure is non-fatal */
}
}
// Optional: a one-line primer for the model. `noReply: true` appends a
// single user message with no assistant turn (no reply, no token burn).
// Deferred + un-awaited so it never blocks the handler.
if (client && client.session && typeof client.session.prompt === "function") {
queueMicrotask(() => {
Promise.resolve(
client.session.prompt({
path: { id: sessionID },
...(directory ? { query: { directory } } : {}),
body: {
noReply: true,
parts: [{ type: "text", text: "Session context is loaded for this session." }],
},
})
).catch(() => {
/* injection failure is non-fatal */
});
});
}
},
};
};
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment