opencode-session-manager/README.md

opencode-session-manager

USE AT YOUR OWN RISK

⚠️ This is entirely vibe coded and mostly untested. It should backup your database before changing anything, but you should make your own backup first ⚠️

A terminal UI for managing OpenCode sessions — move, copy, or delete sessions across projects without writing SQL.

Requirements

• Python 3.11+
• Textual (pip install -r requirements.txt)

A mise.toml is included if you use mise — it pins Python 3.14 and SQLite 3.51. Run mise install to set up the environment.

OpenCode stores its data in an SQLite database, usually at ~/.local/share/opencode/opencode.db.

Running

# With mise (installs Python, SQLite, and dependencies)
mise install && pip install -r requirements.txt
python main.py /path/to/opencode.db

# Without mise
pip install -r requirements.txt
python main.py /path/to/opencode.db

If no path is given it looks for opencode.db in the current directory. If the database is not found, an error is shown in the UI and the app exits with a non-zero status code.

Layout

The UI has two panels:

• Left — All Projects: a list of your OpenCode projects, sorted alphabetically by directory name, with active session counts
• Right — Sessions: sessions for the selected project, sorted newest first, with a filter bar at the top

Select a project from the left panel to load its sessions. The session panel shows ID, title, project, workspace, message count, and creation date.

Keybindings

Key	Action
Tab	Move focus between project list and session table
f	Focus the filter input
Enter (in filter)	Return focus to session table
Escape	Clear filter if active, otherwise clear selection
Space	Select / deselect the highlighted session
m	Move selected sessions to another project
c	Copy selected sessions to another project
d	Delete selected sessions (with confirmation)
a	Toggle visibility of archived sessions
b	Create a manual database backup
r	Refresh all data from the database
q	Quit

Selecting Sessions

Navigate the session table with the arrow keys. Press Space to toggle selection on the highlighted row. The selection count is shown at the bottom of the session panel. Selection is cleared when you switch projects.

Use f to filter sessions by title or slug (case-insensitive). Filtering and selection work together — you can filter, select matching sessions, clear the filter, and the selections persist.

Move / Copy

1. Select one or more sessions with Space
2. Press m (move) or c (copy)
3. Choose a destination project from the dropdown (sorted alphabetically, current project excluded)
4. Optionally choose a destination workspace
5. Click Confirm or press Enter

A timestamped backup is created automatically before the first write operation: opencode-YYYYMMDD-HHMMSS.db, written next to the source database.

Move updates the session's project_id (and optionally workspace_id) in place. All related records stay attached to the session unchanged.

Copy duplicates the session and all related records (messages, message parts, todos) into the destination project. Copied sessions get new IDs. The original is not modified.

Note: copied session IDs will not match OpenCode's native ID format. The sessions will work normally in the app but will look different in the database.

Delete

1. Select one or more sessions with Space
2. Press d
3. Review the list of sessions to be deleted in the confirmation dialog
4. Click Delete to confirm, or Cancel / Escape to abort

Deletion is permanent and cascades to all related records (messages, parts, todos). A backup is created automatically before the first delete in a session.

Archived Sessions

OpenCode can archive sessions. By default they are hidden. Press a to show them alongside active sessions — the session panel header will update to indicate archived mode is on. Archived sessions can be moved, copied, or deleted like any other session.

Backups

A backup is created automatically the first time you perform any write operation (move, copy, or delete) in a given run of the app. You can also create one manually at any time with b. Backups are timestamped copies of the database file placed in the same directory as the source: opencode-YYYYMMDD-HHMMSS.db.

Files

File	Purpose
main.py	Entry point, CLI argument handling
app.py	Textual TUI — layout, keybindings, UI logic
database.py	SQLite queries — sessions, move, copy, delete, backup