oc-session

Global OpenCode session browser and resume tool.

oc-session finds OpenCode SQLite databases across OS-specific data locations, lists root sessions by latest activity, supports keyword search across session metadata and previews, and resumes the selected session from any directory.

Install

cargo install oc-session

From source:

cargo install --git https://github.com/Shane0xM/oc-session

Install the optional bundled OpenCode agent skill:

oc-session skill install

Usage

oc-session                 # interactive picker
oc-session --search project # filtered picker
oc-session search project   # filtered picker
oc-session search api --no-tui
oc-session recent -l 20
oc-session recent --json
oc-session last --print
oc-session resume ses_...
oc-session print ses_...
oc-session copy ses_...
oc-session scan
oc-session scan --include "~/Library/Mobile Documents"
oc-session doctor
oc-session skill install

Search

Default search matches session-focused fields:

session id, title, agent, model, project name, recent message preview

Directory and path fields are searched only when the query looks path-like, for example:

/project
~/work
.local/share
path:data-services

This keeps short project names from matching every session that merely happened to run under a similarly named directory.

Key Bindings

Enter       resume selected session
Esc         clear search, or quit when search is empty
Ctrl+C      quit
Ctrl+Y      copy selected resume command
Ctrl+U      clear search
Ctrl+A/E    move search cursor to start/end
Ctrl+W      delete previous word
Arrow keys  move selection or search cursor
Home/End    move search cursor to start/end
Delete      delete character under search cursor
Backspace   delete character before search cursor

The default resume command is:

opencode {directory} --session {session_id}

The default command is executed without a shell. Custom resume_command values are shell-executed after placeholder values are shell-quoted.

Config

Optional config path:

~/.config/oc-session/config.toml

Example:

resume_command = 'opencode {directory} --session {session_id}'
limit = 500

[paths]
include = []
exclude = []

[ui]
show_directory = true
show_agent = true
show_model = false

Data Sources

The CLI discovers opencode*.db files in known OpenCode data locations, including XDG data directories and common macOS, Linux, and Windows equivalents. Default discovery is intentionally shallow for speed and to avoid expensive cloud-drive walks. Use oc-session scan --include <PATH> to search additional directories or direct database paths.

Agent Skill

This crate includes an optional OpenCode skill for agents working on oc-session.

The source skill lives at:

skills/oc-session/SKILL.md

Install the bundled skill into your global OpenCode skills:

oc-session skill install

This writes to:

~/.config/opencode/skills/oc-session/SKILL.md

Useful skill commands:

oc-session skill path
oc-session skill print
oc-session skill install --force

Restart OpenCode after installing the skill so it can be discovered.