> ## Documentation Index
> Fetch the complete documentation index at: https://docs.otter-shell.org/llms.txt
> Use this file to discover all available pages before exploring further.

# otter-term

> Native Wayland terminal for Otter Shell. Tabs, split panes, shell integration, URL handling, and IME support.

`otter-term` is Otter Shell's built-in terminal emulator. It uses `libghostty-vt` for terminal emulation and Otter libraries for Wayland windowing, PTY handling, input, rendering, configuration, and clipboard. Tabs, horizontal and vertical splits, shell integration via OSC sequences, and IME support. No X11 dependency.

## Launching

Pass a directory path to open there, or use `-e` to run a command instead of your default shell.

```bash theme={null}
otter-term                                      # open with default shell
otter-term /path/to/project                     # open in directory
otter-term --cwd /path/to/project               # same, with explicit flag
otter-term --working-directory /path/to/project # long form of --cwd
otter-term -e htop                              # run a command
otter-term -- nano file.txt                     # pass arguments to command
```

## Features

<CardGroup cols={2}>
  <Card title="Tabs" icon="table-columns">
    Multiple terminal tabs in one window. Close buttons appear per tab and hide when only one tab remains.
  </Card>

  <Card title="Split Panes" icon="table-cells-large">
    Split any tab horizontally or vertically. Each pane has its own focus, resizes independently, and closes without affecting the others.
  </Card>

  <Card title="Shell Integration" icon="terminal">
    OSC 7 tracks the current working directory so new tabs and splits open in the right place. OSC 133 captures command output for the context menu.
  </Card>

  <Card title="URL Handling" icon="link">
    `http://`, `https://`, and `www.` URLs are detected, underlined on hover, and opened with a configurable command (default: `xdg-open`).
  </Card>

  <Card title="IME Support" icon="language">
    Full `zwp_text_input_v3` support with preedit text display and candidate-window positioning at the terminal cursor.
  </Card>

  <Card title="Clipboard" icon="clipboard">
    Copy with <kbd>Ctrl+Shift+C</kbd> and paste with <kbd>Ctrl+Shift+V</kbd>. Primary selection and a right-click context menu are also supported.
  </Card>

  <Card title="Scrollback" icon="scroll">
    Configurable scrollback. Idle panes compress history so big buffers cost less memory.
  </Card>
</CardGroup>

## Configuration

`otter-term` reads `~/.config/otter-shell/otter-term.conf`. The file loads on startup and **hot-reloads whenever you save it**. Font, padding, and grid size update without restarting the terminal.

Shared colors in `theme.conf` hot-reload too. [otter-theme-gen](/desktop/otter-theme-gen) and otter-settings write that file; saving it updates open terminal panes.

```conf theme={null}
general_shell = ""
general_term = "xterm-256color"
general_width = 900
general_height = 560
general_scrollback_rows = 10000

font_family = "IoskeleyMono Nerd Font"
font_size = 14
font_dpi_aware = true
font_scale_percent = 100

padding_x = 4
padding_y = 4

keybinds_copy = "ctrl+shift+c"
keybinds_paste = "ctrl+shift+v"

url_enabled = true
url_underline = true
url_highlight_on_hover = true
url_open_command = "xdg-open"

scroll_fixed_per_row = 10
scroll_rows_per_notch = 3

shell_capture_output = false

bell_enabled = true
bell_command = "paplay /usr/share/sounds/freedesktop/stereo/bell.oga"
bell_visual = false
```

<Note>
  `general_shell = ""` uses `$SHELL`, falling back to `/bin/sh` if unset. The default `general_term` value `xterm-256color` works best for remote hosts over SSH. Only set it to `xterm-ghostty` when the target host has that terminfo entry installed.
</Note>

<Tip>
  Set `shell_capture_output = true` to enable OSC 133 command-output capture. The right-click context menu then gets a **Copy Last Output** action that copies the full output of the most recent command. Off by default to keep large command output off the hot PTY path.
</Tip>

## Color Palette

The color palette uses `colors_*` keys in `otter-term.conf`, or inherits from `theme.conf` when those keys are unset. Palette changes hot-reload on save. Per-app keys in `otter-term.conf` override the shared theme.

## Compositor compatibility

Works on Hyprland, Sway, Niri, and other wlroots compositors. On Niri, scroll damage is tracked so scrollback redraws match the viewport.

## Keyboard Shortcuts

| Action         | Shortcut                     |
| -------------- | ---------------------------- |
| Copy selection | <kbd>Ctrl+Shift+C</kbd>      |
| Paste          | <kbd>Ctrl+Shift+V</kbd>      |
| New tab        | Right-click → **New Tab**    |
| Split pane     | Right-click → **Split Pane** |