atriumatrium

Terminal pane

xterm-backed PTY for shells and CLI agents.

Terminal panes are the default pane type and host everything that runs in a shell — interactive shells, adapters (Claude Code, Codex, Gemini), scripts, long-running dev servers.

Opening

  • Cmd+T opens a new room with a terminal pane.
  • Cmd+D / Cmd+Shift+D split the focused pane and open a terminal in the new split.
  • Drag the Terminal tile from the toolbar and drop it into a split zone.

The launcher

A fresh terminal pane shows the launcher docked at the bottom. It is the primary way to start work in a pane and is documented fully in Launching agents — in short:

  • A grid of adapter tiles (Claude Code, Codex, Gemini, and any you have installed). Each tile has its own session picker, YOLO toggle, CLI args field, and a gear icon for per-adapter settings including environment variables.
  • A pane dock (Terminal, Browser, Search, Git, Tasks, Task) for turning the pane into that type in place instead of an agent.
  • Cmd+Enter launches the currently selected adapter tile.
  • Double-tap-then-hold Shift reveals a hotkey letter on every tile — tap the letter to launch instantly.
  • Cmd-hold chain — hold Cmd, press T / D / Shift+D, then tap a launcher letter to open a new pane and launch in one gesture.
The launcher auto-dismisses when you launch, pick a pane type, or type your first command in the terminal. Cmd+L on a focused pane brings it back.

If a binary is missing, its tile is disabled and a Missing a tool? Add manually link appears — it jumps to Settings → Tools where you can point atrium at a custom binary path.

Working in a terminal

  • Full xterm.js rendering with WebGL acceleration.
  • Cmd+F opens a find bar that searches the scrollback, with match highlighting and jump-to-next.
  • Cmd+C copies the current selection. If nothing is selected, it sends SIGINT to the foreground process.
  • Cmd+A selects all scrollback.
  • Right-click a terminal pane for copy / paste / select-all, jump to cwd in the file tree, and pane-level actions like close, rename, and move to another room.
  • Clickable file paths and URLs — paths like src/foo.ts:12 and https://… are clickable. Paths open an editor pane at the right line; URLs open in a browser pane.
  • File drops and paths are framed for agents — dropping a file onto a terminal pane, or pasting an absolute path, inserts it as @"/full/path" so harnesses like Claude Code and Codex pick it up as a file reference instead of raw text.
  • Image paste — pasting an image with Cmd+V into a harness pane attaches it as an image; pasting a non-image file inserts its path as the @"…" reference above.
  • The pane header shows the foreground process name and exit state, and highlights a dirty indicator if output is pending for a hidden pane.

Customizing a terminal

All terminal pane appearance lives in Settings → Terminal with live previews:

  • Font family, size, line height, letter spacing, ligatures. Powerline / Nerd Font glyphs render through an automatic fallback chain — your primary font does not need to be a Nerd Font–patched build for prompts like p10k, starship, or oh-my-posh to display their icons correctly.
  • Cursor style (block / underline / bar) and blink.
  • Scrollback line count.
  • Inner padding.
  • Background opacity.
Changes apply to every terminal pane immediately. See Appearance.

Persistence

Terminals are fully resumable across quits, crashes, and reboots:

  • Scrollback is captured as the xterm grid and replayed on reopen.
  • Working directory, shell, adapter type, and adapter session ID are restored.
  • If the last command exited non-zero or was signal-killed, the pane records it so the Activity sidebar can offer a Replay action.
See Persistence & recovery for the full model.

Shell integration and environment

When atrium launches a shell it transparently installs a minimal integration layer so it can emit command-start and command-end events, track the foreground process name, and route hook events to the adapter.

  • For zsh, atrium sets ZDOTDIR to ~/.atrium/zsh/ with wrapper dotfiles that source your real dotfiles and add the hooks. Your .zshrc still runs normally.
  • For bash, atrium chains its hooks onto PROMPT_COMMAND, preserving any existing value as ATRIUM_EXISTING_PROMPT_COMMAND.
  • A USR1 signal to any atrium shell re-sources ~/.atrium/shell/env.sh, letting settings changes propagate into running shells without restarting them.
Every atrium shell also gets a small set of environment variables that identify the pane (ATRIUM_PANE_ID, ATRIUM_WORKSPACE_ID, ATRIUM_TAB_ID) and point at the CLI (ATRIUM_CLI_PATH). See Agents & adapters for the full contract.

Scripting a terminal pane

Terminal panes are discoverable and writable from the atrium CLI. Agents use this surface to inspect each other; you can use it from any shell to script a pane:

# List every pane
"$ATRIUM_CLI_PATH" pane list

# Read the last 200 rendered lines (what the user sees)
"$ATRIUM_CLI_PATH" pane read <id> --lines 200

# Write text to the PTY stdin
"$ATRIUM_CLI_PATH" pane write <id> --text "pnpm build"

# Focus, rename, resize, close
"$ATRIUM_CLI_PATH" pane focus  <id>
"$ATRIUM_CLI_PATH" pane rename <id> --name "build server"
"$ATRIUM_CLI_PATH" pane resize <id> --width 120 --height 40
"$ATRIUM_CLI_PATH" pane close  <id>

See the full CLI reference.

Constraints

  • The underlying PTY requires a shell binary (zsh or bash) on $PATH. atrium uses the system default.
  • Very large single-line outputs can stall rendering; use less or redirect to a file for dumps above a few MB.
  • The scrollback persistence format is a VT-escaped grid. Older legacy snapshots without this format are silently discarded on restore.