◐ Shell
clean mode source ↗

GitHub - quantk/opensessions

opensession

A local, read-only terminal browser for OpenCode and Pi agent session history.

opensession turns local agent session storage into a fast, searchable, keyboard-first TUI. It scans OpenCode JSON files/opencode.db and Pi JSONL sessions in read-only mode, builds its own SQLite index, and lets you browse sessions, branches, timelines, tool calls, markdown answers, token usage, and raw part details without touching the source storage.

Go 1.25+ SQLite Terminal UI Read-only

Why

Agent sessions contain a lot of valuable context: prompts, assistant responses, tool calls, file references, subagent tasks, token usage, and raw event metadata.

Once those sessions pile up, finding the one conversation where you solved a bug, changed a config, or ran a specific command becomes painful.

opensession gives that history a local index and a focused terminal UI.

Agent storage                 opensession index              Terminal UI
OpenCode / Pi sessions        local SQLite DB                browse, search, inspect
        |                            |                              |
        | read-only scan             | app-owned writes             |
        v                            v                              v
+------------------+       +---------------------+       +----------------------+
| OpenCode records | ----> | source-aware        | ----> | mixed session list   |
| Pi JSONL trees   |       | sessions/parts/tags |       | branches/details     |
+------------------+       +---------------------+       +----------------------+

Features

  • Read-only source scanning: opensession never creates, edits, deletes, archives, compacts, forks, resumes, or labels files inside OpenCode or Pi storage.
  • Multi-source browsing: OpenCode and Pi sessions appear together with [opencode] / [pi] source badges; use --source to restrict scanning.
  • Pi branch browsing: Pi JSONL session trees open on the latest branch by default and provide a keyboard tree view for alternate branches.
  • Local SQLite index: sessions, entries/messages, parts, search text, scan metadata, tags, and bookmarks live in an application-owned database.
  • Fast startup rescans: unchanged source records are skipped using source path, size, and modification time metadata.
  • Flat or project-grouped browsing: switch between recency-ordered sessions and project-grouped views.
  • Timeline reader: open a session to inspect user messages, assistant messages, tool events, patches, files, and bounded previews.
  • Context-sensitive search: / searches sessions from the session list and searches only the current timeline inside a session.
  • Assistant markdown rendering: assistant text is rendered as terminal markdown by default, with a source-mode toggle.
  • Reasoning guardrails: reasoning parts are hidden by default and only shown after an explicit toggle.
  • Subagent navigation: linked task tool rows can open child or subagent session timelines and return to the parent context.
  • Pretty part details: tool, patch, and file parts open into structured detail views instead of raw JSON dumps.
  • Explicit raw JSON view: raw content is only shown after an intentional action, and unsafe payloads are guarded.
  • Heavy payload protection: large tool artifacts, snapshots, binary-looking data URLs, and oversized text are summarized instead of fully indexed or rendered.
  • Token usage summaries: displays available total, input, output, reasoning, cache read, and cache write token counts without showing monetary cost.
  • Local tags and bookmarks: metadata is stored locally in the opensession database and never written back to source storage.

Install / Run

Run directly from a checkout:

CGO_ENABLED=0 go run ./cmd/opensession

Build a local binary:

CGO_ENABLED=0 go build -o opensession ./cmd/opensession
./opensession

Show the version:

Usage

Use the default OpenCode storage location:

CGO_ENABLED=0 go run ./cmd/opensession

Use a custom OpenCode storage root:

CGO_ENABLED=0 go run ./cmd/opensession --storage-root /path/to/opencode/storage

Use a custom Pi sessions root:

CGO_ENABLED=0 go run ./cmd/opensession --pi-sessions-root /path/to/.pi/agent/sessions

Scan only one source:

CGO_ENABLED=0 go run ./cmd/opensession --source pi
CGO_ENABLED=0 go run ./cmd/opensession --source opencode

The mixed session list uses source badges rather than an in-TUI source filter.

Use a custom opensession SQLite index:

CGO_ENABLED=0 go run ./cmd/opensession --db /path/to/opensession.sqlite

Open the existing index without scanning first:

CGO_ENABLED=0 go run ./cmd/opensession --no-scan

Keyboard

Key Action
j / k Move selection or scroll
l / Enter Open a session, part, message detail, or linked child session
h / Esc Go back
/ Search the current view
v Toggle flat/grouped session list mode
r Show or hide reasoning parts in a timeline
b Open Pi branch/tree navigation from a Pi timeline
m Toggle assistant markdown rendering/source view
R Toggle pretty detail/raw JSON in part detail view
g / G Jump to top or bottom
PgUp / PgDown Page through long views
q Quit

Storage Paths

Source selection:

  1. --source all|opencode|pi (comma-separated values are allowed)
  2. default: all

OpenCode storage root resolution order:

  1. --storage-root
  2. OPENSESSION_STORAGE_ROOT
  3. OPENCODE_STORAGE_ROOT
  4. $XDG_DATA_HOME/opencode/storage
  5. ~/.local/share/opencode/storage

Pi sessions root resolution order:

  1. --pi-sessions-root
  2. OPENSESSION_PI_SESSIONS_ROOT
  3. PI_SESSIONS_ROOT
  4. ~/.pi/agent/sessions

opensession SQLite database path resolution order:

  1. --db
  2. OPENSESSION_DB
  3. $XDG_STATE_HOME/opensession/opensession.sqlite
  4. ~/.local/state/opensession/opensession.sqlite

Data Safety

opensession treats OpenCode and Pi storage as source material, not as writable state.

OpenCode storage / Pi JSONL sessions
        |
        | read only
        v
opensession scanner
        |
        | writes only here
        v
opensession.sqlite

Browsing, searching, opening raw previews, reading child sessions or Pi branches, tags, and bookmarks do not mutate OpenCode or Pi files.

Large or unsafe raw parts are guarded. Normal views use bounded previews and searchable summaries instead of rendering full raw payloads.

Development

Enter the Nix development shell:

Or use direnv:

The dev shell provides Go 1.25, gopls, and SQLite tools.

Run tests:

Run a focused package test:

go test ./internal/tui -run TestModelRawPartGuard

Format touched Go files:

gofmt -w ./path/to/file.go

Tech Stack

  • Go 1.25
  • Bubble Tea terminal UI
  • Lip Gloss styling
  • Glamour markdown rendering
  • Pure-Go SQLite via modernc.org/sqlite
  • Nix flakes dev shell

Status

opensession is an early local-first tool focused on safe browsing, search, and inspection of local agent session history.

Possible next areas:

  • Dedicated TUI shortcuts for editing local tags and bookmarks.
  • Packaged release binaries.
  • Richer filters for sources, projects, models, dates, tools, and tags.
  • Export views for selected sessions or timelines.