OpenCode Session History Manager (OCS)

中文说明

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.1.2 Features

1. Advanced Interactive TUI (v1.3.1.2) OCS 1.3.1.2 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 <number>	Directly open the session at the given index (e.g. ocs 3)
ocs <session_id>	Directly open a session by its full ID (e.g. ocs ses_2b46e8...)
ocs <number> <path>	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 (Requires double confirmation via Modal)
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

# 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:

   opencode attach http://127.0.0.1:<detected_port> --dir <project_root> -s <exact_historical_session_id>

---

🚧 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

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

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

# 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 and CHANGELOG.md to comprehend integration prerequisites.

License: 0BSD