Terminal
Integrated terminal with Ghostty, WezTerm, xterm.js, and SwiftTerm backends
Overview#
Agentastic includes a powerful integrated terminal with four backend options:
- Ghostty - GPU-accelerated terminal rendering via Metal (recommended)
- WezTerm - GPU-accelerated, OpenGL-rendered emulator with font ligatures (HarfBuzz)
- xterm.js - WebGL-accelerated backend that runs in a WebView
- SwiftTerm - Pure Swift terminal implementation
Opening the Terminal#
- Press Cmd+J to toggle the Utility Area
- Click the Terminal tab in the Utility Area
- New terminal tabs open with your default shell
Terminal Backends#
Ghostty (Recommended)#
Ghostty provides GPU-accelerated rendering using Metal, delivering excellent performance and smooth scrolling. It's the default backend on supported systems.
Features:
- GPU-accelerated rendering
- Smooth scrolling
- Native macOS integration
- Fast text rendering
SwiftTerm#
SwiftTerm is a pure Swift implementation that works on all supported systems.
Features:
- Native Swift implementation
- Reliable fallback option
- Good compatibility
WezTerm#
WezTerm is a powerful, GPU-accelerated emulator (OpenGL) popular for its rendering quality and multiplexing.
Features:
- GPU-accelerated rendering
- Font ligatures via HarfBuzz
- Smooth resizing during splits and drag-selection
xterm.js#
xterm.js runs in a WebView with WebGL GPU-accelerated rendering, full theme sync, and auto-resize.
Features:
- WebGL-accelerated rendering
- Clickable URL detection
- Theme synced with the editor
Switching Backends#
- Open Settings (Cmd+,)
- Navigate to Terminal
- Select your preferred backend under Terminal Emulator
Configuration#
Shell Selection#
Choose your shell in Settings > Terminal:
- System Default - Uses your login shell
- Bash - GNU Bash
- Zsh - Z Shell (macOS default)
- Custom - Specify a custom shell path
Appearance#
| Setting | Description |
|---|---|
| Font | Terminal font face |
| Font Size | Text size in points |
| Cursor Style | Block, underline, or bar |
| Cursor Blink | Enable/disable blinking |
Option as Meta Key#
Enable Option as Meta Key to use the Option key as a Meta modifier in terminal applications like Emacs.
Multiple Terminals#
Create multiple terminal tabs for different tasks:
- Click the + button in the terminal tab bar
- Each terminal maintains its own shell session
- Right-click tabs for more options
Clickable Links#
Web URLs are clickable in every terminal backend, and supported backends also detect file paths — no modifier key required:
- Hover over a link to see the pointer switch to a hand cursor
- Click a file path to open it in the editor
Web URLs support placement modifiers:
| Gesture | Opens in |
|---|---|
| Click | GitHub pull request URLs open in the native pull request page when a matching account is available; other URLs use your configured default |
| Option+click | The built-in web browser as a tab in the source editor without creating a split, including for pull request URLs |
| Cmd+click | Your external browser |
File links use the same placement controls:
| Gesture | Opens in |
|---|---|
| Click | A trailing editor split when the editor has a single pane; otherwise, a tab in the editor that owns the terminal |
| Option+click | A full editor tab in the editor that owns the terminal, without creating a split |
| Cmd+click | The file's default external macOS application |
For in-app opens, Agentastic focuses an existing file tab instead of opening a duplicate. For remote terminals, Cmd+click downloads a temporary snapshot for the external application; edits to that snapshot do not sync back to the remote workspace. Container file links open only when the same path resolves to a file visible on the Mac; Cmd+click opens that host-visible file externally.
Web URL modifiers work across Ghostty, WezTerm, xterm.js, and SwiftTerm. Ghostty, WezTerm, and SwiftTerm also detect printed file paths. In xterm.js, file placement modifiers apply to explicit file:// hyperlinks (for example, OSC 8 links); ordinary file-path text is not automatically linkified.
Clickable links are on by default. Toggle them under Settings > Terminal > Links & Previews > Open Links & Files on Click — with links off, a plain click passes straight through to the terminal application, so mouse-aware TUIs keep receiving clicks.
Image Hover Previews#
Image paths and agent-attached images printed to the terminal preview inline instead of leaving you to open them elsewhere:
- Hover a recognized image path (PNG, JPEG, GIF, WebP, HEIC, and other common formats) and a preview appears after a brief pause
- Attachment tags some agents print — like
[image]or[image#2]— preview immediately, no hover delay - Click a preview to expand and pin it in place; press Esc or click elsewhere to dismiss it
This makes it easy to check a screenshot an agent just saved, or an image it references, without leaving the terminal. Image previews are on by default; toggle them under Settings > Terminal > Links & Previews > Image Previews.
File Hover Previews#
Hovering a source reference an agent printed — src/main.swift:42, main.swift:42:9, or a plain path — shows the code around that line without opening the file:
- The excerpt is syntax-highlighted using your current theme and centered on the referenced line
- When the file has uncommitted changes, the preview shows the working-tree hunk at that line as a diff instead of plain source
- Previews are bounded — large, binary, and non-UTF-8 files are skipped rather than loaded
- Click through to open the file for real, using the same placement modifiers as clickable links
The same previews appear for file references inside agent chat transcripts. Paths are resolved against the workspace root and every component is opened without following symlinks, so a repository-controlled link cannot pull in a file from outside the workspace. Remote and container terminals resolve against their own host.
File previews are on by default; toggle them under Settings > Terminal > Links & Previews > Enable File Preview.
Copying and Selection#
Selecting text in a terminal copies it as usual with Cmd+C. If you prefer the terminal-native behavior where a selection lands on the clipboard immediately, enable Settings > Terminal > Auto-copy Selected Text. It applies to all four backends — Ghostty, WezTerm, xterm.js, and SwiftTerm — and is off by default.
Microphone & Voice Tools#
Command-line tools running inside the terminal — such as Claude Code's voice dictation — can use your Mac's microphone. The first time a tool requests it, macOS prompts for permission; the grant belongs to Agentastic, so any terminal pane inherits it.
Shell Integration#
Agentastic automatically integrates with your shell to provide enhanced features.
Features#
- Tab titles - Shows current directory or running command
- Working directory tracking - Navigator follows terminal location
- Command notifications - Get notified when long-running commands complete
- Process tracking - See running processes in the activity indicator
How It Works#
When shell integration is enabled, Agentastic installs hooks into your shell:
- Bash: Sources
.codeedit_shell_integration.bash - Zsh: Sources integration scripts for different startup files
These hooks use preexec and precmd patterns to communicate with Agentastic.
Enabling/Disabling#
Toggle shell integration in Settings > Terminal > Shell Integration.
Agent-Aware Terminals#
Terminals are associated with their agent context:
- Each agent has its own set of terminal tabs
- Switching agents switches to that agent's terminals
- Terminal state (scrollback, running processes) is preserved per agent
- New terminals open in the current agent's directory
This means you can have different terminal sessions for different branches without interference.
Terminal as Chat#
Any live agent terminal running Claude Code or Codex can be viewed as a chat conversation instead of raw terminal output — and switched back at any time without interrupting the agent.
Chat view reads the same session your terminal shows and renders it as a conversation:
- Your prompts appear as chat bubbles
- The agent's prose is shown inline
- Tool calls collapse into compact work cards you can expand
- Finished turns fold away behind a "Worked for…" summary
- Interactive menus become clickable choice buttons — selecting one drives the live terminal underneath
Because chat view is just a different lens on the live session, nothing changes about how the agent runs; flip between Terminal and Chat freely.
Switching to Chat#
Toggle Terminal | Chat from the terminal options menu (the slider icon in the tab toolbar), by right-clicking the terminal tab, or from the Inspector's Terminal card.
Terminal Options Menu#
Terminal tabs have an options menu — matching the editor's — available from the tab toolbar and by right-clicking the tab:
| Action | Description |
|---|---|
| Resume agent session | Re-runs the agent's latest/current-directory resume command (for example, claude --resume). Enabled once a supported agent session is detected. |
| Terminal / Chat | Switch between the raw terminal and the chat view. |
| Rename… | Give the tab a custom name; clear it to restore the automatic name. |
| Copy Working Directory | Copy the terminal's current directory. |
| Copy Terminal Content | Copy the full scrollback as plain text. |
| Reveal in Finder | Open the working directory in Finder (local terminals). |
Resuming Agents You Start Yourself#
Agentastic detects agents you launch by hand in a terminal — not just the ones started from Agent Home. When you type an agent command, shell integration recognizes it and remembers the exact invocation, so the session becomes a first-class agent session:
- Resume in the terminal options menu re-runs the provider's latest/current-directory continuation command (for example,
claude --resume). Agentastic does not yet persist a provider-native session ID, so this shortcut is not guaranteed to select a specific older session. - The Inspector's Terminal card surfaces the same resume shortcut.
- Activity indicators treat the terminal as a live agent session.
Recognition covers the common agent CLIs — including claude, codex, pool, interpreter, gemini, qwen, opencode, goose, aider, amp, copilot, droid, mimo, qodercli, openclaude, ante, omp, and openclaw — and also sees through package runners, so npx @anthropic-ai/claude-code@latest or bunx @openai/codex@latest are matched too. Launch flags, model selections, thinking level, and environment-backed modes are preserved when the session is resumed.
Note: This relies on shell integration. Keep it enabled in Settings → Terminal → Shell Integration.
Container Terminals#
When an agent uses a Docker container, terminals run inside the container:
- Commands execute in the container environment, not on your host
- The working directory is
/workspace(your mounted worktree) - Your shell configuration is available if Copy Shell Config is enabled
- Terminal sessions use
docker execto connect to the running container
Container terminals provide isolation while maintaining a seamless experience. See Docker Containers for details.
Keyboard Shortcuts#
| Action | Shortcut |
|---|---|
| New Terminal Tab | Cmd+T |
| Split Side by Side | Cmd+D |
| Split Top and Bottom | Cmd+Shift+D |
| Toggle Utility Area | Cmd+Option+J |
| Close Terminal | Delete (when focused) |
Input Features#
- Copy/Paste - Standard clipboard integration
- Option as Meta - Use Option key as Meta in vim, emacs, etc.
- Shift+Enter - Send literal newline
- Ctrl+J - Alternative newline input (Ghostty)
- Image pasting - Paste images as file paths
Theme Integration#
The terminal automatically uses your current Agentastic theme:
- ANSI colors match your color scheme
- Background and text colors sync with the editor
- Cursor color follows your selection
Tips#
- Use Ghostty for best performance on Apple Silicon
- Shell integration enables command completion notifications
- Multiple tabs are great for parallel tasks (build, tests, server)
- Agent terminals keep your contexts separate
Related Comparisons#
If you're choosing between Agentastic's terminal and a standalone terminal app:
- Agentastic vs Warp — embedded terminal vs AI-native terminal
- Best Warp alternative — when you need something other than Warp
- Best Ghostty alternative — Ghostty terminal alternatives
- Best iTerm alternative — moving on from iTerm2