From 777cefa47d4254d4980fc86ab71a22d80270275a Mon Sep 17 00:00:00 2001 From: HeavyBunny19C Date: Fri, 20 Mar 2026 18:46:18 +0800 Subject: [PATCH 1/2] docs: add installation tutorials for humans and AI agents (zh) --- README.md | 283 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 246 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index c2373e2..2465188 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@

✨ oh-my-opensession ✨

- 🖥️ 终端风格的 OpenCode 会话浏览器与管理工具 + 🖥️ 你和 AI 结对编程的「回忆录」—— 终端风格的 OpenCode 会话浏览器

@@ -19,12 +19,29 @@ Version

+

+ 每一次和 AI 的对话都值得被好好收藏 📖
+ 就像翻看和老朋友的聊天记录，只不过这个朋友会写代码 🤖 +

+ +--- + +## 🤔 这是什么？ + +你有没有想过—— + +> 「上周那个 bug 我是怎么让 Claude 帮我修的来着？」 +> 「上个月写的那个正则表达式，AI 给的方案贼优雅，在哪呢？」 +> 「我到底烧了多少 token？💸」 + +**oh-my-opensession** 就是来解决这些问题的。它是一个本地 Web 应用，帮你浏览、搜索、管理所有 OpenCode 会话——带暗色模式、终端美学、还有一点点极客浪漫 🌙 + --- ## 🎬 预览
-🏠 首页仪表盘 — 终端风格导航卡片 +🏠 首页仪表盘 — 终端风格，程序员的浪漫

Dashboard @@ -32,7 +49,7 @@

-💬 会话详情 — 消息浏览 & 任务清单 +💬 会话详情 — 和 AI 的每一次「深夜长谈」

Session Detail @@ -43,7 +60,7 @@

-📊 Token 统计 — 模型分布 & 趋势图表 +📊 Token 统计 — 看看你的钱包还好吗

Stats @@ -51,7 +68,7 @@

-🗂️ 批量管理 — 多选操作 & 时间筛选 +🗂️ 批量管理 — 断舍离，从会话开始

Batch Management @@ -62,46 +79,70 @@ ## 🚀 快速开始 +### 方式一：从源码运行（推荐） + ```bash -npx oh-my-opensession +git clone https://github.com/HeavyBunny19C/oh-my-opensession.git +cd oh-my-opensession +npm start +``` + +> 💡 打开 `http://localhost:3456`，开始考古你的 AI 编程之旅！ + +想自动弹浏览器？ + +```bash +npm run dev # 等于 npm start + --open ``` -> 💡 在 `http://localhost:3456` 打开 Web 界面，即刻开始浏览你的 AI 编程会话！ +### 方式二：npx / 全局安装（npm 发布后可用） -## 📦 安装 +> ⚠️ **注意**：npm 包尚未发布，以下命令暂时无法使用。发布后即可一键启动： ```bash +# 临时运行（发布后可用） +npx oh-my-opensession + +# 全局安装（发布后可用） npm install -g oh-my-opensession -oh-my-opensession +oh-my-opensession --open ``` --- -## ✨ 功能特性 - -| 功能 | 描述 | -|:---:|:---| -| 🌙 | **暗色模式** — 自动检测系统偏好，一键切换明暗主题 | -| 🖥️ | **终端美学** — 代码块风格仪表盘卡片，微妙网格背景 | -| 📋 | **会话浏览** — 搜索、筛选、无限滚动浏览所有会话 | -| ⭐ | **收藏管理** — 收藏/取消收藏，快速定位重要会话 | -| ✏️ | **自定义标题** — 给会话起个好记的名字 | -| 🗑️ | **软删除** — 误删不怕，回收站随时恢复 | -| 📤 | **导出** — 一键导出为 Markdown 或 JSON | -| 📊 | **Token 统计** — 消耗趋势、模型分布、每日会话数 | -| 🔔 | **Toast 通知** — 所有操作即时视觉反馈 | -| 🗂️ | **批量操作** — 多选收藏、删除，效率翻倍 | -| 🌐 | **中英双语** — `--lang zh\|en` 自由切换 | -| 🔒 | **只读安全** — 绝不写入 OpenCode 数据库 | -| 📦 | **零依赖** — 只需 Node.js，开箱即用 | +## ✨ 能干啥？ + +| | 功能 | 一句话说明 | +|:---:|:---|:---| +| 🌙 | **暗色模式** | 自动跟随系统，深夜 coding 不刺眼 | +| 🖥️ | **终端美学** | 代码块卡片 + 网格背景，看着就想写代码 | +| 🔍 | **搜索 & 筛选** | 按关键词、时间范围快速定位，告别大海捞针 | +| ♾️ | **无限滚动** | 丝滑加载，不用翻页翻到手酸 | +| ⭐ | **收藏** | 给重要会话打个星，下次一秒找到 | +| ✏️ | **重命名** | 「untitled-session-47」？不存在的 | +| 🗑️ | **软删除** | 手滑删错？回收站救你 | +| 📤 | **导出** | Markdown / JSON 一键导出，写博客素材有了 | +| 📊 | **Token 统计** | 消耗趋势、模型分布，钱花哪了一目了然 | +| 🔔 | **Toast 通知** | 操作有反馈，不再对着屏幕发呆 | +| 🗂️ | **批量操作** | 多选收藏/删除，效率拉满 | +| 🌐 | **中英双语** | `--lang zh` 切中文，`--lang en` 切英文 | +| 🔒 | **只读安全** | 绝不碰你的 OpenCode 数据库，放心用 | +| 📦 | **零依赖** | 只要 Node.js，没有 node_modules 黑洞 | --- ## 🛠️ 环境要求 -- **Node.js** >= 22.5.0（使用内置 `node:sqlite`） -- 已安装 [OpenCode](https://opencode.ai) 并有会话数据 -- 支持平台：macOS、Windows x64 +- **Node.js** >= 22.5.0（用了内置的 `node:sqlite`，所以版本要求高一丢丢） +- 装了 [OpenCode](https://opencode.ai) 并且有会话数据（没数据也能跑，就是空空如也 😅） + +| 平台 | 架构 | 状态 | +|:---|:---|:---:| +| 🍎 macOS | x64 / Apple Silicon (arm64) | ✅ | +| 🪟 Windows | x64 / arm64 | ✅ | +| 🐧 Linux | x64 / arm64 | ✅ | + +> 纯 JS，零 native 依赖，有 Node.js 就能跑 🏃 ## ⚙️ 命令行选项 @@ -109,8 +150,8 @@ oh-my-opensession 选项 说明 默认值 --port <端口号> 服务端口 3456 --db <路径> opencode.db 路径 自动检测 ---lang 界面语言 自动检测系统 LANG ---open 启动后自动打开浏览器 false +--lang 界面语言 自动检测 +--open 启动后自动弹浏览器 false -h, --help 显示帮助 — ``` @@ -118,17 +159,36 @@ oh-my-opensession | 变量 | 说明 | |:---|:---| -| `PORT` | 服务端口（被 `--port` 覆盖） | -| `SESSION_VIEWER_DB_PATH` | opencode.db 路径（被 `--db` 覆盖） | +| `PORT` | 服务端口（`--port` 优先） | +| `SESSION_VIEWER_DB_PATH` | opencode.db 路径（`--db` 优先） | | `OH_MY_OPENSESSION_META_PATH` | 元数据库路径 | --- ## 🧠 工作原理 -oh-my-opensession 以 **只读模式** 读取 OpenCode 的 SQLite 数据库来展示会话，绝不写入你的 OpenCode 数据。 +``` +┌─────────────────────────────────────────┐ +│ OpenCode DB (只读) │ +│ └── session / message / part / todo │ +└──────────────┬──────────────────────────┘ + │ SELECT（绝不 INSERT/UPDATE） + ▼ +┌─────────────────────────────────────────┐ +│ oh-my-opensession │ +│ ├── 服务端渲染 HTML │ +│ ├── 无限滚动 API │ +│ └── 管理操作 → meta.db (独立存储) │ +└──────────────┬──────────────────────────┘ + │ http://localhost:3456 + ▼ +┌─────────────────────────────────────────┐ +│ 🌙 你的浏览器 │ +│ └── 暗色模式 / 终端美学 / Toast 通知 │ +└─────────────────────────────────────────┘ +``` -管理元数据（收藏、重命名、软删除）存储在独立的 `meta.db` 中： +你的 OpenCode 数据 **绝对安全**——我们只看不摸。收藏、重命名、删除等操作存在独立的 `meta.db` 里： ``` macOS: ~/.config/oh-my-opensession/meta.db @@ -137,9 +197,158 @@ Windows: %APPDATA%\oh-my-opensession\meta.db --- +## 📖 给人类的安装教程 + +> 一步步来，不急。五分钟搞定。 + +### Step 1: 检查 Node.js 版本 + +```bash +node --version +# 需要 v22.5.0 或更高版本 +``` + +**版本不够？** 推荐用 [nvm](https://github.com/nvm-sh/nvm) 升级： + +```bash +# 安装 nvm（如果还没装） +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash +source ~/.bashrc # 或 source ~/.zshrc + +# 安装并使用 Node.js 22 +nvm install 22 +nvm use 22 +node --version # 确认 >= 22.5.0 +``` + +> Windows 用户可以用 [nvm-windows](https://github.com/coreybutler/nvm-windows) 或直接从 [Node.js 官网](https://nodejs.org/) 下载 v22+。 + +### Step 2: 确认你有 OpenCode 会话数据 + +```bash +# macOS / Linux +ls ~/.local/share/opencode/opencode.db + +# Windows (PowerShell) +dir "$env:LOCALAPPDATA\opencode\opencode.db" +``` + +如果文件不存在也没关系——程序能跑，只是看不到数据。装了 [OpenCode](https://opencode.ai) 并用过之后就会自动生成。 + +### Step 3: 克隆并运行 + +```bash +git clone https://github.com/HeavyBunny19C/oh-my-opensession.git +cd oh-my-opensession +npm start +``` + +看到类似这样的输出就是成功了： + +``` +oh-my-opensession running at http://localhost:3456 +Language: en +DB: /Users/xxx/.local/share/opencode/opencode.db +42 sessions, 1337 messages. +``` + +打开浏览器访问 `http://localhost:3456` 即可。 + +### Step 4: 可选 - 自动打开浏览器 + +```bash +npm run dev +``` + +### 常见问题 + +| 问题 | 解决方法 | +|:---|:---| +| `Error: Cannot find module 'node:sqlite'` | Node.js 版本低于 22.5.0，请升级 | +| `Error: listen EADDRINUSE :::3456` | 端口被占用，用 `node bin/cli.mjs --port 3457` 换个端口 | +| 启动后显示 `0 sessions` | OpenCode 没有会话数据，或数据库路径不对。用 `--db /path/to/opencode.db` 指定路径 | +| `SQLITE_CANTOPEN` | 数据库文件不存在或无读取权限，检查路径和文件权限 | + +--- + +## 🤖 给 AI 的安装教程 + +> 以下内容为结构化指令，供 AI 编程助手（Claude, ChatGPT, Cursor, Copilot 等）在帮助用户安装时参考。 + +

+展开 AI 安装指令 + +### CONTEXT + +- **Project**: oh-my-opensession — 本地 Web 应用，浏览和管理 OpenCode 会话 +- **Runtime**: Node.js >= 22.5.0（依赖内置 `node:sqlite` 模块） +- **Dependencies**: 零，无需 `npm install` +- **Source**: `https://github.com/HeavyBunny19C/oh-my-opensession.git` +- **npm status**: 尚未发布到 npm，`npx oh-my-opensession` 暂不可用 +- **Default port**: 3456 +- **OpenCode DB location**: + - macOS / Linux: `~/.local/share/opencode/opencode.db`（遵循 XDG，受 `$XDG_DATA_HOME` 影响） + - Windows: `%LOCALAPPDATA%\opencode\opencode.db` + +### INSTALLATION STEPS + +``` +STEP 1: Verify Node.js version + RUN: node --version + EXPECT: v22.5.0 or higher + ON FAILURE: Guide user to install Node.js 22+ via nvm, fnm, or nodejs.org + ERROR PATTERN: "Cannot find module 'node:sqlite'" → Node.js version too old + +STEP 2: Clone repository + RUN: git clone https://github.com/HeavyBunny19C/oh-my-opensession.git + RUN: cd oh-my-opensession + +STEP 3: Start server + RUN: npm start + OR: node bin/cli.mjs [options] + EXPECT OUTPUT: "oh-my-opensession running at http://localhost:3456" + ON SUCCESS: Open http://localhost:3456 in browser + +STEP 4 (optional): Custom options + RUN: node bin/cli.mjs --port --db --lang --open +``` + +### ERROR HANDLING + +``` +ERROR: "listen EADDRINUSE :::3456" + CAUSE: Port 3456 already in use + FIX: node bin/cli.mjs --port 3457 + +ERROR: "Cannot find module 'node:sqlite'" + CAUSE: Node.js < 22.5.0 + FIX: Upgrade Node.js to 22.5.0+ + +ERROR: "SQLITE_CANTOPEN" + CAUSE: opencode.db not found at default path + FIX: node bin/cli.mjs --db /actual/path/to/opencode.db + FIND DB: find ~ -name "opencode.db" -type f 2>/dev/null + +ERROR: "0 sessions, 0 messages" + CAUSE: OpenCode not yet used, or wrong DB path + FIX: Use OpenCode first, or specify correct --db path +``` + +### KEY FACTS FOR AI AGENTS + +- **Read-only**: 绝不修改 OpenCode 数据库，只做 SELECT 查询 +- **Meta storage**: 收藏/重命名/删除等操作存储在独立的 `meta.db`（macOS: `~/.config/oh-my-opensession/meta.db`） +- **Zero install**: 克隆即跑，不需要 `npm install`（零依赖项目） +- **ESM only**: 项目使用 ES Modules（`"type": "module"`），入口是 `bin/cli.mjs` +- **No build step**: 无编译、无打包，纯原生 JavaScript + +
+ +--- + ## 💖 捐赠 -如果这个项目对你有帮助，欢迎请我喝杯蜜雪 :) +如果这个项目让你会心一笑，欢迎请我喝杯蜜雪冰城 🍦

微信支付 @@ -154,4 +363,4 @@ Windows: %APPDATA%\oh-my-opensession\meta.db ## 📄 许可证 -MIT +MIT — 随便用，开心就好 🎉 From 98d4b39fb712b0c0104c0bc0ae3b92b5d8ffd5ff Mon Sep 17 00:00:00 2001 From: HeavyBunny19C Date: Fri, 20 Mar 2026 18:46:27 +0800 Subject: [PATCH 2/2] docs: add installation tutorials for humans and AI agents (en) --- README.en.md | 375 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 330 insertions(+), 45 deletions(-) diff --git a/README.en.md b/README.en.md index 9cdde3a..8c20dd6 100644 --- a/README.en.md +++ b/README.en.md @@ -1,71 +1,354 @@ -# oh-my-opensession +

+ oh-my-opensession +

+ +

✨ oh-my-opensession ✨

+ +

+ 🖥️ Your AI pair-programming "memoir" — a terminal-styled OpenCode session browser +

+ +

+ English · 中文 +

+ +

+ Node.js + Zero Dependencies + MIT License + Version +

+ +

+ Every conversation with AI deserves to be remembered 📖
+ Like scrolling through old chats with a friend — except this one writes code 🤖 +

+ +--- + +## 🤔 What is this? + +Ever caught yourself thinking— + +> "How did I get Claude to fix that bug last week?" +> "That regex AI wrote was *chef's kiss* — where did it go?" +> "How many tokens have I burned through? 💸" + +**oh-my-opensession** is here to help. It's a local web app that lets you browse, search, and manage all your OpenCode sessions — with dark mode, terminal aesthetics, and a sprinkle of geek romance 🌙 + +--- + +## 🎬 Preview + +
+🏠 Dashboard — terminal vibes, developer romance +
+

+ Dashboard +

+
+ +
+💬 Session Detail — every late-night chat with AI +
+

+ Session Detail +

+

+ Session Chat +

+
-**[English](./README.en.md)** | **[中文](./README.md)** +
+📊 Token Stats — how's your wallet doing? +
+

+ Stats +

+
-A web-based session viewer and manager for [OpenCode](https://opencode.ai) — browse, search, star, rename, delete, and export your AI coding sessions. +
+🗂️ Batch Management — Marie Kondo your sessions +
+

+ Batch Management +

+
-## Features +--- -- 📋 Browse and search all OpenCode sessions -- ⭐ Star/unstar sessions for quick access -- ✏️ Rename sessions with custom titles -- 🗑️ Soft delete with trash & restore -- 📤 Export sessions as Markdown or JSON -- 📊 Token usage statistics and charts -- 🌐 English & Chinese UI (`--lang en|zh`) -- 🔒 Read-only access to OpenCode DB — your data is safe -- 📦 Zero dependencies — just Node.js +## 🚀 Quick Start -## Quick Start +### Option 1: Run from Source (Recommended) ```bash -npx oh-my-opensession +git clone https://github.com/HeavyBunny19C/oh-my-opensession.git +cd oh-my-opensession +npm start ``` -Opens a web UI at `http://localhost:3456`. +> 💡 Open `http://localhost:3456` and start archaeologizing your AI coding journey! -## Installation +Want auto-open browser? ```bash +npm run dev # same as npm start + --open +``` + +### Option 2: npx / Global Install (after npm publish) + +> ⚠️ **Note**: The npm package is not yet published. The commands below will work once it's live: + +```bash +# One-off run (available after publish) +npx oh-my-opensession + +# Global install (available after publish) npm install -g oh-my-opensession -oh-my-opensession +oh-my-opensession --open ``` -## Requirements +--- + +## ✨ What can it do? + +| | Feature | TL;DR | +|:---:|:---|:---| +| 🌙 | **Dark Mode** | Auto-follows system preference. Late-night coding without the eye burn | +| 🖥️ | **Terminal Aesthetic** | Code-block cards + grid background. Makes you *want* to code | +| 🔍 | **Search & Filter** | By keyword, time range. No more needle-in-a-haystack | +| ♾️ | **Infinite Scroll** | Silky smooth loading. No more page-clicking carpal tunnel | +| ⭐ | **Star** | Bookmark the good stuff. Find it in one second next time | +| ✏️ | **Rename** | "untitled-session-47"? Not on our watch | +| 🗑️ | **Soft Delete** | Fat-fingered a delete? Trash has your back | +| 📤 | **Export** | Markdown / JSON one-click export. Blog material: acquired | +| 📊 | **Token Stats** | Usage trends, model distribution. See where the money went | +| 🔔 | **Toast Notifications** | Every action gets feedback. No more staring at the screen | +| 🗂️ | **Batch Operations** | Multi-select star/delete. Efficiency: maxed out | +| 🌐 | **Bilingual** | `--lang en` for English, `--lang zh` for Chinese | +| 🔒 | **Read-Only Safe** | Never touches your OpenCode DB. Pinky promise | +| 📦 | **Zero Dependencies** | Just Node.js. No node_modules black hole | -- Node.js >= 22.5.0 (uses built-in `node:sqlite`) -- An existing [OpenCode](https://opencode.ai) installation with session data -- Supported platforms: macOS, Windows x64 +--- -## Options +## 🛠️ Requirements -| Option | Description | Default | -|--------|-------------|---------| -| `--port ` | Server port | `3456` | -| `--db ` | Path to `opencode.db` | macOS: `~/.local/share/opencode/opencode.db`
Windows: `%LOCALAPPDATA%\opencode\opencode.db` | -| `--lang ` | UI language | Auto-detect from `LANG` | -| `--open` | Open browser on start | `false` | -| `-h, --help` | Show help | — | +- **Node.js** >= 22.5.0 (uses built-in `node:sqlite`, hence the version bump) +- [OpenCode](https://opencode.ai) installed with session data (runs without data too, just... empty 😅) -## Environment Variables +| Platform | Architecture | Status | +|:---|:---|:---:| +| 🍎 macOS | x64 / Apple Silicon (arm64) | ✅ | +| 🪟 Windows | x64 / arm64 | ✅ | +| 🐧 Linux | x64 / arm64 | ✅ | + +> Pure JS, zero native dependencies — if Node.js runs, we run 🏃 + +## ⚙️ CLI Options + +``` +Option Description Default +--port Server port 3456 +--db Path to opencode.db Auto-detect +--lang UI language Auto-detect +--open Open browser on start false +-h, --help Show help — +``` + +## 🔧 Environment Variables | Variable | Description | -|----------|-------------| -| `PORT` | Server port (overridden by `--port`) | -| `SESSION_VIEWER_DB_PATH` | Path to `opencode.db` (overridden by `--db`) | -| `OH_MY_OPENSESSION_META_PATH` | Path to metadata DB | +|:---|:---| +| `PORT` | Server port (`--port` takes priority) | +| `SESSION_VIEWER_DB_PATH` | Path to opencode.db (`--db` takes priority) | +| `OH_MY_OPENSESSION_META_PATH` | Metadata DB path | + +--- -## How It Works +## 🧠 How It Works + +``` +┌─────────────────────────────────────────┐ +│ OpenCode DB (read-only) │ +│ └── session / message / part / todo │ +└──────────────┬──────────────────────────┘ + │ SELECT (never INSERT/UPDATE) + ▼ +┌─────────────────────────────────────────┐ +│ oh-my-opensession │ +│ ├── Server-side rendered HTML │ +│ ├── Infinite scroll API │ +│ └── Management ops → meta.db (separate)│ +└──────────────┬──────────────────────────┘ + │ http://localhost:3456 + ▼ +┌─────────────────────────────────────────┐ +│ 🌙 Your Browser │ +│ └── Dark mode / Terminal UI / Toasts │ +└─────────────────────────────────────────┘ +``` + +Your OpenCode data is **absolutely safe** — we look but don't touch. Stars, renames, and deletes live in a separate `meta.db`: + +``` +macOS: ~/.config/oh-my-opensession/meta.db +Windows: %APPDATA%\oh-my-opensession\meta.db +``` -oh-my-opensession reads your OpenCode SQLite database in **read-only mode** to display sessions. It never writes to your OpenCode data. +--- -Management metadata (stars, renames, soft deletes) is stored in a separate `meta.db`: -- macOS: `~/.config/oh-my-opensession/meta.db` -- Windows: `%APPDATA%\oh-my-opensession\meta.db` +## 📖 Installation Guide for Humans -## Donate +> Step by step. No rush. Five minutes tops. -If this project helps you, consider buying me a Mixue :) +### Step 1: Check Node.js Version + +```bash +node --version +# Must be v22.5.0 or higher +``` + +**Too old?** Use [nvm](https://github.com/nvm-sh/nvm) to upgrade: + +```bash +# Install nvm (if not already installed) +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash +source ~/.bashrc # or source ~/.zshrc + +# Install and use Node.js 22 +nvm install 22 +nvm use 22 +node --version # confirm >= 22.5.0 +``` + +> Windows users: try [nvm-windows](https://github.com/coreybutler/nvm-windows) or download v22+ from [nodejs.org](https://nodejs.org/). + +### Step 2: Confirm OpenCode Session Data Exists + +```bash +# macOS / Linux +ls ~/.local/share/opencode/opencode.db + +# Windows (PowerShell) +dir "$env:LOCALAPPDATA\opencode\opencode.db" +``` + +If the file doesn't exist, that's OK — the app runs fine, just with no data. Install [OpenCode](https://opencode.ai) and use it, the DB will be created automatically. + +### Step 3: Clone and Run + +```bash +git clone https://github.com/HeavyBunny19C/oh-my-opensession.git +cd oh-my-opensession +npm start +``` + +You should see something like: + +``` +oh-my-opensession running at http://localhost:3456 +Language: en +DB: /Users/xxx/.local/share/opencode/opencode.db +42 sessions, 1337 messages. +``` + +Open `http://localhost:3456` in your browser. + +### Step 4: Optional - Auto-open Browser + +```bash +npm run dev +``` + +### Troubleshooting + +| Problem | Solution | +|:---|:---| +| `Error: Cannot find module 'node:sqlite'` | Node.js version is below 22.5.0 — please upgrade | +| `Error: listen EADDRINUSE :::3456` | Port 3456 is taken. Use `node bin/cli.mjs --port 3457` | +| Starts with `0 sessions` | No OpenCode session data, or wrong DB path. Use `--db /path/to/opencode.db` | +| `SQLITE_CANTOPEN` | DB file not found or no read permission — check the path and permissions | + +--- + +## 🤖 Installation Guide for AI Agents + +> Structured instructions for AI coding assistants (Claude, ChatGPT, Cursor, Copilot, etc.) to help users install this project. + +
+Expand AI Installation Instructions + +### CONTEXT + +- **Project**: oh-my-opensession — local web app for browsing and managing OpenCode sessions +- **Runtime**: Node.js >= 22.5.0 (depends on built-in `node:sqlite` module) +- **Dependencies**: Zero — no `npm install` needed +- **Source**: `https://github.com/HeavyBunny19C/oh-my-opensession.git` +- **npm status**: NOT yet published to npm. `npx oh-my-opensession` does NOT work. +- **Default port**: 3456 +- **OpenCode DB location**: + - macOS / Linux: `~/.local/share/opencode/opencode.db` (XDG-compliant, respects `$XDG_DATA_HOME`) + - Windows: `%LOCALAPPDATA%\opencode\opencode.db` + +### INSTALLATION STEPS + +``` +STEP 1: Verify Node.js version + RUN: node --version + EXPECT: v22.5.0 or higher + ON FAILURE: Guide user to install Node.js 22+ via nvm, fnm, or nodejs.org + ERROR PATTERN: "Cannot find module 'node:sqlite'" → Node.js version too old + +STEP 2: Clone repository + RUN: git clone https://github.com/HeavyBunny19C/oh-my-opensession.git + RUN: cd oh-my-opensession + +STEP 3: Start server + RUN: npm start + OR: node bin/cli.mjs [options] + EXPECT OUTPUT: "oh-my-opensession running at http://localhost:3456" + ON SUCCESS: Open http://localhost:3456 in browser + +STEP 4 (optional): Custom options + RUN: node bin/cli.mjs --port --db --lang --open +``` + +### ERROR HANDLING + +``` +ERROR: "listen EADDRINUSE :::3456" + CAUSE: Port 3456 already in use + FIX: node bin/cli.mjs --port 3457 + +ERROR: "Cannot find module 'node:sqlite'" + CAUSE: Node.js < 22.5.0 + FIX: Upgrade Node.js to 22.5.0+ + +ERROR: "SQLITE_CANTOPEN" + CAUSE: opencode.db not found at default path + FIX: node bin/cli.mjs --db /actual/path/to/opencode.db + FIND DB: find ~ -name "opencode.db" -type f 2>/dev/null + +ERROR: "0 sessions, 0 messages" + CAUSE: OpenCode not yet used, or wrong DB path + FIX: Use OpenCode first, or specify correct --db path +``` + +### KEY FACTS FOR AI AGENTS + +- **Read-only**: Never modifies the OpenCode database — SELECT queries only +- **Meta storage**: Stars/renames/deletes are stored in a separate `meta.db` (macOS: `~/.config/oh-my-opensession/meta.db`) +- **Zero install**: Clone and run — no `npm install` required (zero-dependency project) +- **ESM only**: Uses ES Modules (`"type": "module"`), entry point is `bin/cli.mjs` +- **No build step**: No compilation, no bundling — plain JavaScript + +
+ +--- + +## 💖 Donate + +If this project made you smile, consider buying me a Mixue ice cream 🍦

WeChat Pay @@ -73,9 +356,11 @@ If this project helps you, consider buying me a Mixue :) Alipay

- WeChat Pay                                  Alipay + WeChat Pay                                      Alipay

-## License +--- + +## 📄 License -MIT +MIT — use it, have fun 🎉