ocsz

A light-weight terminal browser for opencode sessions, built with fzf.

Note

opencode v2 has this built in: press Ctrl+O in the TUI to open a searchable list of recent sessions from every project, plus the projects themselves (docs). ocsz remains useful on opencode v1, or if you'd rather pick from an fzf list in the shell.

Browse your past opencode sessions in an interactive picker, fuzzy-search them, and resume the one you want — without leaving the terminal.

just now   Add dark mode toggle                              ~/projects/webapp
3m ago     ◦ Locate theme provider (@explorer subagent)      ~/projects/webapp
14m ago    ◦ Compare cache libraries (@librarian subagent)   ~/projects/webapp
52m ago    Write API migration plan                          ~/projects/api
1h ago     ◦ Review auth refactor risk (@oracle subagent)    ~/projects/api
2h ago     Refactor login flow                               ~/projects/api
2h ago     ◦ Rename getUser across repo (@fixer subagent)    ~/projects/api
6h ago     Set up CI pipeline                                ~/projects/infra
6h ago     ◦ Polish settings page (@designer subagent)       ~/projects/infra
1d ago     Draft release notes v2.1                          ~/notes
4d ago     Investigate memory leak                           ~/projects/daemon
4d ago     ◦ Research backpressure (@librarian subagent)     ~/projects/daemon

Features

• Browse & search — sessions listed newest-first, fuzzy-filtered as you type.
• Resume in place — Enter reopens the session in opencode, in its own project directory.
• More actions — fork-and-resume, start a new session, continue the last session, delete, and copy the resume command to the clipboard.
• Live preview — title, id, directory, and created/updated times for the highlighted session.
• Subagent sessions hidden by default — child/subagent sessions are filtered out; toggle them with a hotkey and they show up clearly marked.
• Aligned, colored list — columns line up even with full-width CJK titles; colors follow the terminal/fzf palette and honor NO_COLOR.
• CLI-backed — uses the opencode database command on v1 and the session API on v2, without reading storage files directly.

Requirements

• opencode 1.x (tested on 1.17.9) or 2.x (tested on 2.0.18)
• fzf 0.38+ (uses become/reload; tested on 0.73)
• GNU coreutils (date, wc, base64) — standard on Linux
• jq (required only for opencode v2)

Optional:

• A clipboard tool (wl-copy, xclip, xsel, or pbcopy). Without one, the copy action falls back to an OSC 52 escape and also prints the command to stdout.

glow is not required; jq is not required with opencode v1.

Installation

make install      # copies ocsz to ~/.local/bin/ocsz

Make sure ~/.local/bin is on your PATH. To remove it:

make uninstall

You can also just run the script directly:

./ocsz

Usage

Run ocsz with no arguments to open the picker. Type to fuzzy-search, then use the keys below.

Pass extra opencode args after --, for example ocsz -- --port 4096 on v1 or ocsz -- --server http://127.0.0.1:4096 on v2. They apply to resume, fork-and-resume, new, and continue-last launches. On v2, --server also applies to listing, forking, and deleting sessions.

Key	Action
Enter	Resume the selected session
Ctrl-F	Fork the selected session, then resume
Alt-N	Start a new session (in the current directory)
Alt-L	Continue the last session
Alt-S	Show / hide subagent (child) sessions
Ctrl-X	Delete the selected session (with confirm), then refresh
Ctrl-Y	Copy the session id + resume command to clipboard
?	Toggle the preview pane
Esc / Ctrl-C	Quit

Subagent sessions

Sessions spawned by subagents (the opencode task tool) have a parent session, and are hidden by default so the list stays focused on the sessions you actually started. Press Alt-S to toggle them on/off. When shown, each subagent row is prefixed with ◦ and dimmed, so it is easy to tell apart at a glance (the marker remains visible even with NO_COLOR).

Colors

The list uses the terminal's 16-color palette so it blends with your theme:

• relative time — dimmed (bright-black)
• title — default foreground (so fzf's match highlighting stands out)
• directory — cyan

Disable all color with either environment variable:

NO_COLOR=1 ocsz
OCSZ_NO_COLOR=1 ocsz

How it works

ocsz does not parse opencode's storage files directly. Instead it drives the opencode CLI:

• list sessions: v1 uses opencode db --format tsv "SELECT ... FROM session ..."; v2 uses paginated opencode api GET /api/session responses parsed with jq
• resume: opencode [extra...] <dir> -s <id>
• fork and resume: v1 uses opencode [extra...] <dir> --fork -s <id>; v2 uses opencode api POST /api/session/<id>/fork then opencode [extra...] <dir> -s <new-id>
• continue last: opencode [extra...] -c
• delete: opencode session delete <id> (with --server forwarded on v2)

Neither backend reads opencode's on-disk format directly.

Customization

A few knobs live at the top of the ocsz script:

• TIME_WIDTH, TITLE_WIDTH — column widths.
• SUB_MARKER — the subagent marker glyph (default ◦ ). If you change it to a non-ASCII glyph, update the width-1 exception in char_width() to match its codepoint.
• C_TIME, C_DIM, C_DIR — ANSI color codes for the columns.

Environment variables

Variable	Effect
NO_COLOR	Disable all color (standard convention).
OCSZ_NO_COLOR	Disable all color (tool-specific opt-out).
OCSZ_DRY_RUN=1	Make actions print the opencode command instead of running it (useful for testing).
OCSZ_OPENCODE_ARGS	Extra args passed to every opencode launch (resume/fork/new/last), e.g. --port 4096 on v1 or --server URL on v2. On v2, --server also applies to list/fork/delete. A CLI -- passthrough overrides this. Args are whitespace-split, so values containing spaces are not supported.

Prior art

ocsz was inspired by these similar opencode session tools:

• bashtools/oc_session - lists opencode sessions as a Markdown table.
• Shane0xM/oc-session - a session browser with fuzzy search and resume.
• mclarkson/ocs - an interactive TUI session browser.

License

MIT