Tabs and panes

Open, name and move tabs, split them into panes, search and copy the scrollback, follow links, and see the pictures programs print.

Tabs

Each tab has a shell of its own, which keeps running whether you are looking at it or not.

Do thisWith the mouseWith the keyboard
New tabclick + in the tab bar, or right-click a tab → New tabCtrl+B c
Go to a tabclick itCtrl+B 1 to 9
Next or previous tabturn the mouse wheel over the tab barCtrl+B n / p
Rename a tabright-click it → RenameCtrl+B ,
Move a tabdrag it along the tab bar, or right-click it → Move left / Move rightCtrl+B < / >
Close a tabclick its ✕, middle-click it, or right-click it → Close tabexit in its shell, or Ctrl+B x in its last pane

Opening a tab

A new tab starts in the directory of the pane you were in, so + is the quick way to get a second shell in the same project. A new tab opened from a tab on another machine is on this machine; to open another there, use ≡ menu → New tab on another machine… again.

Going to a tab

Click it. Turning the mouse wheel over the tab bar steps through the tabs, one at a time, and wraps around at the ends. With the keyboard, Ctrl+B n and Ctrl+B p go to the next and previous tab, and Ctrl+B and a number from 1 to 9 goes straight to that one. In a tab split into panes, Ctrl+B → past the right-most pane goes on to the next tab, and Ctrl+B ← past the left-most to the previous one.

Naming a tab

A tab names itself after what it is doing: the program running in it if there is one, otherwise the last part of the directory its shell is in, otherwise the title its program gave it. A tab on another machine says which machine first, as in web-3: src.

To give it a name of your own, right-click it and choose Rename (or press Ctrl+B ,), type the name and press Enter. Esc leaves it as it was. A name you give stays with the tab, through restarts too. Rename it to nothing at all and it goes back to naming itself. /rename name in the agent panel does the same.

Moving a tab

Press on a tab, hold the button, and drag it along the tab bar: it takes the place of each tab it passes over. Right-click a tab for Move left and Move right, or press Ctrl+B < and Ctrl+B > to move the tab you are in.

Closing a tab

Click the tab's ✕, middle-click the tab, or right-click it and choose Close tab. The tab closes at once, and its shells end along with whatever was running in them. Typing exit in a tab's only shell closes it too.

Closing the last tab ends the session for good: nothing of it is kept, and the next astrum starts a fresh one. To leave with everything still running, detach instead. See Sessions that come back.

What the tab bar shows

A tab can carry a mark before its name, so that you know what is going on in tabs you are not looking at:

MarkMeans
a spinnerthe tab's agent is at work
?the tab's agent is asking you something
✓the tab's agent finished while you were in another tab
✗the tab's agent stopped with an error while you were in another tab
●, in the accent colorsomething happened there while you were away: a command finished, or a program rang the bell
●, in yellowa command is running there

The marks for what happened while you were away go once you look at the tab. If there are more tabs than fit, the bar ends with …. In a named session, the session's name is at the right-hand end of the bar. Several agents at once has more on following the agents of several tabs.

Panes

A tab can be split into panes, each with a shell of its own, and split again as often as there is room.

A terminal window running Astrum with three tabs in the tab bar, the front tab divided into three panes: an editor with a source file on the left, a failed test run at the top right and a server's log at the bottom rightA terminal window running Astrum with three tabs in the tab bar, the front tab divided into three panes: an editor with a source file on the left, a failed test run at the top right and a server's log at the bottom right
A tab split into three panes
Do thisWith the mouseWith the keyboard
Split side by sideright-click the pane → Split right, or ≡ menu → Split rightCtrl+B | or %
Split one above the otherright-click the pane → Split down, or ≡ menu → Split downCtrl+B - or "
Move between panesclick the paneCtrl+B and an arrow key
Resize panesdrag the divider between them
Zoom one pane to fill the tab, and backright-click it → Zoom / Unzoom, or ≡ menu → Zoom paneCtrl+B z
Move a pane, or have two change placesright-click it → Move this pane…, then click where it goesCtrl+B M, then click
Close a paneright-click it → Close paneCtrl+B x, or exit in its shell

Splitting

Split right puts a new pane to the right of the one you are in, and Split down puts one below it; each takes half the space. The new pane's shell starts in the directory of the pane it was split from, and the keyboard goes to it. In a tab on another machine, the new pane is on that machine too. When a pane is too small to halve, Astrum says there is not enough room.

Moving between panes

Click a pane to type in it. With the keyboard, Ctrl+B and an arrow key moves to the pane in that direction. The divider is lit along the pane the keyboard is in.

The mouse wheel scrolls whichever pane it is over, without moving the keyboard there, so you can look back through one pane while typing in another.

Resizing

Press on the line between two panes and drag it. The panes on either side grow and shrink as you go, and the programs in them are told their new size.

Moving a pane

Right-click a pane → Move this pane… and the pane is held: it is marked, and as you move the pointer over the other panes a frame shows where it would go.

A tab split in two, a failed test run on the left and an editor on the right. The left pane has a frame around it and the words "moving this pane"; the lower half of the right pane has a brighter frame and the words "put it here"A tab split in two, a failed test run on the left and an editor on the right. The left pane has a frame around it and the words "moving this pane"; the lower half of the right pane has a brighter frame and the words "put it here"
A pane held for moving, and where it would go

Any key, or the right button, lets go of it without moving anything. The keyboard goes with the pane, and whatever runs in it carries on; nothing is restarted. The floating pane is not moved this way: drag it by its title.

Zooming

Zoom lets one pane fill the whole tab for a while; the others are hidden, not stopped, and carry on running. The status bar says so while it lasts (⤢ zoomed · 1 of 3 panes). Right-click and choose Unzoom, or press Ctrl+B z again, to bring them back. Splitting a zoomed tab brings the others back first. Zoom is only offered in a tab with more than one pane.

Closing a pane

Right-click the pane and choose Close pane, press Ctrl+B x, or type exit in its shell. Its shell ends, and the pane next to it takes the space. Closing the last pane of a tab closes the tab.

A floating pane

For a quick command without disturbing the splits, a tab can have one pane that floats over the others.

Do thisWith the mouseWith the keyboard
Open a floating paneright-click a pane → Open a floating paneCtrl+B F
Put it away, still runningclick the ✕ on its frameCtrl+B F
Bring it backright-click the tab, or a pane → Show the floating paneCtrl+B F
Move itdrag its title
Change its sizedrag the ◢ at its bottom right corner
Make a pane of the splits floatright-click it → Float this pane
Put it into the splitsright-click it → Put it back into the splits
A tab split in two, a failed test run on the left and an editor on the right; over the middle of both, a framed pane titled zsh showing git log and git status, with a ✕ at its top right and a corner mark at its bottom rightA tab split in two, a failed test run on the left and an editor on the right; over the middle of both, a framed pane titled zsh showing git log and git status, with a ✕ at its top right and a corner mark at its bottom right
A floating pane over the tab's two panes

It starts at about 60% of the tab, in the middle, with a shell in the folder of the pane you were in. A click outside it moves the keyboard to the pane you clicked, and it stays in view; a click inside it brings the keyboard back. Putting it away does not stop what runs in it, and its tab is marked if it then needs you. It closes when its shell ends.

A tab has one. Where it is, and whether it is shown, is kept with the session: it comes back after a restart, and through astrum upgrade. astrum run --float -- CMD runs a command in one (see Scripts and the command line).

The agent and panes

The agent works in one pane at a time: the one the keyboard was in when you asked it something. It stays there until it has finished, so you can move to another pane and carry on while it works. After that it follows the keyboard again. See The agent.

Scrollback

Each pane remembers the last 10,000 lines its programs printed. scrollback in the config file changes that; the change applies to shells started afterwards.

Do thisWith the mouseWith the keyboard
Scroll back and forwardturn the mouse wheel over the paneShift+PageUp / Shift+PageDown, or Ctrl+B PageUp / PageDown
Back to the bottomscroll down, or start typingany key typed into the shell

A full-screen program (an editor, a pager) has the screen to itself. If it uses the mouse, the wheel goes to it; if it does not, the wheel is sent to it as arrow keys, so a pager such as less scrolls with the wheel too.

Finding text

The search looks through everything a pane still remembers, newest first, and finds as you type.

Do thisWith the mouseWith the keyboard
Open the searchright-click the pane → Find…, or ≡ menu → Find in scrollbackCtrl+B /
Next older matchclick ↑ on the search barEnter or ↑
Next newer matchclick ↓↓
Close the searchclick ✕Esc

The matches are lit up in the pane, and the bar says which one you are on and how many there are (3 of 12), or that there is no match. Small letters find capitals too; a capital letter in what you type makes the search exact. Backspace takes back a letter, Ctrl+U clears the text, and pasting puts the pasted text into the search.

Pressing Tab keeps the search and turns it into copy mode: n and N then step to the older and newer matches, v starts selecting, y copies, and q leaves. Click the search text to type in it again.

A pane showing a git log, with a find bar across its top: the word being looked for, how many places it was found in, and buttons to step through them and to closeA pane showing a git log, with a find bar across its top: the word being looked for, how many places it was found in, and buttons to step through them and to close
Finding a word in what has scrolled by

Copying text

With the mouse:

Copied text is handed to your terminal app's clipboard (that also works over SSH, where the terminal lets programs set the clipboard), and to the clipboard tool of the machine astrum runs on: pbcopy on macOS, wl-copy or xclip on Linux. ASTRUM_CLIPBOARD_TOOL, set before starting astrum, names another program to hand it to, or none to leave copying to the terminal alone.

To keep a selection from being copied the moment you let go, turn off ≡ menu → Settings → Copy text as soon as it is selected (copy_on_select = false in the config file).

Paste the way you always do in your terminal app. What you paste goes to wherever the keyboard is: the shell, the agent panel, or a search.

A command's output, whole

With shell integration (zsh, bash and fish have it), Astrum knows where each command and what it printed begin and end. Right-click anywhere in a command or its output:

What was copied is shown selected for a moment, so you can see it was the right one.

From prompt to prompt

Scrolled back with the mouse, right-click the pane → Previous prompt or Next prompt to move the view from one command to the next; in copy mode, [ and ] do the same with the cursor.

The history in your editor

Right-click a pane → Open the history in my editor: everything the pane has kept (its scrollback and its screen, as plain text) opens in your editor, at the line you were looking at, in a pane zoomed over this one. Search it, copy from it, save part of it elsewhere. It is written to a file only you can read, in Astrum's own folder, which is removed when the editor ends.

In programs that use the mouse

Programs such as vim and htop handle the mouse themselves and get your clicks and drags as usual. Hold Shift while you drag to select text inside them with Astrum's selection instead, and hold Shift while you right-click to get Astrum's menu rather than theirs.

Copy mode

Copy mode is the keyboard's way to select text. Press Ctrl+B [, or click ≡ menu → Select with the keyboard. A COPY chip appears on the bar, and a cursor in the pane that moves through the screen and the scrollback. Nothing typed in copy mode reaches the shell.

KeyDoes
arrows, or h j k lmove the cursor
w / b / eto the next word, the word before, the end of the word
W / B / Ethe same, with words separated only by spaces
0 / $, or Home / Endto the start or end of the line
^to the first character on the line that is not a space
H / M / Lto the top, middle or bottom of the pane
{ / }to the paragraph before or after
%to the matching bracket
g / Gto the oldest or the newest line
PageUp / PageDowna page back or forward
Ctrl+U / Ctrl+Dhalf a page back or forward
v or Spacestart selecting at the cursor
Vselect whole lines
Ctrl+Vselect a block
y or Entercopy the selection and leave
/search, as in Finding text
[ / ]to the prompt before or after (with shell integration)
n / Nthe next older or newer match
q or Escleave (Esc first lets go of a selection, if there is one)

A click in the pane moves the cursor there. The ✕ on the bar leaves copy mode, and so does Ctrl+B [ again.

A web address in a pane can be followed, and so can a link a program marked as one (ls --hyperlink, gh, compilers that link to their documentation). Point at it and the status bar shows where it really goes, which for a marked link may not be what its text says.

Some terminals keep Ctrl-click for themselves (macOS Terminal is one); there, the right-click is the way.

Astrum opens web and mail links and nothing else, with the system's own open (macOS) or xdg-open (Linux) on the machine where you ran astrum. A link to a file is not opened that way, because opening a file can mean running it; it can still be copied. ASTRUM_OPEN_TOOL names another program to open links with, or none.

File paths

A file named in a pane opens in your editor, at the line: src/app.py, src/app.py:42, src/app.py:42:7 and src/App.cs(42,7), the ways compilers, test runners and grep -n print them, and a/src/app.py as git diff does. Only a file that is there, in the pane's folder (or by its full path), counts; point at one and the status bar shows it.

It opens in a new pane beside this one, in the pane's folder, which closes when the editor does. The editor is $VISUAL, else $EDITOR, as the shell you started astrum from has them, else vi; it is told the line as it expects (+42 file for most, -g file:42:7 for VS Code and its kind, file:42:7 for Sublime Text, Zed and Helix). In a tab on another machine, whose files are there, file paths are not followed yet.

Pictures

A picture a program prints is shown in the pane: imgcat, kitten icat, chafa, img2sixel, or a plotting library that draws to the terminal. It scrolls with the text around it, is cleared with it, and is there again when you look back through the scrollback.

Programs send pictures in three ways (iTerm2's, kitty's and sixel), and Astrum understands all three. Each attached terminal is sent the picture in a way that terminal has:

Your terminalWhat it is shown
iTerm2, WezTermeverything, except raw pixels a program sent compressed in kitty's way
Ghostty, kittypictures sent in kitty's way, and PNG files sent in iTerm2's
A terminal that only draws sixelsixel pictures
macOS Terminal, and others with no picturesa line saying what the picture is

Where a picture cannot be shown, a faint block the size it would have been takes its place, with a line such as PNG 640×480 · this terminal cannot show it. The same block stands in while a picture is partly off the edge of its pane or under a menu: a terminal cannot be asked to draw part of a picture, so it is drawn whole or not at all. A picture is drawn once it has been still for a moment, not at every line while output is pouring past.

Things to know:

Several windows on one session

The same session can be open in several terminal windows at once: run astrum in another window (with -s name for a named session). Each window has its own view of the session: its own tab in front, its own menus, drawn edge to edge at its own size. So one window can stay on a build while another edits in a different tab.

Two windows looking at the same tab share it: what is typed in one shows in the other. A tab's shells can only have one size, so they are sized for the window that used the tab last. The other window shows the tab at that size, with dots where it does not reach, until a key or a click in that window brings the tab over to its own size.

Each window is sent pictures in the way its own terminal can show them. Ctrl+B d detaches the window you are in; Ctrl+B D detaches every window from the session. See Sessions that come back.