# Terminal

> Consoles, splits, the floating terminal, links and environment variables.

A console is a terminal tab running your login shell in the worktree folder. Agents run in consoles too. Shells keep running when you quit Rexa and reattach on the next launch.

## Shell

- **Your shell, as a login shell.** Rexa runs `$SHELL -l`, or `/bin/zsh` if `$SHELL` is unset.
- **Starts in the worktree** the tab belongs to.
- **Full terminal support:** truecolor, mouse reporting, the kitty keyboard protocol and in-place IME composition. TUIs such as vim, htop, fzf and lazygit work.
- **Font and theme** follow the app. The default font is JetBrains Mono; change it with `font_family` and `font_size` in [Settings](/docs/customize/settings).

Every terminal gets two variables: `REXA_TERMINAL_ID` and `REXA_NAMESPACE`. Agents use them to talk back to the app.

## Consoles and splits

| Action                          | Shortcut                                          |
| ------------------------------- | ------------------------------------------------- |
| New console tab                 | <Kbd>⌘</Kbd> <Kbd>T</Kbd>                         |
| New tab of a chosen kind        | <Kbd>⌘</Kbd> <Kbd>N</Kbd>                         |
| Reopen closed tab               | <Kbd>⌘</Kbd> <Kbd>⇧</Kbd> <Kbd>T</Kbd>            |
| Split right                     | <Kbd>⌘</Kbd> <Kbd>D</Kbd>                         |
| Split down                      | <Kbd>⌘</Kbd> <Kbd>⇧</Kbd> <Kbd>D</Kbd>            |
| Move between splits             | <Kbd>⌘</Kbd> <Kbd>⇧</Kbd> + arrow keys            |
| Maximize the focused split      | <Kbd>⌘</Kbd> <Kbd>↵</Kbd>                         |
| Close the focused split         | <Kbd>⌘</Kbd> <Kbd>W</Kbd>                         |

Split left, split up and reset sizes are in the right-click menu. When the shell exits, its split closes, and the tab closes with its last split.

## Floating terminal

<Kbd>⌘</Kbd> <Kbd>J</Kbd> shows or hides a terminal panel that floats over any view. <Kbd>⌘</Kbd> <Kbd>⇧</Kbd> <Kbd>J</Kbd> moves the keyboard into it and back.

- **One panel per worktree.** Its tabs are terminals; <Kbd>⌘</Kbd> <Kbd>1</Kbd> to <Kbd>⌘</Kbd> <Kbd>9</Kbd> pick one while it has focus.
- **Drag to move, drag the edge to resize.** Position, size and terminals survive a relaunch.
- **Settings:** `floating.width`, `floating.height`, `floating.position` (one of nine anchors), `floating.offsetX`, `floating.offsetY`.

## Keys inside a terminal

| Action                  | Shortcut                                                       |
| ----------------------- | -------------------------------------------------------------- |
| Copy / paste            | <Kbd>⌘</Kbd> <Kbd>C</Kbd> / <Kbd>⌘</Kbd> <Kbd>V</Kbd>           |
| Clear screen and scrollback | <Kbd>⌘</Kbd> <Kbd>K</Kbd>                                  |
| Clear line              | <Kbd>⌘</Kbd> <Kbd>⌫</Kbd>                                      |
| Start / end of line     | <Kbd>⌘</Kbd> <Kbd>←</Kbd> / <Kbd>⌘</Kbd> <Kbd>→</Kbd>           |
| Page up / down          | <Kbd>⇧</Kbd> <Kbd>PgUp</Kbd> / <Kbd>⇧</Kbd> <Kbd>PgDn</Kbd>     |
| Scroll to bottom        | <Kbd>⌘</Kbd> <Kbd>↓</Kbd>                                      |

Other <Kbd>⌘</Kbd> chords are app commands and never reach the shell. <Kbd>Tab</Kbd> and <Kbd>⇧</Kbd> <Kbd>Tab</Kbd> go to the shell.

## Scrollback and selection

- **Scrollback holds 10,000 lines.** Typing snaps back to the bottom.
- **Select** by dragging; double-click a word, triple-click a line, <Kbd>⌥</Kbd>-drag a block.
- **Hold <Kbd>⇧</Kbd>** to select or scroll inside a program that captured the mouse.
- **Copy on select:** turn on `terminal.copy_on_select` in Settings → Terminal.

## Links

<Kbd>⌘</Kbd>-click opens a link; a plain click only selects. The pointer becomes a hand while <Kbd>⌘</Kbd> is held.

| Under the pointer                               | <Kbd>⌘</Kbd>-click does                              |
| ----------------------------------------------- | ---------------------------------------------------- |
| `http://`, `https://` or OSC 8 link             | Opens it in a Rexa browser tab.                      |
| File path, such as `src/a.rs:12:3` or `app.ts(12,5)` | Opens the file in a tab at that line.           |
| Python traceback line (`File "x", line N`)      | Opens the file at that line.                         |
| Directory                                       | Reveals it in Files, or in Finder outside the worktree. |
| A path that matches no file                     | Opens quick open with the path filled in.            |

A solid underline means the file exists; a dotted one means the click searches. Paths that wrap across rows open as one link. Paths with spaces are not detected.

## Drop files and images

- **Files** dropped from Files or Finder insert shell-quoted absolute paths.
- **On an agent's terminal,** dropped files use the agent's mention format, and dropped images are pasted as images. <Kbd>⌘</Kbd> <Kbd>V</Kbd> with an image on the clipboard pastes it too.

Images over 10 MB are skipped.

## Environment variables

Settings → Terminal → **Environment variables** takes a block of `KEY=value` lines. Blank lines, `#` comments, a leading `export ` and surrounding quotes are handled; invalid lines are skipped with a warning.

```bash [Settings → Terminal → Environment variables]
# exported to every new terminal, run and agent
export NODE_OPTIONS="--max-old-space-size=8192"
DATABASE_URL=postgres://localhost/dev
```

The variables reach terminals started after you save. Running terminals keep their environment.

## Terminals survive a quit

A background process owns the shells. Quitting Rexa detaches from them, and the next launch reattaches, so builds and agents keep running.

- **Closing a tab ends its process.** Rexa sends SIGTERM to the process group, then SIGKILL after two seconds.
- **Restored terminals keep the last 500 lines** of scrollback.
- **An update that changes the terminal protocol** ends running shells once. The release notes say when.

`rexa pty ls` lists the background shells, and `rexa pty stop` stops the background process. See the [CLI reference](/docs/reference/cli).

## Limits

- No find bar in the terminal.
- No select-all and no jump to the previous prompt.
- <Kbd>⌥</Kbd> <Kbd>←</Kbd> and <Kbd>⌥</Kbd> <Kbd>→</Kbd> do not move by word in default zsh and bash configs.
