User guide

Layouts

Tile multiple terminals side by side, stacked, or in a grid. Mix horizontal and vertical splits on one screen, balance uneven sashes, and drag tabs between tiles to swap positions.

1. Use the layout buttons in the toolbar, or
2. Press Ctrl+Shift+1 (single), 2 (columns), 3 (rows), 4 (grid) — on Mac use Control, not Command.
3. Split the active panel from a tab's hover icons or its right-click menu — or Ctrl+Alt+Arrow (↑ above · ↓ below · ← left · → right). Presets balance automatically.
4. Balance restores even pane sizes without changing your split structure (right-click a tab → Balance panes).

Selecting text

Drag with the mouse to select terminal output, or use mark mode for full keyboard selection — the same scrollback you can copy with the mouse.

1. Ctrl+Shift+M toggles mark mode (crosshair cursor). Arrow keys move the cursor; hold Shift and use arrows, Home, End, or PgUp/PgDn to highlight.
2. Ctrl+Shift+Home / Ctrl+Shift+End in mark mode selects from the cursor to the top or bottom of scrollback.
3. Ctrl+A (Mac: ⌘A) selects all scrollback without entering mark mode.
4. After mouse-selecting, Shift+Home and other Shift+nav keys extend the highlight without entering mark mode.
5. Ctrl+C copies the selection (or sends SIGINT when nothing is selected). Enter in mark mode copies and exits.
6. Esc clears the selection and exits mark mode.

Groups & colours

Organise terminals in the sidebar and colour-code sessions or groups for at-a-glance context.

1. Right-click a terminal or group in the sidebar.
2. Choose a colour or create / rename groups.

Satellite mode

Pop any terminal out into its own floating window — full CLI fidelity, nothing simplified. A Satellite is the same live session, just detached, so you can keep an agent or long-running command in view while you work elsewhere.

1. Launch from the ✦ button on a terminal tab, the sidebar card actions, or the right-click menu.
2. The window shows a compact chrome with live cwd, git branch, and status, plus a soft accent glow rising from the base so a focused Satellite is easy to spot.
3. Pin (chrome pin button) keeps it on top of other apps. A Satellite gently ghosts (fades) whenever it isn't the focused window, so it stays out of the way until you need it.
4. Click its sidebar card to summon and focus it — the card stays bright while the session is launched.
5. Dock it back to UnionTerminal with the chrome train button or Ctrl+Shift+D (Mac: ⌘⇧D). Closing the window docks it too — the shell keeps running.
6. Ctrl+Alt+S (Mac: ⌘⌥S) summons or hides every Satellite at once.
7. Run up to five Satellites at once; new ones cascade into place and reopen where you left them.
8. Beacon mode — collapse a Satellite to a small floating chip (the Collapse to Beacon chrome button) showing its live status light and session colour. Click the chip to expand it back, or dock it to UnionTerminal. Beacons stay put through sleep/wake, and re-home to your primary screen if you unplug the monitor they were on.

DocView & Focus view

Preview markdown, code, logs, and static HTML beside your work. The toolbar Preview button (or Ctrl+Shift+F) toggles the docked preview rail. Focus view expands the document for distraction-free reading.

1. File and folder paths in terminal output are detected automatically. Hover for name, type, size, and whether the path was found.
2. Click previews the file in the docked rail when it exists; folders reveal in Explorer or Finder. No error if the path is missing — use hover to check first.
3. Hover a path for its card: name, type, size, and buttons for Preview, Open, Show in Explorer / Finder / Files, and Copy path — each with its shortcut. Right-click shows the same actions.
4. A path that cannot be found says where the app looked (your shell's folder, then the project root). When auto-detect cuts a path short, highlight the whole path and Shift+click it (Ctrl, ⌘, Alt, or middle-click also work).
5. Ctrl+click (Mac: ⌘+click) opens in your default app.
6. Ctrl+Shift+click (Mac: ⌘+Shift+click) reveals in Explorer or Finder.
7. Alt+click (Mac: Option+click) or middle-click copies the quoted path.
8. https:// links: click opens in your browser; Alt+click copies the URL.
9. Every preview you open is added to recents automatically. Open the clock menu in the preview header to pick any recent file (with filename, path, and source terminal), or press Ctrl+Shift+← / Ctrl+Shift+→ to move up or down the list (same order as the dropdown, loops at the ends). Works in the docked panel and in focus view.
10. Press Ctrl+Shift+O for focus view; Esc returns to the docked panel (or closes the find bar first when it is open).
11. Press Ctrl+F (Mac: ⌘F) to search within the open document in the docked panel or focus view. Enter and Shift+Enter step between matches; Esc closes the find bar.
12. Use the palette button to cycle theme, light, or dark reading colours.
13. Header actions: open file (default app), reveal in folder, reload, copy, and jump back to the source terminal when it still exists.
14. If the source terminal is gone, use New terminal in the header to spawn a shell in the file's folder.
15. Highlight text in the preview, then press / to ask about the selection. Insert in terminal (or Ctrl+Shift+Enter) types the citation into the linked terminal without running it — useful for stacking several excerpts before you send. Send in terminal (or Enter) pastes and submits in one step. Click the terminal once before typing if keyboard input seems unresponsive after several inserts.
16. Ctrl+scroll (Mac: ⌘+scroll) zooms preview text.
17. Ctrl+Shift+H hides or restores preview and clipboard rails together.

Clipboard & annotate

Capture screenshots and text, annotate images, then drop paths into Claude Code or any CLI.

1. Open the clipboard rail (toolbar Clipboard or Ctrl+Shift+K).
2. Capture a screenshot or copy text — click or drag into a terminal.
3. Annotate images with circles, arrows, and labels before sending.
4. Paste a screenshot — with an image on the clipboard, Ctrl+V (Mac: ⌘V) in a terminal drops the image's file path into your prompt, so tools like Claude Code can read it. Dragging an image file in works the same way.

Scheduler

Queue messages to a terminal at a set time or on a recurring interval while UnionTerminal is open.

1. Open the schedule control in the sidebar.
2. Pick a terminal, message, and time (or recurrence).
3. Overdue messages appear when you return to the app.

Status dots

Each terminal shows a coloured dot: green = active output, yellow = waiting for input, gray = idle.

Settings

Open Settings in the sidebar footer. The panel is searchable — use the box at the top to filter by topic (theme, terminal, hotkey, privacy, editor).

Appearance

Default theme sets the startup look; cycle the current theme anytime from the toolbar. Preview reading colours chooses the default palette when you open DocView (theme, light, or dark).

Shortcuts

Show / focus UnionTerminal — global hotkey to bring the app forward from anywhere on your desktop. Pick a preset or turn it off.

Terminal

New terminal startup — optional starting folder and commands (one per line) when you open a fresh terminal with + or Ctrl+Shift+T (not restored sessions or explicit folder opens).

Clear scrollback sync — off by default. When enabled, Union can clear its own scrollback when the shell wipes the screen (cls, Clear-Host) or when you run configured slash commands (e.g. /clear, /compact). Manual clear from the terminal right-click menu always works.

Terminal scrollbar — Thin (default) or Comfortable width inside terminal panes only.

Shell integration — on by default. Reports live shell cwd so relative paths like ./file.ts and package.json resolve as you cd. Works in PowerShell and Git Bash (Windows), bash and zsh (macOS and Linux). Turn off if a custom shell setup conflicts.

Scroll to bottom — when you scroll up in a long session, click the ↓ control at the bottom-right to return to live output.

Anonymous usage

On by default, and one tap to turn off. Counts installs and which features get used — a random ID, your OS, and version — never commands, file paths, or terminal output. We count installs; we never track people or see your content. Honors DO_NOT_TRACK. A separate Help shape the product option (off by default) links anonymous usage to a random ID for deeper research, and is resettable/deletable anytime. See our Privacy Policy.

Feedback

Send feedback from the Feedback link in the sidebar footer. Choose a category (Bug, Idea, Workflow, or Other) and optionally add a reply email.

Editor connections

Connect external editors (Cursor, VS Code, etc.) so paths and terminals open in the right tool. See the Connections section in Settings.

Shells

Use the split button on + New terminal to pick PowerShell, CMD, Git Bash, or WSL. The chevron menu lists every detected shell; your choice is remembered as the default for the main + button. Add custom shells via Browse for shell executable in that menu.

System requirements

Windows

Windows 10 or later (x64). No additional runtime required. About 120 MB installed.

macOS (beta)

macOS 12 Monterey or later, Apple Silicon (M1/M2/M3/M4) or Intel. About 180 MB installed. Install: open the disk image, drag Union Terminal to Applications, then launch from there. macOS may ask you to confirm the developer on first open — normal for downloaded apps.

Linux (Omarchy) — beta

Built and tested on Omarchy (Arch + Hyprland). x86_64 (64-bit), Wayland or X11 — other distros should work via the AppImage but aren't tested. Ships as a single AppImage, no extra runtime. Install: download the AppImage, mark it executable (chmod +x), and run it. Auto-updates apply the next AppImage in place.

Keyboard shortcuts

See the full reference on the shortcuts page.