Terminal features

This page covers how panes behave as terminals: the shell they start, working directories, mouse and clipboard handling, drag and drop, copy mode and search, links, scrollback, images, and pane logging.

Programs in a pane work as they would in any terminal, including mouse input, titles, clipboard access, and resizing. They see rozi as their terminal, whichever terminal rozi itself runs in: each pane sets TERM=xterm-256color, COLORTERM=truecolor, TERM_PROGRAM=rozi, and TERM_PROGRAM_VERSION to the version of rozi running the session, and a program that asks the terminal for its name and version gets rozi and that same version. Each pane runs on the session server, so it keeps running in a named session after you detach. See Core concepts and Sessions.

On Linux and macOS, panes start with XON/XOFF flow control turned off. Ctrl+S and Ctrl+Shift+S reach the program in the pane as a key instead of pausing its output until Ctrl+Q. Bash, for example, uses the key for forward history search. A program that needs flow control can turn it back on with stty ixon.

Choose the shell and starting directory

The [shell] setting chooses the interactive shell, and cwd sets the fallback working directory. When they are unset, rozi uses the platform's default shell and the directory it was launched from.

Remote panes use the remote server's shell and filesystem, not the client's [shell] value. See Remote sessions.

Working directories and shell metadata

Shell integration lets rozi know each pane's directory, prompts, and running command. rozi uses this for pane titles, opening new panes in the same directory, prompt navigation, copying the last command's output, and detecting the program in the foreground.

With [shell_integration] mode = "auto", the default, rozi sets up bash, zsh, fish, and PowerShell for each pane without editing your shell startup files. It does not edit the Windows AutoRun registry key. cmd.exe can report its directory and prompt boundaries, but not the command it is about to run.

rozi finds a pane's working directory from the first of these that is available:

1. While the shell runs a program, the directory the program was started in, on Linux and macOS. A line such as cd ~/src/api && claude shows, saves, and restores the pane in ~/src/api, even if the program later changes its own directory.
2. A valid local directory report from the shell (OSC 7 or OSC 9;9).
3. Process inspection of the shell, on Linux and macOS.
4. The pane's launch directory.
5. The configured cwd.

Windows has no process inspection, so live directory and foreground-program updates there need shell integration.

A directory reported for another host, such as inside an SSH session, can appear in titles, but rozi never starts a new local pane in it.

See Configuration for modes and per-shell behavior.

Use the mouse

Mouse events go to the program in the pane unless you hold the modifier (Alt by default), have pressed the prefix, or the pane is in copy mode. Mouse-aware editors and other terminal apps keep working normally.

Gesture	Action
Drag over terminal text	Select text and copy it on release
Middle click (Linux)	Paste the primary selection into the pane under the pointer
Wheel over a pane	Scroll history
Ctrl plus click a visible link	Open it
Modifier plus left-drag	Move a pane
Modifier plus right-drag	Resize a pane
Prefix, then left-drag	Move a pane
Prefix, then right-drag	Resize a pane
Drag a tiled split boundary	Resize the split
Drag a workspace tab along the workbar	Move the workspace there

When you drag after pressing the prefix, the which-key strip hides during the drag. The PREFIX badge stays until you release the button, which also ends the prefix.

The wheel scrolls pane history and scrollable lists three lines for every scroll your terminal sends. Change the multiplier with Scroll multiplier in Settings or scroll_multiplier in [input]. It stacks with your terminal's own scroll multiplier: if Ghostty is set to 3 and rozi to 3, one notch scrolls nine lines, so lower one of them if scrolling is too fast. A program that tracks the mouse, such as an editor, receives the wheel itself and scrolls by its own step.

On terminals that support mouse pointer shapes, the pointer follows the pane application under the mouse, including an unfocused pane. Choose Mouse pointer in Settings to enable feedback for Rozi and pane apps, follow Pane apps only, or turn it Off. Text selection uses a text pointer, clickable controls use a pointing hand, and pane splits and sidebar dividers show resize arrows. Plain pane borders and title areas use the normal pointer. Moving a pane shows a grabbing hand. Right-drag resizing shows the directional arrow for the grabbed corner: northwest, northeast, southwest, or southeast. Other terminals keep their usual pointer.

rozi limits pointer-motion events sent to a mouse-tracking program to the configured frame rate, so the program does not fall behind. Presses, releases, and wheel events are always sent.

Select, copy, and paste

Drag to select text. When you release the mouse, rozi copies the selection to the regular clipboard, and on Linux also to the primary selection. The selection stays visible after copying and stays on the same lines while you scroll. Ctrl+C also copies the active selection to the regular clipboard.

A copy leaves out blank lines at the start and end of the selection, so dragging past the end of the output does not copy the empty rows below it. Blank lines between text are kept. A selection of only blank lines copies nothing and leaves the clipboard as it was.

A deliberate copy — Ctrl+C, a right-click copy, copy mode, or a hint — briefly lights up the copied text. Choose how with copy_feedback: a flash, a fade, a scan line that sweeps across the text, a double pulse, or nothing. Set copy_feedback_on_select to light up the copy a mouse selection makes as well, and clear_selection_after_copy to have the selection disappear once it is copied.

On Linux, middle click pastes the primary selection into the pane under the pointer, not the focused pane. Clicking another pane focuses it first; a click on a pane border or titlebar pastes nothing.

Right click does nothing clipboard-related by default, so it stays available to the pane program and to rozi. If you set right_click, it follows the same pointer rule as middle click, and "copy-or-paste" copies only a selection in the pane you click.

A program that tracks the mouse, such as Codex or Claude Code, receives middle and right clicks itself and pastes from the clipboard of the machine it runs on. In a remote session that is the remote host, so the click usually pastes nothing. Hold Shift while you middle-click or right-click to paste your local clipboard with rozi instead; Ctrl+V works too.

You can change all of these under [clipboard]; changes apply when the config reloads. If the system has no primary selection, regular clipboard copying still works, and primary-only gestures are turned off.

The v command key and Ctrl+V paste text from the system clipboard as a bracketed paste. In a local session, direct Ctrl+V passes non-text formats to the pane program; the prefix and command-palette paste commands read text.

When your local rozi window is attached to a remote session, Ctrl+V and the paste command also accept clipboard images and copied files. rozi uploads them and pastes their remote paths without submitting the prompt. Codex and Claude Code can use the image paths as attachments. Other files arrive as paths for the pane program to interpret. An empty clipboard keeps direct Ctrl+V available to the program. If the connection is unavailable, pasting reports an error; reconnect and paste again.

Copy up to 16 regular files at once from a file manager. Each file may be up to 16 MiB; clipboard images may be up to 10,000,000 bytes after PNG encoding. Directories and symbolic links are rejected. A single absolute PNG, JPEG, GIF, WebP, or BMP path emitted by the terminal is also uploaded when it names a local file. Text read by rozi's clipboard shortcut or paste command stays literal, even if it names a local image. Paths absent from your computer also stay text. A terminal can emit identical text for its own paste gestures and file drops; use rozi's Ctrl+V or paste command to keep a copied path literal. If the terminal consumes the shortcut before rozi receives it, use the v command key or the paste command in the command palette.

Uploaded files survive detach and reconnect while the session server runs. They are removed when that server stops and are not restored with a saved session. A session can retain up to 256 files or 256 MiB of uploads. Reaching a limit reports an error. Files copied from your computer remain unchanged.

This transfer works for panes in managed remote sessions. An ordinary ssh command inside a local pane, another SSH hop inside a remote pane, and programs inside containers need their own file transfer or shared filesystem.

Programs can set the system clipboard through OSC 52 while [clipboard].enable_osc52 = true, the default. Turn it off if pane programs should not control your clipboard. The change applies when the config reloads.

When attached to a remote session, mouse selection and OSC 52 use your local clipboard. A pane program that calls a clipboard API directly uses the remote host's clipboard.

Drag and drop

In a terminal that supports drag and drop, such as kitty 0.47 or later, you can drop files and text from other applications onto a pane. The pane under the pointer is the one that receives the drop, and its border lights up while you drag over it. Dropping focuses that pane.

• A program in the pane that supports drag and drop, such as yazi or kitty's kitten dnd, receives the drop itself, as it would in a terminal of its own. It decides what it accepts and can read dropped files even when it runs in a remote session. Losing permission to type in the pane cancels an active drag or drop.
• Any other program receives the dropped files as their paths, quoted for a shell, or the dropped text, as a paste. A pane in a remote session receives uploaded copies of the files instead, as pasting copied files does, with the same limits.
• A program that offers drags can be dragged from, into other applications.

Turn drag and drop off with [clipboard].drag_and_drop = false. In a terminal without drag and drop support, a drop arrives the way that terminal sends it, usually as pasted text.

Copy, search, and hints

Copy mode

Press Ctrl+A, then [ to enter copy mode. It lets you move a cursor with the keyboard, select text, jump between shell prompts, and copy the last command's output. Press / in copy mode to search the focused pane. See Keybindings for every key. The copy-mode cursor is your terminal's own cursor, in its usual shape. With the cursor trail in "jump" mode, a smear follows its long moves. The cursor starts where the shell's cursor is. If you entered copy mode while scrolled back and that spot is below the view, the cursor starts at the bottom row of what you are looking at instead.

The mouse works in copy mode too. Drag to select text, or click to move the cursor there. The keys then pick up where the mouse left off: $ extends a dragged selection to the end of its row, and y copies it and exits. The wheel scrolls the pane and keeps the cursor on the same screen row. While copy mode is open, the mouse belongs to it, even when the program in the pane tracks the mouse, and a paste with the middle or right mouse button does not reach the pane. Copy mode also keeps focus on its pane: clicking another pane does nothing until you leave copy mode.

Search scrollback

Outside copy mode, the / command key searches the retained history.

• Tab switches the scope between the focused pane, the workspace, and all panes.
• The arrow and paging keys move through results.
• Workspace results are grouped by pane. All-pane results also name the workspace. Panes are numbered in display order.
• Search keeps up to 2000 matches. The count shows + when there are more.

ASCII letters match regardless of case; other characters are case-sensitive. Lines that wrapped only because of the pane width are joined before matching, so they count as one line and one result. When the pane prints new output, an open search runs again so its results stay accurate.

Hint mode

The u command key starts hint mode. It labels visible URLs, links that programs mark explicitly (OSC 8 hyperlinks), paths with optional line numbers, Git commit ids, and your [[hints]] patterns, including ones that wrap across lines. Type a lowercase label to copy the target, or end the label with an uppercase character to open it when it can be opened. After each key, labels show only the keys left to press. URL hints use the same handlers as clicked links. A configured file handler enables path hints; custom patterns can define on_open commands. See Link handlers.

What counts as a target:

• Links copy and open their destination, not their visible text, so PR #200 linked to a pull request gives the pull request URL.
• URLs end at whitespace, quotes, backticks, and angle brackets. Trailing sentence punctuation and closing brackets are left out.
• Paths start with ./, ../, ~/, /, or a drive letter, or are relative paths such as src/main.rs whose file name has an extension. A path starting with / needs a second / or an extension, so /etc/hosts is a path and a slash command such as /status is not. Neither is a bare and/or or feature/branch.
• Git commit ids are 7 to 40 hex digits containing both a digit and a letter.

A URL or path containing … is skipped: the program shortened it, and what remains is not the real target.

Copy the last command output

Copy last command output copies what the most recent command printed. While a command is still running, it copies the output so far. While a full-screen program such as vim or htop is open, it copies the output of the command that finished before it, since the program's own screen is not kept in scrollback.

This and the prompt jumps in copy mode need shell integration; see Working directories and shell metadata. For scripts, rozi capture-pane --last-output captures the same output.

Open links

Hold Ctrl and click a visible URL to open it with a configured link handler, or the system handler when none matches. Links that programs mark explicitly (OSC 8 hyperlinks) also work, and take precedence over URLs detected in plain text. File URLs and other schemes need a configured handler. rozi shows an error for unsupported destinations. With a file handler, file paths such as src/main.rs:12:3 are links too, when the file exists. In a remote session pane, http and https links to localhost, 127.0.0.1, 0.0.0.0, or :: are forwarded automatically over SSH when opened on your client and rewritten to the local forwarded port; see Port forwarding.

Scrollback

Each pane keeps the last scrollback lines of output, 5000 by default. Typing returns the view to live output.

The session keeps each pane's history so you can reattach. Every attached client uses that pane's history limit, even when its own scrollback setting differs. Memory use grows with pane width, the amount of history, and the number of attached clients. Lower scrollback if memory matters more than deep history.

The limit is fixed when a pane is created. After a config reload, the session host's scrollback value applies to new panes; existing panes keep their old limit, including after reconnect or resurrection. Two panes in one session can have different limits. Open replacement panes to use the new limit.

Edit scrollback saves the focused pane's history to a private file in the state directory and opens it in $EDITOR, then $VISUAL, then vi. rozi keeps about the 20 most recent files. These files may contain passwords, tokens, and other private output.

Titles and urgency

Programs set the pane title with OSC 0 or OSC 2. A custom title set with the N command key takes precedence. See Layouts and panes.

rozi also titles your terminal window, so window switchers and status bars can tell rozi windows apart. By default the title reads rozi · <session> · <focused pane>. A temporary session has no name, so its title reads rozi · <focused pane>. An agent's working spinner is left out. Set the format, or turn it off, with window_title.

With [notifications] bell = true, a bell from a pane you are not watching marks its workspace. You are watching a pane only when both the terminal window and the pane have focus. A bell from a pane running an agent does not mark it: the agent's own finished or blocked mark covers it. A pane with only a rozi status activity is not running an agent, so its bell still marks it.

Switching to a workspace preserves its panes' attention marks, including finished-agent marks, even when a marked pane is selected automatically. Click or explicitly focus the pane, scroll through it, type into it, or paste into it to clear its marks. Scrolling also clears marks when the pane's program handles the mouse wheel.

Images

Pane programs can show images with the Kitty graphics protocol. rozi displays them in whatever format the host terminal supports, including Kitty, iTerm2, sixel, or a text-cell fallback. Images scroll with the terminal and belong to the screen (main or alternate) they were drawn on.

When a program redraws an image faster than a client can show it, such as a browser playing a video, rozi shows the most recent frame and skips the ones in between, so the picture stays current instead of falling behind. Over SSH, only the parts of an image that changed are sent, so a mostly still page costs a fraction of a full redraw. While a client from an older rozi release is attached to the session, every client receives whole images instead.

Limits:

• Kitty protocol animation frames are not supported, apart from edits to an image's first frame. Programs that redraw an image can still animate it.
• Each pane keeps up to 200 MiB of image data, and evicts the oldest images beyond that. A client that attaches to a running session receives the images still on screen.
• A single image upload is limited to 64 MiB.
• Programs can also hand images over in regular files, temporary files, or POSIX shared memory. Images keep updating when local and SSH clients share a session, including after a source is consumed or someone reconnects.
• Over a slow connection, images show the newest frame the connection can carry and skip the ones in between, so video and image-heavy pages update less often while other panes stay responsive.

If images draw incorrectly in a Kitty-protocol terminal such as Ghostty, start rozi with TUI_LIPAN_TERMINAL_IMAGES=composed. rozi then draws every image itself instead of handing placements to the terminal. If image-heavy panes are slow while you resize the window, set TUI_LIPAN_IMAGE_RESIZE_PAUSE_MS=180 so rozi waits for the resize to settle before it redraws them.

Take a screenshot

To save a PNG of what rozi shows, run one of these from the command palette, or bind its id under [keys]:

Command	Id	Saves
Screenshot pane	screenshot-pane	The focused pane's visible screen, without its border or title.
Screenshot UI	screenshot-ui	The whole window as drawn: bar, sidebar, borders, titles, and every visible pane.

Screenshot UI leaves out the command palette that ran it. The Screenshot saved toast shows the file path beneath its title. Left-click to open the PNG in your default image viewer, or right-click to copy its full path. The pane or window flashes briefly in the theme's accent color. The flash comes after the picture is taken, so it never appears in the file. With [animations] enabled = false or focus_chrome = false, only the toast appears.

Files go into [capture] dir, which defaults to captures in the state directory, and are named rozi-pane-<ID>-<YYYYMMDD-HHMMSS>.png or rozi-ui-<YYYYMMDD-HHMMSS>.png in local time. A second screenshot in the same second gets -2, -3, and so on; an existing file is never replaced. [capture] scale (1 to 3) enlarges the image. A screenshot is always written on the machine running this rozi window, even when the session is on another host.

Screenshots use the same drawing as rozi capture-pane --render png and rozi capture-ui --render png, which scripts should use instead; see Capturing the whole UI. Those commands never flash.

Pane logging

To save a pane's raw output to a file, run Pane logging from the command palette or bind toggle-pane-logging. The titlebar shows a log badge while logging is on, and every attached client sees the same state. When logging starts, a toast shows the log path; right-click it to copy the full path. The file is on the session server's host.

Logging stops after a write error or when the file reaches [logging] max_bytes (64 MiB by default; 0 means no limit). Logs are written to [logging] dir, which defaults to logs in the state directory.

Logs keep escape sequences and carriage returns. Each logging run starts with a header that records the session, pane, generation, size, and start time. Raw logs can contain credentials and private output, so store and share them with care.

Persistence boundaries

• Named sessions keep their panes running while their server runs.
• Profiles restore the layout and launch commands in fresh panes.
• Resurrection restarts commands and replays saved terminal history, including retained Kitty images.
• Scratch panes belong to one client and are never saved or shared.
• Retained Kitty images are restored when you attach to a live session.

See Profiles and Shared sessions for those workflows.

Program status

A program can report its progress through OSC 7501, and rozi shows it in the Activity sidebar tab. For example, this reports a build at 40 percent:

printf '\033]7501;state=working:app=cargo:progress=40\033\\'

State	Meaning
working	The program is busy, optionally with a percentage.
blocked	The program needs your input.
done	The work finished.
error	The work failed.

Messages and titles are base64-encoded UTF-8. The Activity tab shows one row per pane: if a pane reports several things, the most urgent wins, in the order blocked, error, working, done, idle. Selecting the row focuses the pane.

A report lasts until the program replaces it. A new prompt or the program exiting clears working and blocked; done and error stay until the program reports again or the terminal is reset. Reports keep arriving while no client is attached, and a client that attaches sees the current state.

blocked and error notify you like a finished agent does, following your notification settings, and tint the pane border in the warning and error colors. Override or turn off those colors with the blocked and error keys in [pane.alert]. Interacting with the pane clears its attention mark. working, done, and progress updates never notify.

A report never makes a pane an agent, even when it says app=codex or app=claude-code. When it names an agent rozi found in that pane, such as app=claude-code from Claude Code, it is that agent's own word on its state, and rozi takes it over what it reads on the screen: it decides when the agent is working, blocked, done, or failed, what rozi agents wait sees, and when the machine stays awake. The agent's row shows the report's message as what it is doing, and its title names the run, instead of a row of its own. With one row per conversation, as an extension like claude-rozi-sessions publishes, the report speaks for the conversation on screen. An agent's hook reports outrank it. Reports from other programs in the same pane keep their own row. A report left behind after the agent exits is an activity named after the agent.