OpenCode Plugin: read-session

A plugin for OpenCode (GitHub) that enables cross-session context reuse. Inspired by AmpCode's read threads, it allows you to reference previous conversations and extract relevant information without loading full session histories into context.

Features

• Read Sessions (read_session): Extract relevant information from any OpenCode session using AI summarization
• List Sessions (list_sessions): View recent sessions for the current project in a formatted table
• Project-Scoped: Sessions are automatically filtered to the current working directory/project
• Pre-Filtered Context: Session content is filtered before being sent to the summarizing model (removes reasoning, truncates long outputs, skips noise)
• Smart Summarization: Spawns a sub-agent to extract only relevant information—decisions, code, constraints, and errors—while removing repetition and saving a lot of context from the top level agent.
• Configurable: JSON config file for model and truncation length settings

Installation

1. Clone this repository:

git clone https://github.com/quaternion7/opencode-read-session.git
cd opencode-read-session

2. Build the plugin:

npm install
npm run build

3. Add to OpenCode configuration:

Edit ~/.config/opencode/opencode.json and add the absolute path to the plugin:

{
  "plugins": [
    "/absolute/path/to/opencode-read-session"
  ]
}

Usage

Simply ask the agent to work with previous sessions. The agent will automatically use the appropriate tools to list, find, or read session content.

Listing Sessions

Ask the agent to show your recent sessions:

• "List my recent sessions"
• "Show me the sessions I had yesterday"
• "What sessions do I have for this project?"

Referencing Sessions by Title

You can refer to sessions by their title, and the agent will find the correct one:

• "Read the session about API design decisions"
• "What did we decide in the database schema session?"
• "Consider the authentication refactoring session we had"

Direct Session Reference

If you know the session ID, you can reference it directly:

• "Look at session ses_abc123 for the implementation details"

Tools

The plugin provides two tools:

read_session

Read another OpenCode session and extract only relevant information.

Use when:

• A session_id is provided
• You need prior context
• You want a concise summary

read_session({
  session_id: "ses_abc123...",
  sub_prompt: "What were the key technical decisions?"
})

How it works:

1. Exports the target session using OpenCode CLI
2. Pre-filters the content (removes reasoning parts, truncates long tool outputs, formats tool calls)
3. Sends filtered content to a summarizing model
4. Returns a concise summary focused on your query

list_sessions

List recent OpenCode sessions for the current project/directory.

Use when:

• User wants to see their recent sessions
• User needs to find a session ID to read
• User asks "what sessions do I have" or "show my sessions"

list_sessions({
  directory: "/path/to/project",  // Current working directory (from context)
  limit: 20                       // Maximum sessions to show (default: 20)
})

Important: Sessions are filtered to show only those in the specified directory. The current working directory is automatically provided from the environment context.

Returns a formatted table with:

• Session ID
• Title
• Directory (shortened with ~ for home directory)
• Last updated time (relative: "just now", "5m ago", "2h ago", etc.)

Configuration

Create a config file at:

• ~/.config/opencode/opencode-read-session.json (or .jsonc for JSON with comments)

Example:

{
  "model": "openai/gpt-4o-mini",
  "temperature": 0.3,
  "perMessageTruncationLength": 5000
}

Options

Option	Type	Default	Description
model	string	zai-coding-plan/glm-4.7	Model for summarization (format: provider/model)
temperature	number	0.3	Sampling temperature for the model
perMessageTruncationLength	number	5000	Max characters per individual tool output before truncation (not overall session)

Model Format

Models must be specified in provider/model format:

• openai/gpt-4o-mini
• anthropic/claude-3-sonnet
• zai-coding-plan/glm-4.7

Default: zai-coding-plan/glm-4.7

Project Structure

opencode-read-session/
├── package.json
├── tsconfig.json
├── LICENSE
├── src/
│   ├── index.ts              # Plugin entry point
│   ├── context.ts            # Plugin context storage
│   ├── config.ts             # Configuration loading
│   ├── tools/
│   │   ├── readSession.ts    # read_session tool
│   │   └── listSessions.ts   # list_sessions tool
│   └── utils/
│       ├── exportSession.ts  # Session export & filtering
│       ├── listSessions.ts   # Session listing logic
│       └── summarize.ts      # AI summarization
└── dist/                     # Compiled output

Architecture

Pre-Filtering Pipeline

Before sending session content to the summarizing model, the plugin applies several filters:

1. Remove Reasoning: Internal reasoning parts are stripped to save tokens
2. Per-Message Truncation: Individual tool outputs longer than perMessageTruncationLength (default: 5000 chars) are truncated. The overall session is NOT truncated—only excessively long single tool outputs are capped to prevent token bloat.
3. Smart Tool Formatting: Tool calls are formatted with input/output, skipping noisy fields like description
4. Empty Message Removal: Messages with no substantial content are skipped

Context Isolation

Sessions are always filtered by the current working directory, ensuring you only see relevant project sessions. This prevents accidentally mixing sessions from different projects.

Limitations

• No autocomplete for session IDs (would require API support from opencode to fuzzy find sessions like it does with files)

License

MIT

Acknowledgments

• Inspired by AmpCode's read threads feature, which demonstrated the value of cross-session context in AI-assisted coding
• Built for OpenCode, the open-source AI coding agent
• This repository was created using Kimi K2.5 assisted development