95 lines
3.5 KiB
Markdown
95 lines
3.5 KiB
Markdown
# opencode-session-manager
|
|
|
|
*USE AT YOUR OWN RUSK*
|
|
|
|
⚠️ This is entirely vibe coded and mostly untested. It should backup yout 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
|
|
# Install dependencies With mise
|
|
mise install
|
|
|
|
# Install dependencies and run
|
|
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.
|
|
|
|
## Layout
|
|
|
|
The UI has two panels:
|
|
|
|
- **Left — All Projects**: a list of your OpenCode projects with active session counts
|
|
- **Right — Sessions**: sessions for the selected project, with a filter bar at the top
|
|
|
|
## 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 workspace within that project
|
|
5. Click Confirm or press `Enter`
|
|
|
|
A timestamped backup is created automatically before the first write operation in a session: `opencode-YYYYMMDD-HHMMSS.db`
|
|
|
|
Copy duplicates the session and all related records (messages, parts, todos). Move updates the session's project/workspace in place.
|
|
|
|
## 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 removes all related records (messages, todos, etc). A backup is created automatically before the first delete.
|
|
|
|
## 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.
|
|
|
|
## Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `main.py` | Entry point |
|
|
| `app.py` | Textual TUI — layout, keybindings, UI logic |
|
|
| `database.py` | SQLite queries — sessions, move, copy, delete, backup |
|