7ddd9f8be1
- Implemented spatial navigation between terminal panes using directional shortcuts (Ctrl+Alt+Arrow keys). - Improved session handling by ensuring stale sessions are automatically removed when the server indicates they are invalid. - Added customizable keyboard shortcuts for terminal actions and enhanced search functionality with dedicated highlighting colors. - Updated terminal themes to include search highlighting colors for better visibility during searches. - Refactored terminal layout saving logic to prevent incomplete state saves during project restoration.
3.7 KiB
Terminal
The integrated terminal provides a full-featured terminal emulator within Automaker, powered by xterm.js.
Configuration
Configure the terminal via environment variables in apps/server/.env:
Disable Terminal Completely
TERMINAL_ENABLED=false
Set to false to completely disable the terminal feature.
Password Protection
TERMINAL_PASSWORD=yourpassword
By default, the terminal is not password protected. Add this variable to require a password.
When password protection is enabled:
- Enter the password in Settings > Terminal to unlock
- The terminal remains unlocked for the session
- You can toggle password requirement on/off in settings after unlocking
Keyboard Shortcuts
When the terminal is focused, the following shortcuts are available:
| Shortcut | Action |
|---|---|
Alt+T |
Open new terminal tab |
Alt+D |
Split terminal right (horizontal split) |
Alt+S |
Split terminal down (vertical split) |
Alt+W |
Close current terminal |
These shortcuts are customizable via the keyboard shortcuts settings (Settings > Keyboard Shortcuts).
Split Pane Navigation
Navigate between terminal panes using directional shortcuts:
| Shortcut | Action |
|---|---|
Ctrl+Alt+ArrowUp (or Cmd+Alt) |
Move focus to terminal pane above |
Ctrl+Alt+ArrowDown |
Move focus to terminal pane below |
Ctrl+Alt+ArrowLeft |
Move focus to terminal pane on left |
Ctrl+Alt+ArrowRight |
Move focus to terminal pane on right |
The navigation is spatially aware - pressing Down will move to the terminal below your current one, not just cycle through terminals in order.
Global shortcut (works anywhere in the app):
| Shortcut | Action |
|---|---|
Cmd+`` (Mac) / Ctrl+`` (Windows/Linux) |
Toggle terminal view |
Features
Multiple Terminals
- Create multiple terminal tabs using the
+button - Split terminals horizontally or vertically within a tab
- Drag terminals to rearrange them
Theming
The terminal automatically matches your app theme. Supported themes include:
- Light / Dark / System
- Retro, Dracula, Nord, Monokai
- Tokyo Night, Solarized, Gruvbox
- Catppuccin, One Dark, Synthwave, Red
Font Size
- Use the zoom controls (
+/-buttons) in each terminal panel - Or use
Cmd/Ctrl + Scrollto zoom
Scrollback
- The terminal maintains a scrollback buffer of recent output
- Scroll up to view previous output
- Output is preserved when reconnecting
Architecture
The terminal uses a client-server architecture:
- Frontend (
apps/ui): xterm.js terminal emulator with WebGL rendering - Backend (
apps/server): node-pty for PTY (pseudo-terminal) sessions
Communication happens over WebSocket for real-time bidirectional data flow.
Shell Detection
The server automatically detects the best shell:
- WSL: User's shell or
/bin/bash - macOS: User's shell, zsh, or bash
- Linux: User's shell, bash, or sh
- Windows: PowerShell 7, PowerShell, or cmd.exe
Troubleshooting
Terminal not connecting
- Ensure the server is running (
npm run dev:server) - Check that port 3008 is available
- Verify the terminal is unlocked
Slow performance with heavy output
The terminal throttles output at ~60fps to prevent UI lockup. Very fast output (like cat on large files) will be batched.
Shortcuts not working
- Ensure the terminal is focused (click inside it)
- Some system shortcuts may conflict (especially Alt+Shift combinations on Windows)