OpenCode Session Explorer

Browse, continue, organize, inspect, and export OpenCode sessions from the VSCode Activity Bar.

English | 简体中文

English

Overview

OpenCode Session Explorer adds an OpenCode Sessions view to VSCode. It discovers OpenCode sessions associated with the folders opened in the current window and provides common session operations without requiring manual session ID lookup.

The extension invokes the installed OpenCode CLI and does not bundle OpenCode or a native SQLite dependency.

Requirements

• VSCode 1.85.0 or later.
• An installed OpenCode CLI.
• At least one folder opened in the current VSCode window.

Verify the CLI before using the extension:

opencode --version

If opencode is not available to the VSCode extension host, configure the full executable path with opencodeSessionExplorer.cliPath.

Key Features

Browse and find sessions

• Group root sessions by workspace folder and subdirectory.
• Assign a session to the most specific folder in nested multi-root workspaces.
• Group by directory, date, agent, model, or favorite color.
• Search by title, session ID, directory, model, or agent.
• Filter by sessions updated today, this week, or this month.
• Display local timestamps and file-change statistics.

Continue and organize

• Open or fork a session in a dedicated integrated terminal.
• Rename, archive, unarchive, or permanently delete a session.
• Mark sessions as favorites with configurable star colors.
• Add multiple local tags to a session.
• Copy a session ID, resume command, or clickable VSCode Markdown link.

Inspect and export

• Show session metadata, model, usage, and change statistics.
• Open a compact message timeline.
• Extract file references and link files inside opened workspaces.
• Export Markdown or JSON, with an optional sanitized mode.
• Export every session assigned to a workspace folder.
• Export all currently visible sessions.
• Avoid batch-export filename collisions by including the session ID and never overwriting an existing file.

Maintenance and reliability

• Bulk-delete sessions older than 30, 90, or 180 days.
• Inspect empty or stale candidates before cleanup.
• Confirm empty sessions from exported message data instead of token counters alone.
• Offer archive as the default cleanup action before permanent deletion.
• Auto-refresh only while the Sessions view is visible.
• Apply CLI timeouts, output-size limits, and diagnostic logging.

Quick Start

1. Open a project folder in VSCode.
2. Select OpenCode Sessions in the Activity Bar.
3. Select a session to continue it in a terminal.
4. Right-click a session for inspect, organize, export, copy, and delete actions.
5. Use the view title actions to search, filter, regroup, refresh, export, or clean sessions.

Commands

Commands are available from the Session tree context menu or the Command Palette.

Configuration

Example:

{
  "opencodeSessionExplorer.cliPath": "C:/Tools/opencode/opencode.exe",
  "opencodeSessionExplorer.maxSessionsPerFolder": 200,
  "opencodeSessionExplorer.includeArchived": false,
  "opencodeSessionExplorer.autoRefreshInterval": 15
}

The CLI resolver checks PATH and common nvm, npm, pnpm, bun, Homebrew, mise, and asdf installation locations. In Remote SSH, WSL, or Dev Containers, OpenCode must be installed in the environment where the extension host runs.

Export and Data Safety

• Favorites and tags are extension-local metadata stored in VSCode globalState; they do not modify OpenCode session content.
• Rename and archive operations currently update OpenCode metadata through opencode db.
• Delete operations use opencode session delete.
• Export uses opencode export.
• Sanitized export uses OpenCode's native --sanitize option when available and applies an additional local redaction pass. Sanitization is best-effort; review exported content before sharing it.
• Cleanup always requires explicit selection and confirmation. Permanent deletion cannot be undone by this extension.
• Diagnostic messages are written to the OpenCode Session Explorer Output channel.

Session Links

Copy Markdown Link creates a VSCode URI such as:

vscode://ascendlin.opencode-session-explorer/session/ses_example

Opening the link resumes the session when it belongs to one of the folders currently opened in VSCode.

Troubleshooting

OpenCode CLI not found

Run opencode --version in the VSCode integrated terminal. If it works in an external terminal but not in VSCode, configure the full executable path and reload the window.

Sessions are missing

• Confirm that the session directory is the opened folder or one of its descendants.
• Enable includeArchived if the session was archived.
• Clear search and date filters.
• Increase maxSessionsPerFolder.
• Child sessions are currently excluded; the explorer lists root sessions only.

Session data fails after an OpenCode update

Session listing, rename, and archive currently depend on OpenCode database fields. Check the Output channel for the failing CLI operation and update OpenCode Session Explorer when a compatibility release is available.

Development

Run commands from opencode-session-explorer/:

npm install
npm run compile
npm test
npm run package

Use F5 in VSCode to start an Extension Development Host.

The test suite uses the Node.js built-in test runner and covers path matching, health classification, session deduplication, and export filename generation.

简体中文

插件简介

OpenCode Session Explorer 在 VSCode Activity Bar 中增加 OpenCode Sessions 视图，用于发现、继续、整理、检查和导出当前窗口所打开项目下的 OpenCode 会话，无需手动查找和复制 Session ID。

插件调用本机或远程扩展宿主环境中已安装的 OpenCode CLI，不内置 OpenCode，也不引入原生 SQLite 依赖。

环境要求

• VSCode 1.85.0 或更高版本。
• 已安装 OpenCode CLI。
• 当前 VSCode 窗口至少打开一个文件夹。

使用前可以执行：

opencode --version

如果 VSCode 扩展宿主无法找到 opencode，请通过 opencodeSessionExplorer.cliPath 配置完整的可执行文件路径。

主要功能

浏览与查找

• 按 workspace folder 和子目录展示根会话。
• 多根工作区存在父子目录时，将会话归属到路径最具体的工作区。
• 支持按目录、日期、agent、模型或收藏颜色分组。
• 支持按标题、Session ID、目录、模型或 agent 搜索。
• 支持筛选今天、本周、本月更新的会话。
• 使用用户本地时区展示时间，并显示文件修改统计。

继续与整理

• 在独立集成终端中打开或 Fork 会话。
• 支持重命名、归档、取消归档和永久删除。
• 支持彩色收藏星标和多个本地标签。
• 支持复制 Session ID、恢复命令和可点击的 VSCode Markdown 链接。

检查与导出

• 展示会话元数据、模型、用量和修改统计。
• 打开精简的消息时间线。
• 提取文件引用，并链接当前工作区内的文件。
• 导出 Markdown、JSON，以及对应的脱敏格式。
• 导出指定 workspace folder 下的全部会话。
• 导出当前界面中可见的全部会话。
• 批量导出文件名包含 Session ID，且不会覆盖已有文件。

清理与可靠性

• 批量删除 30、90 或 180 天前的会话。
• 检查空会话或过期会话候选项。
• 使用实际导出消息数确认空会话，不再仅依赖 token 统计。
• 健康清理默认提供归档操作，永久删除需要再次确认。
• 仅在 Sessions 视图可见时执行自动刷新。
• CLI 调用包含超时、输出大小限制和诊断日志。

快速开始

1. 在 VSCode 中打开项目文件夹。
2. 点击 Activity Bar 中的 OpenCode Sessions。
3. 点击某个会话，在新终端中继续该会话。
4. 右键会话执行检查、整理、复制、导出或删除操作。
5. 使用视图标题栏按钮执行搜索、筛选、分组、刷新、批量导出或清理。

命令分类

配置项

配置示例：

{
  "opencodeSessionExplorer.cliPath": "C:/Tools/opencode/opencode.exe",
  "opencodeSessionExplorer.maxSessionsPerFolder": 200,
  "opencodeSessionExplorer.includeArchived": false,
  "opencodeSessionExplorer.autoRefreshInterval": 15
}

插件会检查 PATH 以及常见的 nvm、npm、pnpm、bun、Homebrew、mise 和 asdf 安装目录。使用 Remote SSH、WSL 或 Dev Containers 时，需要在扩展宿主实际运行的环境中安装 OpenCode。

数据与安全说明

• 收藏和标签保存在 VSCode globalState 中，不会修改 OpenCode 会话内容。
• 重命名和归档当前通过 opencode db 更新 OpenCode 元数据。
• 删除使用 opencode session delete。
• 导出使用 opencode export。
• 脱敏导出会优先使用 OpenCode 原生 --sanitize，并额外执行本地敏感字段清理。脱敏属于尽力处理，分享前仍应人工检查。
• 清理操作必须先选择候选项并确认；永久删除无法由本插件恢复。
• CLI 诊断信息写入 OpenCode Session Explorer Output Channel。

Session 链接

Copy Markdown Link 会生成类似下面的 VSCode URI：

vscode://ascendlin.opencode-session-explorer/session/ses_example

当链接对应的会话属于当前 VSCode 已打开的文件夹时，打开链接即可继续该会话。

常见问题

找不到 OpenCode CLI

先在 VSCode 集成终端中执行 opencode --version。如果外部终端可用、VSCode 中不可用，请配置完整可执行文件路径并重新加载窗口。

会话没有显示

• 确认会话目录是当前打开文件夹或其子目录。
• 如果会话已归档，请启用 includeArchived。
• 清除搜索条件和日期筛选。
• 增大 maxSessionsPerFolder。
• 当前版本只展示根会话，暂不展示子会话。

OpenCode 升级后读取失败

会话列表、重命名和归档目前仍依赖 OpenCode 数据库字段。请先查看 OpenCode Session Explorer Output Channel 中失败的 CLI 操作，并升级到对应的插件兼容版本。

开发与验证

在 opencode-session-explorer/ 目录执行：

npm install
npm run compile
npm test
npm run package

在 VSCode 中按 F5 可启动 Extension Development Host。

测试使用 Node.js 内置测试运行器，覆盖路径归属、健康状态判定、会话去重和导出文件名生成。