automaker/docs/terminal.md

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+D	Split terminal right (horizontal split)
Alt+S	Split terminal down (vertical split)
Alt+W	Close current terminal

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)