opencode-sesh 0.1.3

package/AGENTS.md

@@ -0,0 +1,129 @@
+# AGENTS.md — sesh
+
+Instructions for AI coding agents working in this repository. The map, not the
+territory: read this first, then the specific file you need.
+
+## What this is
+
+`sesh` is an opencode-native session browser in three parts:
+
+1. **`bin/`** — a fullscreen [fzf](https://github.com/junegunn/fzf) picker for
+   any terminal. Lists **all** sessions across **all** project directories,
+   full-text searchable, with transcript preview and resume/fork/delete.
+2. **`tui/sesh-panel.tsx`** — a SolidJS/OpenTUI plugin for the opencode TUI: a
+   recent-sessions section in the sidebar plus a `ctrl+o` / `/sesh` picker.
+3. **`opencode/tools/sesh-list.ts`** — the `sesh-list` custom tool, so the agent
+   can list sessions across every directory (the native `opencode session list`
+   is project-scoped).
+
+No iTerm2, no AppleScript, no panes, no window management — **never add any.**
+opencode has no persistent-sidebar API, so the "sidebar" is a `sidebar_content`
+slot section plus an xlarge modal picker; the terminal UI is fullscreen fzf.
+
+## Start here
+
+```bash
+npm install            # dev deps (TypeScript, opencode/OpenTUI types)
+npm test               # fixture-DB regression suite — must stay green
+npm run typecheck      # tsc over tui/ and opencode/
+npm run lint:sh        # bash -n on every script
+HOME=/tmp/fakehome bash install.sh   # installer smoke test (never touches ~/.config)
+```
+
+## Layout
+
+- `bin/` — flat; no subdirs. Scripts resolve siblings from their own location.
+  Never hardcode install paths.
+- `tui/sesh-panel.tsx` — SolidJS panel, `/** @jsxImportSource @opentui/solid */`.
+- `opencode/tools/sesh-list.ts` — the agent-facing `sesh-list` tool.
+- `themes/`, `tests/`, `install.sh`, `README.md`.
+
+The **filename becomes the tool name** in opencode, so `sesh-list.ts` is the
+`sesh-list` tool. Do not rename it without updating the docs.
+
+## Data flow (fzf picker)
+
+`bin/sesh-list.sh` is the only place that knows the session store (opencode
+SQLite DB: `session` / `message` / `part` tables). Keystrokes never touch the
+database:
+
+- `--refresh` (expensive): bulk-reads session metadata and per-session text
+  parts, validates the persistent extraction cache
+  (`$SESH_CACHE_DIR/extractions/<ses_*.json>`) against `time_updated` + part
+  count, re-extracts only changed sessions, prunes vanished ones, and atomically
+  publishes `STATE_DIR/snapshot.jsonl` with `status = fresh`. Scope
+  (`--cwd`/toggle) and `--limit` apply at assembly, so metadata always covers
+  the whole DB and pruning is always safe.
+- render (cheap, pure `jq`): reads the snapshot only. Filters on `searchText`
+  (title + `fulltextLower`, both lowercased at extraction), groups by `cwd`,
+  sorts groups/items by recency, renders the TSV.
+
+**Output contract** (TSV, 6 fields):
+`agentId  sessionId  liveState  display  cwd  trackingId`. `display` is the only
+rendered column; `trackingId` is fzf's `--id-nth`. Headers/notices carry an
+empty `sessionId` and are a selection no-op — keep that guard.
+
+One worker (`sesh-refresh-worker.sh`, per picker, TERMed on exit) serializes
+scans; fzf's `start`/`every(3)`/`change` bindings render only. Selection requests
+a fresh poll (`request`/`wait`, ≤12 s) before dispatch. opencode has no
+live-agent API, so `liveState` is always `unknown` and rows render gray;
+dispatch is always `opencode --session <id>` (`--fork` with Ctrl-F/Enter).
+Resume happens in place (`exec` after `cd` to the session's cwd).
+
+## Conventions
+
+- Default scope is **all** sessions, every directory. `--cwd`/Ctrl-G narrows.
+  Archived sessions and fork children are hidden unless `--archived`.
+- **Text parts only** in search/preview; reasoning and tool payloads are
+  excluded (asserted in tests).
+- Validate session ids (`^ses_[A-Za-z0-9]+$`) before SQL interpolation — never
+  interpolate unvalidated input.
+- Prefer direct `sqlite3` over `opencode db` (startup latency). Never parse
+  `sqlite3 -json` in `-R` mode; it pretty-prints — parse as JSON.
+- `jq -R` output stays JSON-quoted: use `-Rr` when a shell variable needs the
+  raw string.
+- fzf: stock only, `>= 0.52` (`transform:`, `every():`). `{q}` in binds is
+  shell-quoted by fzf — don't add quoting. Ctrl-G is bind-only (stays open);
+  Ctrl-F is `--expect` (accepts with fork).
+- The installer prefers the local opencode version for `@opencode-ai/*` and
+  merges (never clobbers) the config `package.json`; opencode runs `bun install`
+  at startup.
+
+## TUI panel (`tui/sesh-panel.tsx`)
+
+- **Sidebar:** `api.slots.register` on `sidebar_content` (append mode — native
+  sidebar content stays). Renders the most recent unarchived sessions with the
+  current one highlighted, polled every 15 s. Display-only; the picker does
+  actions.
+- **Picker:** a custom dialog (not `DialogSelect`) grouped by
+  project/directory, recency-ordered, resume via
+  `api.route.navigate("session", …)`. `ctrl+o` and the command palette open it;
+  Ctrl-X deletes via the opencode CLI and removes the row only after the server
+  confirms the deletion.
+
+### Hard-won rules — do not regress
+
+- **No `DialogSelect`.** Call `api.ui.dialog.setSize("xlarge")` **after**
+  `dialog.replace(...)`; `replace` resets the size to medium.
+- Use the `backgroundColor` **prop** on boxes, never `style={{backgroundColor}}`.
+- No percentage heights/widths in the picker; size the list window explicitly.
+- An inline `<input>` in a slot does **not** receive keyboard focus. Sidebar and
+  home search are keymap-captured queries (priority-20 base layer, letters /
+  space / backspace, Esc exits); click the box to activate, click elsewhere to
+  leave.
+- **`/sesh` is the plugin's slash**, registered with
+  `slash: { name: "sesh" }` on the `api.command.register` entry — that is the
+  only way to open the dialog. A markdown command under `commands/` cannot drive
+  the picker (it just prompts the model), so never ship one; the installer
+  removes any leftover `commands/sesh.md`.
+- Do not bind `<leader>l` (native `session_list`) or shadow the native
+  `/sessions` command.
+
+## Verifying
+
+- `npm test` — fixture-DB regression suite, hermetic via `SESH_*` overrides.
+- `npm run typecheck` — `tsc` over `tui/` and `opencode/`.
+- `npm run lint:sh` — `bash -n` on every script.
+- `HOME=/tmp/fakehome bash install.sh` — installer smoke test.
+- Keep `tui/sesh-panel.tsx` and any installed copy byte-identical when testing
+  the panel locally.

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.3] - 2026-09-12
+
+### Added
+
+- npm distribution: `npm install -g opencode-sesh`, with `sesh install` /
+  `sesh uninstall` wrappers and a tag-triggered publish workflow.
+
+## [0.1.2] - 2026-09-12
+
+### Fixed
+
+- The home-screen recent-sessions list had no transcript preview binding, so
+  pressing space while hovering a session typed into the prompt instead. It now
+  opens the same preview as the sidebar.
+
+## [0.1.1] - 2026-09-12
+
+### Changed
+
+- Transcript previews (terminal picker and TUI panel) now show the newest
+  messages first instead of the oldest.
+
+## [0.1.0] - 2026-09-12
+
+### Added
+
+- Fullscreen `fzf` terminal picker (`sesh`) listing every session across every
+  project directory, grouped by directory and sorted by recency.
+- Full-text search over session titles and text-only conversation parts, with a
+  persistent, incrementally refreshed extraction cache.
+- Transcript preview, rendered as Markdown via `glow` when available.
+- Resume in place (`opencode --session <id>`) and fork (`--fork`) actions.
+- Session deletion from the picker.
+- `sesh-list` opencode tool so agents can list sessions across all directories.
+- OpenTUI sidebar panel and `ctrl+o` / `/sesh` picker plugin, themed by the
+  active opencode theme.
+- `install.sh` / `--uninstall` installer that links the picker and merges the
+  TUI plugin into the opencode config.
+- Fixture-database regression suite, TypeScript typechecking, and ShellCheck in
+  CI.
+
+[Unreleased]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.1.3...HEAD
+[0.1.3]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/ozandogrultan/opencode-sesh/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/ozandogrultan/opencode-sesh/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ozan Dogrultan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# sesh
+
+**A session browser for [opencode](https://opencode.ai).** Search every session
+across every project, preview the transcript, and resume in place — from your
+terminal or from inside the TUI.
+
+`opencode` keeps a growing pile of sessions, and its native lists (`<leader>l`,
+`/sessions`) are scoped to the current project. `sesh` shows all of them —
+grouped by directory, full-text searchable, and previewable from anywhere.
+
+[![CI](https://github.com/ozandogrultan/opencode-sesh/actions/workflows/ci.yml/badge.svg)](https://github.com/ozandogrultan/opencode-sesh/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](#contributing)
+[![GitHub stars](https://img.shields.io/github/stars/ozandogrultan/opencode-sesh?style=social)](https://github.com/ozandogrultan/opencode-sesh/stargazers)
+
+```text
+❯ auth
+  ~/code/api                                 (8)
+  ├ Retry the OAuth token refresh       2h
+  ├ Login rate limiting notes          3d
+  └ auth middleware cleanup           11d
+  ~/code/web                                (3)
+  ├ Fix session cookie on Safari       1d
+  └ Redirect loop after logout         6d
+```
+
+## Why sesh
+
+- **Every session, everywhere.** Sessions are grouped by project directory and
+  sorted by recency — across *all* your projects, not just the current one.
+- **Full-text search.** Type to match against session titles *and* the text of
+  the conversation itself. Reasoning and tool output are excluded, so the index
+  stays clean.
+- **Transcript preview.** Space shows the most recent messages first, rendered as
+  Markdown (with `glow` if you have it).
+- **Resume in place.** Enter `exec`s `opencode --session <id>` in the session's
+  own directory. Ctrl-F forks instead. Your terminal becomes the session — no
+  tabs, no panes, no window management.
+- **Native TUI, too.** A recent-sessions section in the opencode sidebar plus a
+  `ctrl+o` picker, both themed by your opencode theme.
+- **Fast.** The database is scanned once per refresh and cached; keystrokes only
+  re-render the last snapshot, so typing never triggers a query storm.
+
+## Install
+
+With npm:
+
+```bash
+npm install -g opencode-sesh
+sesh install
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/ozandogrultan/opencode-sesh.git
+cd opencode-sesh
+bash install.sh
+```
+
+`sesh install` (or `bash install.sh`) links `sesh` into `~/.local/bin`, copies
+the `sesh-list` tool and the TUI panel into
+`${XDG_CONFIG_HOME:-~/.config}/opencode`, registers the panel in `tui.json`, and
+declares the plugin dependencies (opencode installs them on next start). The
+panel registers the `/sesh` slash command. It never edits your shell rc, and any
+file it would overwrite is backed up first.
+
+The npm package ships the same scripts and installer; the runtime tools below
+are still required.
+
+Restart opencode to load the panel, then:
+
+```bash
+sesh              # terminal picker
+```
+
+```text
+/sesh             # inside opencode — picker (TUI plugin)
+ctrl+o            # inside opencode — picker
+```
+
+### Requirements
+
+- [opencode](https://opencode.ai), used at least once
+- `bash`, `jq`, and [`fzf`](https://github.com/junegunn/fzf) `>= 0.52`
+- `sqlite3` recommended — the picker queries the session DB directly in
+  milliseconds and falls back to the slower `opencode db` CLI without it
+- [`glow`](https://github.com/charmbracelet/glow) optional — styles the
+  transcript preview as Markdown; without it the preview shows the plain
+  Markdown, unchanged otherwise
+
+### Uninstall
+
+```bash
+sesh uninstall        # npm installs
+bash install.sh --uninstall   # from source
+```
+
+## Usage
+
+### Terminal picker
+
+| Key | Action |
+| --- | --- |
+| Type | Search titles and transcript text across all directories |
+| Enter | Resume the selected session in this terminal |
+| Ctrl-F Enter | Resume as a fork (the original is untouched) |
+| Ctrl-G | Toggle current-directory scope / all sessions |
+| Space (empty query) | Toggle the transcript preview |
+| `?` (empty query) | Toggle shortcut help |
+| Ctrl-X | Delete the selected session |
+| Escape | Exit |
+
+Flags: `--cwd` (current directory only), `--limit N` (default: all),
+`--archived`, `--print` (print `id<TAB>cwd` instead of resuming), `--fork`,
+`--query TEXT`, `--check`.
+
+Because `--print` just emits the id and directory, `sesh` doubles as a scriptable
+session lookup:
+
+```bash
+read -r id cwd < <(sesh --print --query "auth")
+```
+
+### TUI panel
+
+| Key | Action |
+| --- | --- |
+| `/sesh` | Open the full picker |
+| `ctrl+o` | Open the full picker (also in the command palette) |
+| Type | Search titles, directories and transcript text |
+| `↑`/`↓`, `PgUp`/`PgDn`, `Home`/`End` | Move the selection |
+| Space | Toggle the transcript preview |
+| Enter | Open the selected session |
+| Esc | Close |
+
+Click the sidebar's `search…` box to filter recent sessions in place; click
+elsewhere or press Esc to leave search.
+
+## Configuration
+
+All variables are optional.
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `SESH_DB` | `opencode db path` | opencode SQLite database |
+| `SESH_SQLITE` | `sqlite3` | query tool (`opencode db` is ~300 ms/call) |
+| `SESH_JQ` / `SESH_FZF` | `PATH` | explicit executable overrides |
+| `SESH_GLOW` | first `glow` on `PATH` | optional Markdown preview renderer |
+| `SESH_OPENCODE` | `opencode` | opencode executable (resume / delete) |
+| `SESH_CACHE_DIR` | `~/.cache/sesh` | persistent search-index cache |
+
+## How it works
+
+`bin/sesh-list.sh` is the only place that reads the opencode session store
+(SQLite: `session` / `message` / `part`). Each refresh extracts session metadata
+and text-only parts into a persistent per-session cache keyed on `time_updated`
+and part count, then atomically publishes a `snapshot.jsonl`. Every keystroke
+re-renders that snapshot with `jq` alone, so typing never starts competing
+database scans. Reasoning and tool payloads are never indexed or previewed, and
+session ids are validated before any SQL interpolation.
+
+Four flat scripts back the terminal UI — the picker (`sesh.sh`), snapshot
+builder (`sesh-list.sh`), preview renderer (`sesh-preview.sh`) and deleter
+(`sesh-delete.sh`) — with one worker process per picker serializing refreshes.
+The TUI panel (`tui/sesh-panel.tsx`) is a SolidJS OpenTUI plugin that talks to
+the opencode SDK over the same store.
+
+## FAQ
+
+**Does it replace opencode's native session list?** No. `<leader>l` and the
+native `/sessions` command are untouched; `sesh` is additive.
+
+**Is there an agent-facing list?** Yes — the `sesh-list` tool lets the model list
+every session across all directories (the native `opencode session list` only
+covers the current project) and offer to resume one.
+
+**Where is my data?** It reads the opencode database read-only and caches
+extracted text under `~/.cache/sesh`. Nothing is uploaded anywhere.
+
+**Does it work on Windows?** It targets macOS and Linux. WSL should work; native
+Windows is untested.
+
+**Why a separate terminal picker *and* a TUI panel?** The panel is always one
+keystroke away while you work. The terminal picker is fullscreen and works from
+any shell, including outside opencode.
+
+## Contributing
+
+Issues and PRs are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full
+guide; this project follows the [Code of Conduct](CODE_OF_CONDUCT.md). Run the
+checks before opening a PR:
+
+```bash
+npm install
+npm test             # fixture-database regression suite
+npm run typecheck    # tsc over tui/ and opencode/
+npm run lint:sh      # bash -n on every script
+```
+
+`HOME=/tmp/fakehome bash install.sh` smoke-tests the installer without touching
+your real opencode config. [AGENTS.md](AGENTS.md) documents the architecture and
+the hard-won TUI rules.
+
+## License
+
+[MIT](LICENSE)

package/bin/sesh

@@ -0,0 +1,26 @@
+#!/bin/bash
+set -e
+source_path=${BASH_SOURCE[0]}
+links=0
+while [ -L "$source_path" ]; do
+  links=$((links + 1))
+  [ "$links" -le 40 ] || { echo 'sesh: launcher symlink loop.' >&2; exit 1; }
+  source_dir="$(cd "$(dirname "$source_path")" && pwd -P)"
+  link_target=$(readlink "$source_path")
+  case "$link_target" in
+    /*) source_path=$link_target ;;
+    *) source_path="$source_dir/$link_target" ;;
+  esac
+done
+SCRIPT_DIR="$(cd "$(dirname "$source_path")" && pwd -P)"
+case ${1:-} in
+  install)
+    shift
+    exec bash "$SCRIPT_DIR/../install.sh" "$@"
+    ;;
+  uninstall)
+    shift
+    exec bash "$SCRIPT_DIR/../install.sh" --uninstall "$@"
+    ;;
+esac
+exec "$SCRIPT_DIR/sesh.sh" "$@"

package/bin/sesh-delete.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# Usage: sesh-delete.sh STATE_DIR SESSION_ID
+# Ctrl-X deletes through the opencode CLI so its own safeguards apply.
+# There is no confirmation prompt, matching the Claude picker.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+state_dir=${1:-}
+session_id=${2:-}
+snapshot="$state_dir/snapshot.jsonl"
+lock="$state_dir/refresh.lock"
+OPENCODE_BIN=${SESH_OPENCODE:-opencode}
+JQ_BIN=${SESH_JQ:-jq}
+
+lock_owned=0
+pause() { release_lock; read -r -n 1 -s -p "Press any key to return..." _ || true; echo; }
+release_lock() {
+  [ "$lock_owned" = 1 ] || return 0
+  rm -f "$lock/pid" 2>/dev/null || true
+  rmdir "$lock" 2>/dev/null || true
+  lock_owned=0
+}
+# Mirrors the acquirer in sesh-list.sh, including its stale-owner
+# recovery. Recovery is conservative -- an unreadable or non-numeric owner,
+# or one still alive, always loses the race.
+acquire_lock() {
+  if mkdir "$lock" 2>/dev/null; then printf '%s\n' "$$" > "$lock/pid"; return 0; fi
+  local owner=''; [ -f "$lock/pid" ] && owner=$(cat "$lock/pid" 2>/dev/null || true)
+  case "$owner" in ''|*[!0-9]*) return 1;; esac
+  kill -0 "$owner" 2>/dev/null && return 1
+  rm -f "$lock/pid" 2>/dev/null || return 1
+  rmdir "$lock" 2>/dev/null || return 1
+  mkdir "$lock" 2>/dev/null || return 1
+  printf '%s\n' "$$" > "$lock/pid"
+}
+
+# fzf passes an empty second field for headers and notices. They are never
+# actions, and should not surface a misleading failure prompt.
+[ -n "$session_id" ] || exit 0
+case "$session_id" in ses_[A-Za-z0-9]*) ;; *) echo "Invalid session identity."; pause; exit 0;; esac
+[ -n "$state_dir" ] && [ -f "$snapshot" ] || { echo "No session snapshot available."; pause; exit 0; }
+
+# Serialize this action with the sole snapshot publisher. A short collision
+# is safer than deleting against a moving snapshot.
+if ! acquire_lock; then
+  echo "Session list is refreshing; try deletion again in a moment."
+  pause
+  exit 0
+fi
+lock_owned=1
+trap 'release_lock' EXIT
+trap 'exit 130' HUP INT TERM
+
+if ! "$JQ_BIN" -se --arg sid "$session_id" 'any(.sessionId == $sid)' "$snapshot" >/dev/null 2>&1; then
+  echo "The selected session is no longer in this snapshot."
+  pause
+  exit 0
+fi
+
+command -v "$OPENCODE_BIN" >/dev/null 2>&1 || { echo "Refusing deletion: opencode executable is unavailable."; pause; exit 0; }
+"$OPENCODE_BIN" session delete "$session_id" || { echo "opencode could not delete the session."; pause; exit 1; }
+echo "Session deleted."
+
+SESH_LOCK_HELD="$state_dir" "$SCRIPT_DIR/sesh-list.sh" --refresh --state-dir "$state_dir" >/dev/null || true
+release_lock
+trap - EXIT HUP INT TERM