mirror of
https://github.com/AutoMaker-Org/automaker.git
synced 2026-01-30 22:32:04 +00:00
8d578558ff
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
124 lines
3.7 KiB
Markdown
124 lines
3.7 KiB
Markdown
# 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 + Scroll` to 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:
|
|
|
|
1. **Frontend** (`apps/ui`): xterm.js terminal emulator with WebGL rendering
|
|
2. **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
|
|
|
|
1. Ensure the server is running (`npm run dev:server`)
|
|
2. Check that port 3008 is available
|
|
3. 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)
|