https://github.com/tiezbro/opencode-session-history
Bring hidden OpenCode session history back into view and seamlessly continue work in any historical session.
https://github.com/tiezbro/opencode-session-history
cli developer-tools opencode productivity python session-history sessions tmux
Last synced: about 2 months ago
JSON representation
Bring hidden OpenCode session history back into view and seamlessly continue work in any historical session.
- Host: GitHub
- URL: https://github.com/tiezbro/opencode-session-history
- Owner: tiezbro
- License: 0bsd
- Created: 2026-04-11T08:19:23.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-12T06:27:44.000Z (2 months ago)
- Last Synced: 2026-04-14T04:03:15.882Z (2 months ago)
- Topics: cli, developer-tools, opencode, productivity, python, session-history, sessions, tmux
- Language: Python
- Size: 181 KB
- Stars: 5
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# OpenCode Session History Manager (OCS)
[中文说明](README.zh-CN.md)
[](https://github.com/tiezbro/opencode-session-history/actions/workflows/ci.yml)
> **Turn hidden OpenCode history into instant staging environments for your code.**
> **Type `ocs`, select your target session in a premium TUI, and instantly resume your workflow.**
---
## 💡 Why OCS? (The Problem)
OpenCode provides an unparalleled immersive workflow environment. However, its native `/sessions` interface naturally prioritizes **recent activities**. This results in **historical sessions**—which often hold your deepest context and hardest-won debugging paths—being unknowingly hidden or buried.
**You aren't just losing a session log; you are losing your momentum.**
OCS bridges this exact gap. Its core mission is transforming the thought "I know that session still exists somewhere" into **"I am jumping back in to continue coding right now."**
---
## 🚀 Core Value & v1.3.0.1 Features
1. **Advanced Interactive TUI (v1.3.0.1)**
OCS 1.3.0.1 introduces a state-of-the-art terminal interface with:
- **Self-Update (`--update`)**: One command to check and install the latest version from GitHub.
- **Native Modal Dialogs**: Professional "Rename Session" dialog with a modern aesthetic, allowing in-place edits without restarting the TUI.
- **Precision Alignment (CJK Support)**: Perfect right-alignment for all sessions, including those with Chinese titles.
- **Smooth Viewport Scrolling**: Effortlessly navigate through hundreds of sessions with automatic window scrolling.
- **Live Search & Metrics**: Real-time filtering by title/ID and instant session count statistics.
- **Date Clustering**: Grouping sessions by *Today*, *Yesterday*, or specific dates.
- **Refined Two-Line Layout**: Information-rich display with right-aligned metadata (Time & Message Count).
2. **Context-Aware History Restoration**
Automatically detects Git root and mines the local SQLite `opencode.db` for relevant sessions.
3. **Multi-Mode Runtime Discovery**
Instantly attaches to OpenCode running in **tmux** or as **direct processes**.
4. **Active Session Life-cycle Management**
- **Delete (`Ctrl+D`)**: Clean up old or irrelevant history.
- **Rename (`Ctrl+R`)**: Keep your workflow organized.
5. **Zero-Config, Zero-Intrusion**
No local JSON files needed. Just `cd` and `ocs`.
---
## 📖 OCS Command Reference
A complete reference of all available commands and options.
### CLI Arguments
| Command | Description |
|---------|-------------|
| `ocs` | Launch the interactive TUI session picker for the current project |
| `ocs ` | Directly open the session at the given index (e.g. `ocs 3`) |
| `ocs ` | Directly open a session by its full ID (e.g. `ocs ses_2b46e8...`) |
| `ocs ` | Open session #N for a specific project directory |
### Options
| Flag | Short | Description |
|------|-------|-------------|
| `--version` | `-V` | Print the current OCS version and exit |
| `--list` | `-l` | List all sessions for the current project without entering any |
| `--update` | | Check GitHub for the latest release and auto-install if newer |
| `--verbose` | `-v` | Show detailed diagnostic output for debugging |
### TUI Keyboard Shortcuts
| Key | Action |
|-----|--------|
| `↑` / `↓` | Navigate between sessions (with automatic viewport scrolling) |
| `←` / `→` | Page skip: jump 20 sessions at a time |
| `Enter` | Open the selected session |
| `Ctrl+D` | Delete the selected session |
| `Ctrl+R` | Rename the selected session (opens modal dialog) |
| `Ctrl+Q` / `Ctrl+C` / `Esc` | Cancel and exit |
| *Any printable key* | Live search / filter sessions by title or ID |
| `Backspace` | Remove last character from search |
### Quick Examples
```bash
# Launch interactive TUI
ocs
# List sessions without entering
ocs --list
# Jump to session #3
ocs 3
# Self-update to latest version
ocs --update
# Debug: show detailed detection logs
ocs --verbose
# Open session for another project
ocs 1 ~/projects/other-project
```
---
## ⚙️ How it Works (Under the Hood)
The moment you invoke `ocs`, the framework performs the following logic sequence in milliseconds:
1. Dynamically maps the CWD (Current Working Directory) upwards to ascertain the active Git tree's Root Path.
2. Mounts `~/.local/share/opencode/opencode.db`, scraping and grouping all valid Root Sessions and their associative metadata explicitly filtering for this project.
3. Conducts OS-level process fingerprint comparisons (bolstered by fallback `lsof` TCP scanning) to accurately isolate the live OpenCode targets.
4. Assembles optimal arguments and instantly dispatches the physical attach protocol:
```bash
opencode attach http://127.0.0.1: --dir -s
```
---
## 🚧 Scope & Constraints
Before implementing OCS into your workflow, note the following system boundaries:
- **Environment Depdency**: Native Python 3.10+ must be available.
- **Port Identification Strategy**: While `ocs` supports an innate `lsof` fallback scan (grabbing the actual TCP listening port from the `opencode` process tree), the **Best Practice** firmly recommends booting OpenCode with an explicit `--port 4096` flag. This dramatically reduces system scanning latency and guarantees precision mapping.
- **Single-Machine Boundery**: The active scope of this utility is confined to local host reconstruction. Transpiling and syncing OpenCode states across remote hosts via SSH are distinctly categorized as non-goals.
---
## 🛠 Installation Instructions
The provided scripts automatically detect your host architecture (macOS, Linux, Windows) and route `ocs` logic into your local secure binary execution path.
### Swift Deployment via GitHub
If you have forked this project, you must swap out `tiezbro` with your GitHub username below:
#### macOS / Linux
```bash
curl -fsSL https://raw.githubusercontent.com/tiezbro/opencode-session-history/main/scripts/install.sh | bash -s -- https://github.com/tiezbro/opencode-session-history.git
```
#### Windows PowerShell
```powershell
irm https://raw.githubusercontent.com/tiezbro/opencode-session-history/main/scripts/install.ps1 -OutFile install.ps1; powershell -ExecutionPolicy Bypass -File .\install.ps1 https://github.com/tiezbro/opencode-session-history.git; Remove-Item .\install.ps1
```
### Direct Local Mapping Structure
```bash
# macOS/Linux
./scripts/install.sh
# Windows
python .\scripts\install.py
```
---
## 🤝 Development & Contributions
- **Unit Verification Pipeline**: `python3 -m unittest discover -s tests -p 'test_*.py'`
- **Lints & Structure**: We employ `Ruff` broadly to orchestrate format checking and comprehensive AST evaluations.
- Read [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md) to comprehend integration prerequisites.
> License: 0BSD