{"id":48732306,"url":"https://github.com/tiezbro/opencode-session-history","last_synced_at":"2026-04-18T08:01:20.529Z","repository":{"id":350686630,"uuid":"1207661632","full_name":"tiezbro/opencode-session-history","owner":"tiezbro","description":"Bring hidden OpenCode session history back into view and seamlessly continue work in any historical session.","archived":false,"fork":false,"pushed_at":"2026-04-12T06:27:44.000Z","size":185,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-14T04:03:15.882Z","etag":null,"topics":["cli","developer-tools","opencode","productivity","python","session-history","sessions","tmux"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"0bsd","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tiezbro.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-11T08:19:23.000Z","updated_at":"2026-04-13T13:32:13.000Z","dependencies_parsed_at":"2026-04-15T05:00:30.480Z","dependency_job_id":null,"html_url":"https://github.com/tiezbro/opencode-session-history","commit_stats":null,"previous_names":["tiezbro/opencode-session-history"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/tiezbro/opencode-session-history","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiezbro%2Fopencode-session-history","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiezbro%2Fopencode-session-history/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiezbro%2Fopencode-session-history/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiezbro%2Fopencode-session-history/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tiezbro","download_url":"https://codeload.github.com/tiezbro/opencode-session-history/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiezbro%2Fopencode-session-history/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31826902,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"online","status_checked_at":"2026-04-15T02:00:06.175Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","developer-tools","opencode","productivity","python","session-history","sessions","tmux"],"created_at":"2026-04-12T02:01:05.603Z","updated_at":"2026-04-15T05:00:34.456Z","avatar_url":"https://github.com/tiezbro.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenCode Session History Manager (OCS)\n\n[中文说明](README.zh-CN.md)\n\n[![CI](https://github.com/tiezbro/opencode-session-history/actions/workflows/ci.yml/badge.svg)](https://github.com/tiezbro/opencode-session-history/actions/workflows/ci.yml)\n![License: 0BSD](https://img.shields.io/badge/license-0BSD-blue.svg)\n![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)\n\n\u003e **Turn hidden OpenCode history into instant staging environments for your code.**  \n\u003e **Type `ocs`, select your target session in a premium TUI, and instantly resume your workflow.**\n\n---\n\n## 💡 Why OCS? (The Problem)\n\nOpenCode 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.\n\n**You aren't just losing a session log; you are losing your momentum.**  \nOCS 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.\"**\n\n---\n\n## 🚀 Core Value \u0026 v1.3.0.1 Features\n\n1. **Advanced Interactive TUI (v1.3.0.1)**\n   OCS 1.3.0.1 introduces a state-of-the-art terminal interface with:\n   - **Self-Update (`--update`)**: One command to check and install the latest version from GitHub.\n   - **Native Modal Dialogs**: Professional \"Rename Session\" dialog with a modern aesthetic, allowing in-place edits without restarting the TUI.\n   - **Precision Alignment (CJK Support)**: Perfect right-alignment for all sessions, including those with Chinese titles.\n   - **Smooth Viewport Scrolling**: Effortlessly navigate through hundreds of sessions with automatic window scrolling.\n   - **Live Search \u0026 Metrics**: Real-time filtering by title/ID and instant session count statistics.\n   - **Date Clustering**: Grouping sessions by *Today*, *Yesterday*, or specific dates.\n   - **Refined Two-Line Layout**: Information-rich display with right-aligned metadata (Time \u0026 Message Count).\n2. **Context-Aware History Restoration**\n   Automatically detects Git root and mines the local SQLite `opencode.db` for relevant sessions.\n3. **Multi-Mode Runtime Discovery**\n   Instantly attaches to OpenCode running in **tmux** or as **direct processes**.\n4. **Active Session Life-cycle Management**\n   - **Delete (`Ctrl+D`)**: Clean up old or irrelevant history.\n   - **Rename (`Ctrl+R`)**: Keep your workflow organized.\n5. **Zero-Config, Zero-Intrusion**\n   No local JSON files needed. Just `cd` and `ocs`.\n\n---\n\n## 📖 OCS Command Reference\n\nA complete reference of all available commands and options.\n\n### CLI Arguments\n\n| Command | Description |\n|---------|-------------|\n| `ocs` | Launch the interactive TUI session picker for the current project |\n| `ocs \u003cnumber\u003e` | Directly open the session at the given index (e.g. `ocs 3`) |\n| `ocs \u003csession_id\u003e` | Directly open a session by its full ID (e.g. `ocs ses_2b46e8...`) |\n| `ocs \u003cnumber\u003e \u003cpath\u003e` | Open session #N for a specific project directory |\n\n### Options\n\n| Flag | Short | Description |\n|------|-------|-------------|\n| `--version` | `-V` | Print the current OCS version and exit |\n| `--list` | `-l` | List all sessions for the current project without entering any |\n| `--update` | | Check GitHub for the latest release and auto-install if newer |\n| `--verbose` | `-v` | Show detailed diagnostic output for debugging |\n\n### TUI Keyboard Shortcuts\n\n| Key | Action |\n|-----|--------|\n| `↑` / `↓` | Navigate between sessions (with automatic viewport scrolling) |\n| `←` / `→` | Page skip: jump 20 sessions at a time |\n| `Enter` | Open the selected session |\n| `Ctrl+D` | Delete the selected session |\n| `Ctrl+R` | Rename the selected session (opens modal dialog) |\n| `Ctrl+Q` / `Ctrl+C` / `Esc` | Cancel and exit |\n| *Any printable key* | Live search / filter sessions by title or ID |\n| `Backspace` | Remove last character from search |\n\n### Quick Examples\n\n```bash\n# Launch interactive TUI\nocs\n\n# List sessions without entering\nocs --list\n\n# Jump to session #3\nocs 3\n\n# Self-update to latest version\nocs --update\n\n# Debug: show detailed detection logs\nocs --verbose\n\n# Open session for another project\nocs 1 ~/projects/other-project\n```\n\n---\n\n## ⚙️ How it Works (Under the Hood)\n\nThe moment you invoke `ocs`, the framework performs the following logic sequence in milliseconds:\n1. Dynamically maps the CWD (Current Working Directory) upwards to ascertain the active Git tree's Root Path.\n2. Mounts `~/.local/share/opencode/opencode.db`, scraping and grouping all valid Root Sessions and their associative metadata explicitly filtering for this project.\n3. Conducts OS-level process fingerprint comparisons (bolstered by fallback `lsof` TCP scanning) to accurately isolate the live OpenCode targets.\n4. Assembles optimal arguments and instantly dispatches the physical attach protocol:\n   ```bash\n   opencode attach http://127.0.0.1:\u003cdetected_port\u003e --dir \u003cproject_root\u003e -s \u003cexact_historical_session_id\u003e\n   ```\n\n---\n\n## 🚧 Scope \u0026 Constraints\n\nBefore implementing OCS into your workflow, note the following system boundaries:\n\n- **Environment Depdency**: Native Python 3.10+ must be available.\n- **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.\n- **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.\n\n---\n\n## 🛠 Installation Instructions\n\nThe provided scripts automatically detect your host architecture (macOS, Linux, Windows) and route `ocs` logic into your local secure binary execution path.\n\n### Swift Deployment via GitHub\nIf you have forked this project, you must swap out `tiezbro` with your GitHub username below:\n\n#### macOS / Linux\n```bash\ncurl -fsSL https://raw.githubusercontent.com/tiezbro/opencode-session-history/main/scripts/install.sh | bash -s -- https://github.com/tiezbro/opencode-session-history.git\n```\n#### Windows PowerShell\n```powershell\nirm 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\n```\n\n### Direct Local Mapping Structure\n```bash\n# macOS/Linux\n./scripts/install.sh\n\n# Windows\npython .\\scripts\\install.py\n```\n\n---\n\n## 🤝 Development \u0026 Contributions\n\n- **Unit Verification Pipeline**: `python3 -m unittest discover -s tests -p 'test_*.py'`\n- **Lints \u0026 Structure**: We employ `Ruff` broadly to orchestrate format checking and comprehensive AST evaluations.\n- Read [CONTRIBUTING.md](CONTRIBUTING.md) and [CHANGELOG.md](CHANGELOG.md) to comprehend integration prerequisites.\n\n\u003e License: 0BSD\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiezbro%2Fopencode-session-history","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftiezbro%2Fopencode-session-history","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiezbro%2Fopencode-session-history/lists"}