w33ble/opencode-session-manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update readme, fix typos and try to increase clarity

Browse Source
This commit is contained in:
Joe Fleming
2026-03-08 14:28:22 -06:00
parent c768caa025
commit f072120961
1 changed files with 26 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
README.md
View File

@@ -1,12 +1,12 @@
# opencode-session-manager # opencode-session-manager
*USE AT YOUR OWN RUSK* *USE AT YOUR OWN RISK*
⚠️ This is entirely vibe coded and mostly untested. It should backup yout database before changing anything, but you should make your own backup first ⚠️ ⚠️ 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. A terminal UI for managing [OpenCode](https://opencode.ai) sessions — move, copy, or delete sessions across projects without writing SQL.
![iscreenshot](assets/opencode-session-manager.png) ![screenshot](assets/opencode-session-manager.png)
## Requirements ## Requirements
@@ -20,22 +20,25 @@ OpenCode stores its data in an SQLite database, usually at `~/.local/share/openc
## Running ## Running
```bash ```bash
# Install dependencies With mise # With mise (installs Python, SQLite, and dependencies)
mise install mise install && pip install -r requirements.txt
python main.py /path/to/opencode.db
# Install dependencies and run # Without mise
pip install -r requirements.txt pip install -r requirements.txt
python main.py /path/to/opencode.db python main.py /path/to/opencode.db
``` ```
If no path is given it looks for `opencode.db` in the current directory. 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 ## Layout
The UI has two panels: The UI has two panels:
- **Left — All Projects**: a list of your OpenCode projects with active session counts - **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, with a filter bar at the top - **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 ## Keybindings
@@ -65,12 +68,16 @@ Use `f` to filter sessions by title or slug (case-insensitive). Filtering and se
1. Select one or more sessions with `Space` 1. Select one or more sessions with `Space`
2. Press `m` (move) or `c` (copy) 2. Press `m` (move) or `c` (copy)
3. Choose a destination project from the dropdown (sorted alphabetically, current project excluded) 3. Choose a destination project from the dropdown (sorted alphabetically, current project excluded)
4. Optionally choose a workspace within that project 4. Optionally choose a destination workspace
5. Click Confirm or press `Enter` 5. Click Confirm or press `Enter`
A timestamped backup is created automatically before the first write operation in a session: `opencode-YYYYMMDD-HHMMSS.db` A timestamped backup is created automatically before the first write operation: `opencode-YYYYMMDD-HHMMSS.db`, written next to the source database.
Copy duplicates the session and all related records (messages, parts, todos). Move updates the session's project/workspace in place. **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 ## Delete
@@ -79,16 +86,20 @@ Copy duplicates the session and all related records (messages, parts, todos). Mo
3. Review the list of sessions to be deleted in the confirmation dialog 3. Review the list of sessions to be deleted in the confirmation dialog
4. Click Delete to confirm, or Cancel / `Escape` to abort 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. 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 ## 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. 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 ## Files
| File | Purpose | | File | Purpose |
|------|---------| |------|---------|
| `main.py` | Entry point | | `main.py` | Entry point, CLI argument handling |
| `app.py` | Textual TUI — layout, keybindings, UI logic | | `app.py` | Textual TUI — layout, keybindings, UI logic |
| `database.py` | SQLite queries — sessions, move, copy, delete, backup | | `database.py` | SQLite queries — sessions, move, copy, delete, backup |