opencode-session-manager/PLAN.md

Session Mover TUI - Project Plan

Overview

A Python Textual TUI application to visually manage OpenCode sessions (move/copy between projects and workspaces) without writing SQL.

Database Schema (opencode.db)

Core Tables

• session: id, project_id, workspace_id, parent_id, slug, directory, title, version, time_created, time_updated, time_archived
• project: id, worktree, name, vcs
• workspace: id, project_id, branch, type, name, directory

Related Data (cascade on session delete)

• message → part: Conversation content
• todo: Session todos
• session_share: Share links

Goals

1. Visual browsing - Tree view of Projects → Workspaces → Sessions
2. Easy session movement - Drag-and-drop or keyboard-driven moving between projects
3. Batch operations - Select multiple sessions and move them together
4. Safety - Confirmation dialogs, preview SQL, automatic backup
5. Discoverability - Hotkeys always visible, clear status indicators

Key Features

Display

• Split pane: Left = Projects/Workspaces tree, Right = Sessions table
• Sessions table columns: Title, Project, Workspace, Messages, Created, Archived status
• Filter/search box for sessions
• Toggle for archived sessions (hidden by default)
• Selected sessions highlighted/checked

Navigation

• Mouse: Click to select, double-click to open details
• Keyboard: Tab/Shift+Tab between panels, arrows to navigate
• Hotkeys always visible at bottom

Actions

• Backup (B) - Create timestamped DB copy
• Move (M) - Move selected sessions to another project/workspace
• Copy (C) - Duplicate sessions to another project
• Show archived (A) - Toggle archived sessions visibility
• Refresh (R) - Reload data from database
• Quit (Q)

Move/Copy Dialog

• Dropdown selectors for destination Project (required) and Workspace (optional)
• Preview of affected sessions and SQL statements that will execute
• Confirmation before executing
• Summary after completion

Backup Strategy

• Before first write operation, create backup: opencode-YYYYMMDD-HHMMSS.db
• Location: same directory as source DB
• Only one backup per session (don't spam)
• User can manually backup at any time with B

Technical Implementation

Stack

• Python 3.9+
• Textual (TUI framework)
• sqlite3 (stdlib)

Project Structure

session-mover/
├── main.py              # Application entry point
├── app.py               # Textual App class
├── database.py          # DB connection, queries, models
├── widgets/
│   ├── project_tree.py # Projects/Workspaces tree
│   ├── sessions_table.py # Sessions data table
│   └── dialogs.py      # Move/Copy dialogs
├── utils.py             # Backup, formatting helpers
└── requirements.txt

Database Operations

Move session:

UPDATE session SET project_id = ? WHERE id = ?;
-- Optionally: UPDATE session SET workspace_id = ? WHERE id = ?;

Copy session:

BEGIN TRANSACTION;
-- Copy session with new UUID
INSERT INTO session (...)
SELECT ... FROM session WHERE id = ?;
-- Copy related records with new IDs
INSERT INTO message ... SELECT ... FROM message WHERE session_id = ?;
INSERT INTO part ... SELECT ... FROM part WHERE session_id = ?;
INSERT INTO todo ... SELECT ... FROM todo WHERE session_id = ?;
INSERT INTO session_share ... SELECT ... FROM session_share WHERE session_id = ?;
COMMIT;

Validation checks:

• Target project exists
• If workspace specified: exists and belongs to target project
• Sessions exist and aren't already in target

Implementation Steps

1. Setup - Create project structure, requirements.txt with textual
2. Database layer - database.py with connection, session/project/workspace queries
3. TUI skeleton - Basic Textual app with split layout
4. Project tree widget - Load projects/workspaces, show hierarchy
5. Sessions table - Load sessions with counts, implement filtering
6. Selection - Multi-select mechanism (checkboxes or highlight+shift)
7. Action dialogs - Move/Copy dialog with preview
8. Backup system - Before first write operation
9. SQL execution - Safe updates with transactions
10. Polish - Status messages, error handling, hotkeys display

Open Questions (Resolved)

• Use Textual: Yes
• Show hotkeys: Always at bottom
• Include archived: hidden by default, toggle显示
• Single DB path: Default opencode.db in current dir, --db flag to override
• Copy command: Yes, duplicate sessions
• Batch move: All selected move to same destination
• Confirmation needed: Yes, with SQL preview
• Backup: Timestamped copy before first write
• Workspace on move: Optional - can keep current or select new

Success Criteria

• Can browse all sessions with project/workspace context
• Can select session(s) and move them to different project with one keystroke
• Can see exactly what SQL will run before confirming
• Backup created automatically before any change
• All operations display clear success/error feedback
• No need to write SQL manually