🚀 OpenCode Starter

Your homepage for OpenCode. All your sessions, at a glance.
OpenCode 的主页。你的所有会话，一目了然。

npm install -g opencode-starter  →  opencode-starter

---

English

The Problem

OpenCode keeps every session in a SQLite database under ~/.local/share/opencode/opencode.db. To get back into a past conversation you need to remember the session id (ses_2552b058effe…) and type:

opencode -s ses_2552b058effeRkC50L1NRrLtv -c

Good luck remembering the right one out of hundreds.

The Solution

opencode-starter

A beautiful split-pane TUI with a Tokyo Night palette. Left panel: every session with project, time, and topic. Right panel: full metadata and a preview of the conversation. Not session ids — your actual words.

🔍 Search — The Killer Feature

Press / and start typing. That's it. No Enter needed.

Searches across everything — project names, titles, conversation content, session ids. Results update as you type, ↑↓ to navigate instantly.

• auth → all auth-related sessions
• refactor → that cleanup from last week
• my-app fix → bug fixes in a specific project

No modes. No confirmation. Just type and go.

Features

	Feature	Description
🎨	Minimal UI	High-contrast mono / grayscale, follows your terminal background — same restrained vibe as opencode itself
✨	New Session	Launch a fresh OpenCode session in one keystroke
🔍	Instant Search	Live fuzzy search across project names, titles and message content
📂	Project Filter	Press p to filter by project
⚡	One-Key Resume	Arrow, Enter, you're back in the conversation (opencode -s … -c)
🔓	Permission Mode	Press m to toggle ask / allow / deny — allow = no more prompts
📋	Session Preview	Full metadata + conversation history in the right panel
🔀	Sort Modes	Sort by time, message count, or project
📎	Copy ID	Press c to copy the session id
✏️	Rename Sessions	Press r to give a session a custom title (CJK supported)
🗑️	Delete Sessions	Press x to remove a session from the database (cascades messages + parts)
⌨️	Vim Keybindings	j/k navigate, g/G jump to top/bottom
🔐	100% Local	No network, no telemetry — reads your local SQLite database directly

Install

npm install -g opencode-starter

Or from source:

git clone https://github.com/Bojun-Vvibe/opencode-starter.git
cd opencode-starter
npm install
npm link

Then run:

opencode-starter

CLI Options

opencode-starter             # Launch interactive TUI
opencode-starter --list [N]  # Print latest N sessions (default: 30)
opencode-starter --version   # Show version
opencode-starter --update    # Update to the latest version
opencode-starter --help      # Show help

Keyboard Shortcuts

Key	Action
↑ ↓ / j k	Navigate sessions
Enter	Start new / resume selected session
n	New session
/	Search
Backspace	Edit search, auto-exit when empty
Esc	Clear filter
p	Filter by project
s	Cycle sort mode (time / messages / project)
c	Copy session ID
r	Rename session (custom title)
x / Delete	Delete session
g / G	Jump to top / bottom
Ctrl-D / Ctrl-U	Page down / up
q / Ctrl-C	Quit

How It Works

Reads OpenCode's SQLite database (~/.local/share/opencode/opencode.db) directly via better-sqlite3. Renders metadata + the first user prompt of each session as a list. On resume, spawns opencode -s <id> -c in the session's original working directory.

User-defined custom titles are stored separately in ~/.opencode-starter/meta.json so the OpenCode database is never mutated by a rename.

You can override the data directory with the OPENCODE_DATA_DIR environment variable.

Requirements

• Node.js ≥ 18
• OpenCode — install from opencode.ai

Development

npm install
npm test          # 46 unit / integration tests
npm start         # Launch the TUI

License

MIT

---

中文

痛点

OpenCode 把每一个会话都存进 ~/.local/share/opencode/opencode.db 这一个 SQLite 数据库里。想回到上周的某个会话？你需要记住 session id 然后敲：

opencode -s ses_2552b058effeRkC50L1NRrLtv -c

几百个 session，谁也记不住。

解决方案

OpenCode Starter 是一个精美的终端可视化工具，让你能像浏览网页一样浏览所有 OpenCode 历史会话。它是你的 OpenCode 主页 —— 每次打开终端， opencode-starter 一敲，所有 session 一目了然。

opencode-starter

精美的分屏 UI，Tokyo Night 配色。左侧列表一目了然，右侧实时预览对话详情。 不是 UUID，是你真正说过的话。

🔍 搜索 — 杀手级功能

按 / 开始输入，就这么简单。无需按回车。

跨项目名、自定义标题、对话内容、session id 全文实时搜索。 输入即过滤，↑↓ 直接导航结果。

• auth → 所有认证相关的对话
• refactor → 上周的代码重构
• my-app fix → 某个项目的 bug 修复

不需要管理模式，不需要确认。输入即搜，方向键即走。

核心能力

	功能	说明
🎨	精美 TUI	Tokyo Night 配色，分屏布局，终端里的 App
✨	一键新建	列表顶部直接新建对话
🔍	即时搜索	/ 全文搜索，无需回车
📂	项目过滤	p 按项目筛选
⚡	秒级恢复	选中 → Enter → opencode -s … -c 回到对话
📋	对话预览	右侧面板展示完整元数据和对话历史
🔀	多种排序	时间 / 消息数 / 项目
📎	复制 ID	c 一键复制到剪贴板
✏️	重命名会话	r 给会话起个自定义标题，支持中文输入
🗑️	删除会话	x 删除不需要的会话（消息和 part 一并清理）
⌨️	Vim 快捷键	j/k 上下，g/G 跳顶/底
🔐	完全本地	不联网，不上传，不追踪 — 直接读本地 SQLite

安装

npm install -g opencode-starter

或者从源码安装：

git clone https://github.com/Bojun-Vvibe/opencode-starter.git
cd opencode-starter
npm install
npm link

然后运行 opencode-starter，就这么简单。

CLI 参数

opencode-starter             # 启动交互式 TUI
opencode-starter --list [N]  # 打印最近 N 个会话（默认 30）
opencode-starter --version   # 显示版本号
opencode-starter --update    # 检查并更新到最新版本
opencode-starter --help      # 显示帮助信息

快捷键

按键	功能
↑ ↓ / j k	上下导航
Enter	新建 / 恢复对话
n	直接新建
/	搜索
Backspace	删除搜索字符，删空自动退出
Esc	清空搜索
p	按项目过滤
s	切换排序（时间/消息数/项目）
c	复制 Session ID
r	重命名会话
x / Delete	删除会话
g / G	跳到顶 / 底
Ctrl-D / Ctrl-U	翻页
q / Ctrl-C	退出

原理

直接读取 OpenCode 的 SQLite 数据库 (~/.local/share/opencode/opencode.db)，无需任何 IPC、API 或网络调用。 恢复会话时在原始工作目录里 spawn opencode -s <id> -c。

自定义标题保存在 ~/.opencode-starter/meta.json，OpenCode 自身的数据库 不会 被本工具修改。

需要时可以用 OPENCODE_DATA_DIR 环境变量覆盖数据目录。

环境要求

• Node.js ≥ 18
• OpenCode — 从 opencode.ai 安装

---

_{Built with 💜 by Bojun — powered by OpenCode itself}