Terminal

Orca's terminal is the same xterm.js-based terminal VS Code uses, with a few additions tuned for AI-agent workflows.

Panes & tabs

Terminals are just tabs — see Tabs, panes & split layouts. Splitting a terminal pane gives you two shells side by side.

Agent terminal tabs show the agent identity plus live state: working, waiting for input, completed, or completed-but-unread. For Claude and Codex, tab titles can also show the AI Vault conversation name (custom title / thread name) when Orca can map the pane to that session — manual renames still win.

Desktop Orca can keep inline images in up to two mounted hidden panes per window while their output stays continuous. A pane needs at least one placed image when you switch away to qualify. A Kitty image that is still decoding or has only been uploaded can be lost, and recovery after a delivery gap or a cold reopen can restore text without graphics.

Resource Manager terminals

The Resources view works in both the desktop app and the paired web client while its page is visible. The separate PTYs view manages local desktop terminals; a web client cannot end those terminals.

Refresh discovers terminals created since the previous observation. End requires a host that can check the selected terminal's identity, agent ownership, and attachments before stopping it. An older host, ambiguous ownership, or lost contact cannot establish a safe End result.

If End is unavailable because the terminal host lacks support, end the terminal manually from its terminal tab or on its host.

A confirmed End removes saved terminal history just like Close. If a newer terminal replaces the selected one while cleanup is pending, that newer terminal remains in the inventory and keeps its history.

TUI clipboard (OSC 52)

Many terminal UIs (Zellij, tmux, Neovim, fzf, Grok) copy via OSC 52 instead of OS clipboard APIs. Orca allows those writes by default so copy-from-remote/TUI works over SSH the same way as locally.

Toggle: Settings → Terminal → Allow TUI Clipboard Writes (OSC 52).

Cmd-F opens find-in-scrollback. Match highlighting, case, regex, and match navigation are all supported.

A plain click on a terminal link (HTTP/OSC 8 URL, file path, workspace, terminal, or task handle) opens a compact action popover instead of navigating immediately. Local web links and links owned by a capability-verified paired runtime offer Orca Browser and System Browser; links from older runtimes stay system-only. SSH links whose host is routed follow link routing. When the host's SSH browsing is set to This device, they open in an Orca tab that browses from this device only while links open in Orca; otherwise they stay system-browser only. Web links also get Copy link, which copies the resolved URL (including hidden OSC 8 destinations) without closing the popover — file and workspace destinations stay unchanged. Cmd-click (macOS) / Ctrl-click (Windows / Linux) still opens directly, and Shift+Cmd / Shift+Ctrl-click still uses the link-routing alternate.

Previewable HTML file links can open in Orca from local, SSH, and paired-runtime workspaces; remote file rows also offer Download & open with default app. If a linked file is already open in a sibling workspace tab, Orca activates that tab instead of opening a duplicate. See HTML viewers.

Turn the popover off under Settings → Browser → Show terminal link actions. With it off, opening a link requires the modifier-click.

Copy terminal context

Right-click a terminal and choose Copy Context to copy a bounded transcript from that pane. Use it when you want to paste recent agent output into another tool without starting an Orca fork.

Pasted and dropped images

When you paste or drop a local image into a terminal, Orca shows it in the pane header. Hover over an image chip to see its thumbnail and path, or click to open the file in Orca. Each mounted pane keeps its four most recent images. Scroll the chip strip horizontally to reach older images in a narrow pane. Turn the chips off in Settings → Terminal → Pasted and dropped image previews.

Themes

Terminal color themes are configurable under Settings → Terminal. Orca ships a library of popular themes and lets you customize any of them.

Ghostty import

If you use Ghostty, Orca can import its theme, font, and cursor config on first launch. You can re-run the import later from Settings → Terminal → Import from Ghostty.

Warp theme import

If you've collected themes in Warp, click Import themes from Warp in the terminal-theme picker under Settings → Terminal to bring them in as Orca terminal themes. Orca scans Warp's theme directory for the current OS (~/.warp/themes on macOS, $XDG_DATA_HOME/warp-terminal/themes on Linux, %APPDATA%\warp\Warp\data\themes on Windows) and lets you pick which YAML themes to import. The button next to it, Import from YAML, takes the same picker and points it at any folder of Warp-format .yaml/.yml files — useful when you store themes outside the default location.

Imported themes appear alongside Orca's built-ins in the theme dropdown.

Terminal capabilities for tools

Orca desktop terminals render 24-bit color, OSC 8 hyperlinks, and inline raster images. The terminal's image renderer supports Kitty graphics, Sixel, and iTerm2 inline pictures when Settings → Terminal → Inline Images is enabled.

SignalMeaning
TERM_PROGRAM=OrcaIdentity of the direct Orca terminal. Preserve it when launching tools.
COLORTERM=truecolorPrograms can emit 24-bit color.
FORCE_HYPERLINK=1Orca can open OSC 8 hyperlinks. Tools that honor this environment variable can emit them.
ORCA_IMAGE_PROTOCOL=kittyStartup hint for newly opened terminals with inline images enabled and a supporting viewer. Kitty is the preferred encoder for raster images.

Prefer a Kitty graphics query for live image detection. Send the direct a=q query before a primary-device-attributes query, and wait for the graphics reply within a bounded deadline. Orca advertises Sixel in its primary device attributes when the renderer is ready. Terminal settings and the viewer can change after launch.

A local CLI launch on a headless Orca host starts without the image hint. Attaching a desktop later enables rendering in that viewer according to its settings, but the running shell keeps its startup environment.

In tmux, use the multiplexer’s capability information. TERM_PROGRAM inside a pane describes tmux, and environment variables inherited from an Orca client can outlive that attachment. For OSC 8, use a version of tmux with hyperlink support and set the hyperlinks terminal feature for any matching outer terminal type that supports it. tmux display-message -p '#{client_termname} #{client_termfeatures}' shows the attached client’s terminal type and features. Kitty graphics support inside tmux depends on the multiplexer and its attached viewer.

macOS and Linux shell

By default, local terminal panes on macOS and Linux open your system shell ($SHELL) as a login shell (-l). With the default arguments:

  • zsh reads .zshenv, .zprofile, .zshrc, and .zlogin in order from $ZDOTDIR, or your home directory (~) if unset. Each user file follows its system counterpart (zshenv, zprofile, zshrc, zlogin), usually under /etc or /etc/zsh.

  • bash reads /etc/profile, then the first of ~/.bash_profile, ~/.bash_login, or ~/.profile that exists. It does not read ~/.bashrc on its own. If your PATH or version-manager setup (nvm, asdf, mise) lives in ~/.bashrc, source it from that login file, as many distributions' default ~/.profile or ~/.bash_profile already do:

    [ -n "${BASH_VERSION:-}" ] && [ -f "$HOME/.bashrc" ] && . "$HOME/.bashrc"

    The guard keeps non-bash shells that also read ~/.profile from loading bash-only setup, even with set -u enabled. Add it only if the login file bash reads does not already source ~/.bashrc.

When Orca uses its bash integration wrapper, it starts bash with --rcfile instead of -l. The wrapper sources the same login files without separately sourcing ~/.bashrc; bash itself is not in login mode.

To open a different shell, choose Custom shell under Settings → Terminal → Terminal shell. Under Advanced → Custom args, enter one argument per line to replace the default -l for ordinary local panes. An empty list requests no arguments: unwrapped interactive bash then reads ~/.bashrc instead of the login files. When the terminal daemon is unavailable, Orca's bash or zsh integration can override custom arguments and retain login startup. Agent launches, startup commands, and one-off shell choices do not use this argument setting.

Windows shell

The default shell on Windows is configurable between PowerShell, Command Prompt, and WSL under Settings → Terminal. WSL is offered automatically when wsl.exe --status succeeds. The + dropdown on the tab bar also shows a submenu so you can open a one-off tab in any shell without changing your default.

For repos on a WSL filesystem (\\wsl.localhost\...), Orca launches through wsl.exe -d <distro>. For Windows-path repos opened in WSL, Orca translates the cwd to /mnt/<drive>/... and drops you into a login bash.

Windows administrator mode

Open Settings → Terminal → Administrator mode to see whether the Orca app is running as Administrator or Standard user. Unable to determine means Orca could not read its Windows elevation status. Existing terminals can have different permissions from the app.

In the installed Windows app, choose Restart as administrator, review the confirmation, then approve Windows’ prompt using your usual account. After approval, Orca replaces its current local terminal host. This ends that host’s terminals and running agents; restored terminal tabs open new administrator shells. SSH and WSL permissions remain controlled on their hosts. Terminals on retained older hosts keep their original permissions.

If you cancel Windows’ prompt or elevation fails, Orca reopens with its previous permissions and retains its terminal sessions.

For a manual launch, finish your local terminal work and exit Orca. Find Orca in the Windows Start menu, right-click it, and choose Run as administrator. If new terminals still have ordinary permissions, use Settings → Terminal → Manage Sessions → Restart daemon. This ends terminals on the current local host; newly opened local shells inherit the administrator app’s permissions. The setting’s manual instructions include a direct link to Manage Sessions.

To check a PowerShell terminal’s own permissions, run:

([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)

True means that PowerShell process has administrator permissions.

Administrator mode applies to the whole app. When running orca commands in an external PowerShell window, run that window with the same administrator mode as Orca.

To return to ordinary permissions, finish and close all local terminal sessions, exit Orca, and launch it normally. Closing the sessions lets the retained terminal host retire after Orca disconnects; leaving sessions running can retain an administrator host even after the app exits. The Administrator status offers Standard mode guide with these steps.

Shortcuts

  • Cmd-T — new terminal tab in the current worktree.
  • Cmd-Alt-T (macOS) — new agent tab using your default agent. On Linux and Windows this chord ships unbound; assign one under Settings → Shortcuts (search for "New agent tab"). Each supported agent also has its own per-agent "New agent tab" action — bind a chord to launch a specific CLI directly without going through the default.
  • Cmd-W — close the current tab.
  • Cmd-\ — split right.
  • Cmd-Shift-\ — split down.

Native key bindings

Orca advertises the kitty keyboard protocol, so terminal apps see real Shift+Enter, Ctrl+Enter, and other modifier-aware keystrokes — the bindings work the same in Orca as they do in Ghostty, WezTerm, or your native terminal.

For Japanese JIS keyboards on macOS, enable Settings → Terminal → JIS Yen (¥) to Backslash (\) if you want the physical Yen key to send a backslash in terminal sessions.

Floating terminal

The floating terminal is a global shell surface that's always one chord away, regardless of which worktree or tab you're on. It's on by default for new installs.

  • Toggle it with Cmd+Option+A (macOS) / Ctrl+Alt+A (Linux/Windows). The same chord focuses the panel if it's already open and dismisses it if it's already focused.
  • Click the floating button on the edge of the window, or move the trigger to the status bar under Settings → Terminal → Floating terminal.
  • Set the starting working directory under the same setting (~ by default) so new floating tabs land where you expect.
  • The floating panel hosts its own tabs and supports orchestration setup — kick off background runs without claiming a worktree pane.

Quick Commands

Quick Commands save terminal commands you run often, such as npm run dev, pnpm test, or a project-specific setup script. They can also save reusable agent prompts for launch-time prompt agents such as Claude and Codex. Create them from Settings → Quick Commands or the tab bar's Add command button, then run them from the Quick Commands split-button in a worktree tab bar or from the terminal context menu.

Each command has a label, command text, and scope. Use Global for commands that apply everywhere, or Project to show the command only in worktrees for a specific repo. The tab-bar button opens a fresh terminal tab and runs the command; the terminal context menu can insert commands into the current terminal. Use the copy control on a command row (Settings list, tab-bar menu, or mobile Quick Commands) to put the command body on the clipboard.

When you work with a paired Remote Orca Server (or another execution host), the picker can show local and remote collections side by side, labeled by host (for example Local Mac and Orca Server). Saved on is where the command is stored; running a command still executes in the terminal or workspace where you invoke it — so a client-owned command can run inside a remote worktree. Older servers that do not advertise multi-host Quick Commands fall back to the local-only list.