# 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](https://opencode.ai) sessions — move, copy, or delete sessions across projects without writing SQL.

![screenshot](assets/opencode-session-manager.png)

## Requirements

- Python 3.11+
- [Textual](https://github.com/Textualize/textual) (`pip install -r requirements.txt`)

A `mise.toml` is included if you use [mise](https://mise.jdx.dev) — 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

```bash
# 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 |