headquarter/openspec/changes/archive/2026-06-12-completed-changes-archive/multi-session-terminal-ux/proposal.md at 38d116dcf746be1608246bed94de45cef8d1c4d5

Files

T

Developer 8c1948d226 chore: archive final 4 completed OpenSpec changes

Move the following completed changes from openspec/changes/ to
openspec/changes/archive/2026-06-12-completed-changes-archive/:
- multi-session-terminal-ux
- reorganize-long-files
- working-copies
- workspace-first-ui

Update parent and archive .pi-map*.md indexes to reflect the move and
remove the transient active-changes-archive grouping.

openspec/changes/ now contains only the archive/ directory.

2026-06-12 21:11:11 +00: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