headquarter/openspec/changes/multi-session-terminal-ux/proposal.md at c353bceb971a2cf0e383172370c5def347b058fe

Files

T

alex 62d1bdc462 feat: multi-session terminal frontend UI + tests (PR 3)

- Add TerminalSessionTabs component with status dots, rename, close, max-5 limit
- Add 7 component tests for tab rendering, selection, close, rename
- TerminalComponent: sessionId prop, forwardRef with fit() method
- TerminalPage: multi-session orchestration, tab switching, auto-create default
- Fullscreen mode: Alt+Shift+F toggle, auto-hide tabs, Esc exit
- Keyboard shortcuts: Alt+Shift+N/W/ArrowLeft/ArrowRight/R
- Add CSS for tabs, fullscreen, mobile responsive
- Update useTerminalSessions hook for session CRUD
- terminal_manager.py: lookup by internal session_id fallback

Quality gates: tsc --noEmit clean, vitest (7/7 new tests passed), pytest (182 passed)

2026-05-28 13:35:45 +02:00

2.0 KiB

Raw Blame History

Why

Currently, each tool instance (e.g., pi-agent, code-server) supports exactly one terminal session. Users who want to run multiple concurrent tasks (e.g., a long-running build in one pane, an editor in another, and a shell for quick commands) must open multiple tool instances or use tmux/screen inside a single session. This is inefficient and confusing.

Additionally, the web terminal lacks basic usability features found in modern terminal emulators: fullscreen mode, detachable panes, session tabs, and keyboard shortcuts for common actions.

What Changes

Backend: Allow multiple TerminalSession objects per ToolInstance, each with a unique session_id
Backend: Update TerminalManager to track and route multiple sessions per instance
Backend: Update terminal WebSocket protocol to include session_id in connection URL or message
Frontend: Add session tabs/management UI (create new session, switch between sessions, close sessions)
Frontend: Add fullscreen mode for the terminal
Frontend: Add keyboard shortcuts for session management (Ctrl+Shift+N new session, etc.)
Frontend: Session list panel showing active sessions per instance

Capabilities

New Capabilities

multi-session-terminal: Multiple independent terminal sessions per tool instance
terminal-fullscreen: Fullscreen terminal mode
terminal-session-management: Create, switch, rename, and close terminal sessions

Modified Capabilities

tool-terminal: Extend WebSocket protocol and UI to support multiple sessions per instance
terminal-session-lifecycle: Session creation, naming, and cleanup for multi-session model

Impact

Backend: TerminalManager, TerminalSession, api/terminal.py, database schema (session tracking)
Frontend: TerminalComponent, terminal.tsx, new TerminalSessionTabs, TerminalSessionManager
Protocol: WebSocket message format changes (add session_id field)
Database: New or extended table to track terminal sessions per instance

2.0 KiB Raw Blame History

Why