106 lines
4.7 KiB
Markdown
106 lines
4.7 KiB
Markdown
# 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.
|
|
|
|
|
|
|
|
## 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 |
|