Shell App
Shell App
Shell App
The Shell App is a terminal application for FlowState that provides a full-featured terminal experience with session persistence, context-aware sessions, and seamless integration with the FlowState ecosystem. Built with xterm.js and WebSocket connectivity, it supports both standalone operation and embedded use within other FlowState applications.
Key Features
- xterm.js Terminal: Full-featured terminal emulator with proper cursor, colors, and input handling
- Session Management: Create, rename, close, and delete terminal sessions with persistence
- Context-Aware Sessions: Associate sessions with projects, milestones, and tasks
- WebSocket Connectivity: Real-time bidirectional communication with shell server
- Session Persistence: Sessions are stored in RxDB for recovery and cross-device access
- Multi-Session Support: Run multiple terminal sessions simultaneously
- Bottom Panel Integration: Embed terminal in FlowState's bottom panel system
- Electron Support: Automatic detection and integration with Electron shell server
Target Users
| User Type | Primary Use Cases |
|---|---|
| Developers | Run commands, view logs, execute scripts |
| DevOps Engineers | Server administration, deployment tasks |
| System Administrators | System management, monitoring |
| Power Users | Command-line operations within FlowState |
Quick Links
- Features & Capabilities - Detailed feature documentation
- Getting Started - Set up and configure the app
Getting Started
Navigation
The app uses a simple three-page structure:
- Terminal (
/terminal) - Main terminal view with session management - Settings (
/settings) - Terminal configuration options - About (
/about) - Version and build information
Creating a Terminal Session
- Click the "New Terminal" button or use the keyboard shortcut
Ctrl+Shift+` - Configure session options:
- Display name for easy identification
- Shell server URL (defaults to
ws://localhost:3001) - Context hierarchy (Workspace, Project, Milestone, Task)
- Click "Connect" to create the session
- Terminal is ready for use
Managing Sessions
- Select Session: Click on a session in the session list to switch to it
- Rename Session: Right-click or use the rename action on a session
- Close Session: Terminates the shell process but keeps history
- Delete Session: Removes the session entirely
Keyboard Shortcuts
| Action | Windows/Linux | macOS |
|---|---|---|
| New Terminal | Ctrl+Shift+` | Cmd+Shift+` |
| Clear Terminal | Ctrl+K | Cmd+K |
| Focus Terminal | Ctrl+` | Cmd+` |
App Identity
| Property | Value |
|---|---|
| Package | @epicdm/flowstate-app-shell |
| Base Path | /shell |
| Icon | Terminal |
| Color | #10b981 (emerald-500) |
Related Packages
- @epicdm/flowstate-shell - Shell UI components (Terminal, TerminalProvider)
- @epicdm/flowstate-shell-core - Core terminal adapter interfaces
- @epicdm/flowstate-shell-server - WebSocket shell server
- @epicdm/flowstate-app-framework - App container framework