Sessions

Give your opencode agent memory of past sessions. Recall what you tried last time, check what a subagent's session actually did, or search weeks of transcripts for that one snippet — all without leaving the conversation. opencode-sessions adds four read-only tools that let an agent list, inspect, read, and search local opencode session history through opencode's SDK session API. Nothing it exposes can modify, delete, or resume a session.

Quick Start

Requirements:

• Node.js >=20.11.0
• opencode with plugin support

Install the package:

bun add @mcrescenzo/opencode-sessions

npm install @mcrescenzo/opencode-sessions

Register it in opencode.json:

{
  "plugin": ["@mcrescenzo/opencode-sessions"]
}

For local development from a source checkout, register the checkout entrypoint path instead of the package name:

{
  "plugin": ["./opencode-sessions.js"]
}

This plugin does not auto-allow its tools. Grant only the tools you want agents to use:

{
  "permission": {
    "session_list": "allow",
    "session_info": "allow",
    "session_read": "allow",
    "session_search": "allow"
  }
}

After installing, registering, or changing this plugin, restart opencode. Running sessions keep already-loaded plugin code.

Example

Say you can't remember which past session settled on an auth approach. Ask the agent directly — it can search transcripts and read the one that matches:

"What did we decide about auth? I think it came up in a session last week."

The agent first calls session_search to find candidate sessions, then session_read to pull the full exchange from the one that matches. The output below is illustrative — the session IDs and message content are made up for this example — but the format matches what the tools actually return.

session_search({ query: "auth" })

Session search for text "auth" in /home/user/project: 3 matches across 12 session(s) scanned, 640 message(s) scanned
1. ses_a1b2c3d4 — Refactor auth middleware
   message=msg_9f8e7d6c role=assistant time=2026-06-30T18:22:04.000Z
   …we decided to use short-lived JWTs with a 15-minute expiry and rotate refresh tokens server-side, no session cookies…
2. ses_a1b2c3d4 — Refactor auth middleware
   message=msg_9f8e7d71 role=user time=2026-06-30T18:23:11.000Z
   …agreed, let's lock that in and update the API gateway config…
3. ses_7f00e211 — Fix login redirect loop
   message=msg_11aa22bb role=assistant time=2026-06-24T09:04:57.000Z
   …the redirect loop was unrelated to auth, it was a stale cookie path…

session_read({ sessionId: "ses_a1b2c3d4", limit: 20 })

Transcript for Refactor auth middleware (ses_a1b2c3d4) in /home/user/project: 20 messages (limit=20)

--- user msg_9f8e7d6b @ 2026-06-30T18:21:50.000Z
What auth approach should we use for the new service?

--- assistant msg_9f8e7d6c @ 2026-06-30T18:22:04.000Z
Let's use short-lived JWTs (15-minute expiry) with server-side refresh token rotation. No session cookies — Authorization header only.

--- user msg_9f8e7d71 @ 2026-06-30T18:23:11.000Z
Agreed, let's lock that in and update the API gateway config.

The agent now answers from the actual transcript instead of guessing.

For AI agents

Tools are read-only, scoped to the current project directory, and output-bounded by default (session_read caps at 100 messages / 30,000 characters unless raised). When you don't know which session to read, call session_search first to find a sessionId — it's cheaper than scanning sessions one at a time with session_read.

Tools

All tools are read-only, output-bounded, and scoped to the invoking opencode session's current project directory. Caller-supplied directory values are accepted for compatibility but ignored.

session_list

Lists local sessions for the current project directory.

Argument	Type	Default	Bounds	Notes
directory	string	current project	ignored	Compatibility-only; context.directory is always used.
limit	integer	50	1..200	Maximum sessions shown.
includeCurrent	boolean	true	-	Include the current opencode session.
sort	enum	updated-desc	updated-desc, created-desc	Session ordering.

session_info

Shows one session's metadata, status, children, todos, and optional diff summary.

Argument	Type	Default	Bounds	Notes
sessionId	string	required	non-empty	Session to inspect.
directory	string	current project	ignored	Compatibility-only; context.directory is always used.
includeChildren	boolean	true	-	Include child-session count.
includeTodos	boolean	true	-	Include todo summary.
includeStatus	boolean	true	-	Include current status.
includeDiff	boolean	false	-	Include diff summary.

session_read

Reads a bounded, redacted formatted transcript for one session.

Argument	Type	Default	Bounds	Notes
sessionId	string	required	non-empty	Session to read.
directory	string	current project	ignored	Compatibility-only; context.directory is always used.
limit	integer	100	1..500	Maximum messages read.
includeToolCalls	boolean	false	-	Include bounded tool input/output details.
includeMetadata	boolean	false	-	Include bounded message metadata.
maxPartChars	integer	4000	500..12000	Per-part cap before formatting.
maxOutputChars	integer	30000	2000..80000	Total output cap.

There is no raw transcript mode in the public API. Use includeToolCalls and includeMetadata explicitly when you need more detail.

session_search

Searches recent local session transcripts and returns bounded, redacted snippets.

Argument	Type	Default	Bounds	Notes
query	string	required	text: 1..1000, regex: 1..300	Text or regex pattern.
directory	string	current project	ignored	Compatibility-only; context.directory is always used.
sessionId	string	none	-	Search a single session instead of recent sessions.
maxSessions	integer	25	1..100	Recent sessions considered when sessionId is absent.
maxMessagesPerSession	integer	100	1..300	Messages scanned per session.
caseSensitive	boolean	false	-	Case-sensitive matching.
regex	boolean	false	-	Treat query as a regular expression.
includeToolCalls	boolean	false	-	Include tool input/output text in searchable content.
maxPartChars	integer	4000	500..12000	Per-part cap before searching.
maxOutputChars	integer	30000	2000..80000	Total output cap.

Literal queries are capped at 1000 characters. Regex patterns are capped at 300 characters. Invalid regex syntax returns a bounded error, and known unsafe nested-quantifier or optional-atom-chain shapes are rejected to reduce catastrophic-backtracking risk. Regex matching still uses the JavaScript regular-expression engine, so prefer literal search for untrusted patterns.

Read-Only Guarantee

The plugin intentionally exposes only:

• session_list
• session_info
• session_read
• session_search

It does not expose mutating opencode session APIs such as delete, update, prompt, promptAsync, command, shell, fork, share, abort, summarize, revert, or unrevert. Tests include tripwires to ensure tool execution does not call those APIs.

Privacy Model

Session transcripts can contain secrets, proprietary code, prompts, tool output, file paths, and local metadata. This plugin applies best-effort redaction for common secret shapes, URL credentials, sensitive query parameters, and sensitive object keys, strips terminal control sequences, then caps output sizes. Redaction is not a security boundary and cannot guarantee removal of every sensitive value.

Defaults avoid tool I/O and metadata in transcript output. Users must opt into includeToolCalls or includeMetadata per call.

User-facing SDK error messages and echoed search queries are redacted before display. Returned sessions are locally directory-validated when opencode provides a project directory. Degraded transcript output is reserved for decode/read-format failures; SDK/API failures surface distinctly.

Development And Release

This plugin registers two hooks internally (config, tool); see docs/architecture.md for details.

For the development setup, verification commands, release process, and the versioned-contract / breaking-change policy, see CONTRIBUTING.md.

Support And Security

Use GitHub issues for bugs and documentation requests. Do not include secrets or private transcript content in public issues. Report suspected vulnerabilities privately using GitHub security advisories on this repository; see SECURITY.md.

See CONTRIBUTING.md for the development workflow and pull request expectations, and CODE_OF_CONDUCT.md for community standards.