The mouse and the keys

Every click and menu in Astrum, then the keys: how the prefix key works, how to change the keys, and the full list.

Everything with the mouse

Nothing in Astrum needs a keyboard shortcut. The tab bar, the status bar and every pane can be clicked, right-clicking a tab or a pane gives a menu, and ≡ menu at the bottom right lists everything else. The keys are there for people who want them, and every menu shows the key beside its entry.

Do thisWith the mouseWith the keyboard
New tabclick + in the tab barCtrl+B c
New tab on another machine≡ menu → New tab on another machine…Ctrl+B R
Go to a tabclick it, or turn the wheel over the tab barCtrl+B n / p / 1 to 9
Move a tabdrag it along the tab barCtrl+B < / >
Rename a tabright-click it → RenameCtrl+B ,
Close a tabclick its ✕, or middle-click itCtrl+B x in its last pane, or exit
Split a paneright-click it → Split right / Split downCtrl+B | / -
Go to another paneclick itCtrl+B and an arrow key
Resize panesdrag the divider between them
Zoom a pane, and backright-click it → Zoom / UnzoomCtrl+B z
Close a paneright-click it → Close paneCtrl+B x, or exit in its shell
Scroll backturn the mouse wheel over the paneShift+PageUp / Shift+PageDown
Find in the scrollbackright-click the pane → Find…, then ↑ ↓ on the search barCtrl+B /
Copy textdrag across it (copied when you let go); double-click a wordCtrl+B [ (copy mode)
Open or copy a linkright-click it → Open link / Copy link, or Ctrl-click it
Open a file a pane names, at its lineCtrl-click it, or right-click it → Open in editor
Copy what a command printedright-click it → Copy this command's output
Go from prompt to promptright-click the pane → Previous prompt / Next prompt[ / ] in copy mode
Open a pane's history in your editorright-click the pane → Open the history in my editor
Talk to the agentclick the SHELL chipCtrl+Space
Show or hide the agent panel≡ menu → Talk to the agent / Hide the agent panelCtrl+B a
Resize the agent paneldrag the line between it and the shell
Explain or fix a failed commandclick explain or fix on the status barCtrl+B e / f
Have the agent watch a running commandclick watch on the status barCtrl+B o
Take the agent into a shell you reachedclick take the agent in on the status barCtrl+B i
See every tab's agent, and what needs youclick need you (or agents working) on the status bar, or ≡ menu → Agents and panes at a glanceCtrl+B A
Hear nothing more from a paneright-click it → Don't tell me about this pane
Go to another session, start one, stop oneclick the session's name at the right of the tab bar, or ≡ menu → Sessions…Ctrl+B S
After a restore, run again what was runningclick run again on the status barCtrl+B !
Show the changes, a review, a commit messageclick the git branch on the status barCtrl+B g
Open a layout: tabs, splits and commands≡ menu → Open a layout…Ctrl+B l
A floating pane: open it, put it away, bring it backright-click a pane → Open a floating pane; its ✕Ctrl+B F
Move a pane, or have two change placesright-click it → Move this pane…, then click where it goesCtrl+B M, then click
Save a tab as a layoutright-click the tab → Save this tab as a layout…
Choose a modelclick the model on the status barCtrl+B m
Change how much the agent may doclick ask first (or the level shown) on the status barShift+Tab in the agent panel
Choose a theme≡ menu → Choose a themeCtrl+B s
Settings≡ menu → SettingsCtrl+B .
See every keyclick ? help on the status barCtrl+B ?
Leave, keep everything runningclose the window, or ≡ menu → DetachCtrl+B d
Detach every window from the sessionclose each windowCtrl+B D

The tab bar

In a pane

The status bar

Every piece of the status bar that does something can be clicked:

PieceA click
SHELL / ✦ AGENTswitches your typing between the shell and the agent
^Space agent / ^Space shellthe same: a reminder of the key that does it
explain, fix (after a command fails)has the agent explain the failure, or fix it
watch (while a command of yours runs)has the agent follow the command and say how it went
take the agent in (while ssh, sudo -s and the like run)carries the agent into the shell you reached
◆ and the model's nameopens the list of models
◔ and a level, or ◔ effortopens the levels of how hard the model thinks
ask first, auto read-only, ▶▶ autopilotsteps to the next level of how much the agent may do
? 2 need you, 2 agents workingopens Agents and panes at a glance
? helpshows every key
≡ menuopens the menu of everything

On the left, after the chip, is the folder the shell is in. In a git repository the branch follows it, then what has changed, when there is any: ~/src/app git:main +2 *3 ?1 is two files staged, three changed and not staged, and one git does not track. ! counts files left in conflict, ↑ and ↓ the commits ahead of the upstream branch and behind it, and a merge or rebase stopped half way is named after the branch. The branch is read when the prompt comes back, when the folder changes, and again every ten seconds or so while you work, from the repository's own files; the counts come from git status, which never takes the repository's lock, so a git commit of yours at the same moment is not held up. Without git installed the branch still shows. Turn it off with ≡ menu → Settings → Show the git branch beside the folder (git_status = false in the config file).

Click the branch (or press Ctrl+B g) for what is most often done next:

A shell showing git log, git status and git diff --stat for a project; above the status bar, which reads git:main *1, a small menu: Show the changes, Ask the agent to review my changes, Draft a commit messageA shell showing git log, git status and git diff --stat for a project; above the status bar, which reads git:main *1, a small menu: Show the changes, Ask the agent to review my changes, Draft a commit message
The git branch on the status bar, clicked

A shell on another machine shows the branch of its folder there too, looked up by Astrum's own program on that machine. Its menu has the agent's two entries; the changes themselves are there, not here.

On a narrow terminal, the pieces on the right give way one by one, starting with the reminder of the agent key; ≡ menu is always the last to stay. status_bar = false in the config file hides the bar altogether; Ctrl+B Space still opens the menu.

The ≡ menu

Click ≡ menu at the right-hand end of the status bar for a menu of every action, each with the key that does the same. Click an entry to do it.

The ≡ menu open above the status bar, over an editor and a test run side by side, listing every action from New tab to Help, with the key for each at its rightThe ≡ menu open above the status bar, over an editor and a test run side by side, listing every action from New tab to Help, with the key for each at its right
The ≡ menu

It lists, in order: New tab, New tab on another machine…, Split right, Split down, Zoom pane, Close pane, Next tab and Previous tab (with more than one tab), Rename tab, Find in scrollback, Select with the keyboard, Talk to the agent, Agents and panes at a glance, Sessions…, Open a layout… (once you have one), Explain the last command, Fix the last command, Watch the running command (while one runs), Take the agent into this shell (ssh, sudo…) (while ssh or the like runs), Choose a model, How hard the model thinks, Choose a theme, Settings, Detach (keep everything running), and Help.

Some entries follow the moment: Zoom pane is there only in a tab with more than one pane, and reads Unzoom pane while one is zoomed; Close pane reads Close tab when the tab has only one; Talk to the agent reads Hide the agent panel while the panel is open.

From the keyboard, Ctrl+B Space opens the menu. ↑ and ↓ move through it and Enter picks the entry; or press an entry's own key (c for New tab, say) to pick it at once. Any other key, or a click outside the menu, closes it.

Right-click menus

Right-click a tab or a pane for a menu of what can be done with it. Click an entry, or use ↑ ↓ and Enter; a click outside, or another right-click, closes it.

On a tab

EntryDoes
Renamenames the tab
Move left, Move rightmoves the tab one place (offered where there is a place to move to)
New tabopens a new tab
Close tabcloses the tab and its shells

On a pane

EntryDoes
Open link, Copy linkwhen you right-click a link: opens it (web and mail links only), or copies where it goes
Split right, Split downsplits the pane in two
Find…opens a search of the pane's scrollback
Zoom, Unzoomlets the pane fill the tab, and back (with more than one pane)
Close panecloses the pane; reads Close tab when it is the tab's only pane

Right-clicking a pane the keyboard is not in moves the keyboard there first.

Programs that use the mouse

Programs such as vim and htop take the mouse for themselves, so clicks, drags, the wheel and right-clicks in their pane go to them. Hold Shift to have Astrum take it instead: Shift and drag selects text, Shift and right-click gives Astrum's menu.

How the keys work

The prefix key

Most of Astrum's keys come after a prefix key, Ctrl+B unless you change it: press Ctrl+B, let go, then press the key. Ctrl+B c is a new tab. Keys are case-sensitive: Ctrl+B d detaches this window, Ctrl+B D every window.

After the prefix, the status bar shows PREFIX and what can follow it, each with its key. They can be clicked as well as typed, so the prefix also works as a way into the menu. They wait ten seconds for you, and moving the pointer starts the wait again. When they do not all fit, ≡ more opens the full menu. Esc, or a key that is none of these, lets go without doing anything.

A few things to know:

Keys without the prefix

The help screen

Click ? help on the status bar, or press Ctrl+B ?, for one screen of the keys, grouped as tabs, the agent, and scrolling and copying. It shows the keys as you have set them. Any key or a click closes it.

Changing the keys

Every key Astrum uses can be changed, in the config file. (The settings screen has the settings most people change; keys are not among them.) astrum config says where the file is, and astrum config --init writes a commented starter file there if there is none. A change takes effect in the running session as soon as you save the file: Astrum says "Settings reloaded", or says what is wrong with the file and changes nothing. Settings has the rest of the file.

The prefix and the agent key

Two settings at the top of the file:

prefix = "ctrl+a"         # in place of ctrl+b
agent_key = "f2"          # in place of ctrl+space

On macOS, Ctrl+Space switches input sources when several keyboard layouts are turned on, and some shell plugins use it. If it does something else for you, pick another agent_key, such as "ctrl+backslash" or "f2".

The [keys] table

Every other key is in a [keys] table, by the name of what it does:

[keys]
new_tab = ["c", "ctrl+t"]   # Ctrl+B c as before, and Ctrl+T directly
next_tab = "alt+right"
prev_tab = "alt+left"
split_right = "v"
detach_all = "none"

How it is read:

The names of keys:

WriteFor
a single character: c, D, ,, /, [that key (a capital is Shift and the letter)
space, enter, tab, shift+tab, esc, backspace, delete, insertthose keys
up, down, left, right, home, end, pageup, pagedownthose keys
f1 to f24the function keys
backslash, plus, minusthe \, + and - keys
ctrl+ or alt+ in front (option+ and meta+ mean Alt)the key with Ctrl or Alt held

In macOS terminal apps, the Option key reaches programs as Alt only when the terminal is set to send it that way; check your terminal's settings if an alt+ key does nothing.

The hint line after the prefix, the ≡ menu and the help screen all show the keys as you have set them. When a new release brings a new key that you had already given to something else, it stays yours, and the new action can still be reached from the menu.

Seeing the keys you have

astrum keys

lists every action with the keys it has now and what it does, the same list as below but with your changes in it:

ACTION           KEYS                   WHAT IT DOES
new_tab          c, t                   open a new tab
next_tab         n, tab                 go to the next tab
prev_tab         p, shift+tab           go to the previous tab

Every key

Every action, what it does, and the keys it has before you change any. A plain key is pressed after the prefix, Ctrl+B.

What it doesKeysIts name in [keys]
Open a new tabCtrl+B c or Ctrl+B tnew_tab
Go to the next tabCtrl+B n or Ctrl+B Tabnext_tab
Go to the previous tabCtrl+B p or Ctrl+B Shift+Tabprev_tab
Go to tab 1Ctrl+B 1tab_1
Go to tab 2Ctrl+B 2tab_2
Go to tab 3Ctrl+B 3tab_3
Go to tab 4Ctrl+B 4tab_4
Go to tab 5Ctrl+B 5tab_5
Go to tab 6Ctrl+B 6tab_6
Go to tab 7Ctrl+B 7tab_7
Go to tab 8Ctrl+B 8tab_8
Go to tab 9Ctrl+B 9tab_9
Split the pane, side by sideCtrl+B | or Ctrl+B %split_right
Split the pane, one above the otherCtrl+B - or Ctrl+B "split_down
Move to the pane on the left (or the previous tab)Ctrl+B ←focus_left
Move to the pane on the right (or the next tab)Ctrl+B →focus_right
Move to the pane aboveCtrl+B ↑focus_up
Move to the pane belowCtrl+B ↓focus_down
Let the pane fill the tab, and backCtrl+B zzoom
Close the pane, or the tab when it is the lastCtrl+B x or Ctrl+B wclose
Move the tab one place leftCtrl+B <move_tab_left
Move the tab one place rightCtrl+B >move_tab_right
Leave, keeping everything runningCtrl+B d or Ctrl+B qdetach
Detach every terminal from the sessionCtrl+B Ddetach_all
Show or hide the agent panelCtrl+B aagent_panel
Rename the tabCtrl+B , or Ctrl+B rrename
Have the agent explain the last commandCtrl+B eexplain
Have the agent fix the last commandCtrl+B ffix
Have the agent watch the running commandCtrl+B owatch
Choose a modelCtrl+B mmodel
Choose how hard the model thinksnoneeffort
Choose a themeCtrl+B s or Ctrl+B Ttheme
Show the keysCtrl+B ? or Ctrl+B hhelp
Search the scrollbackCtrl+B /find
Select with the keyboardCtrl+B [copy_mode
Scroll back a pageCtrl+B PageUppage_up
Scroll forward a pageCtrl+B PageDownpage_down
Open the menu of all of theseCtrl+B Spacemenu
Open the settingsCtrl+B .settings
Have the agent work in the shell this pane has reached (ssh, a container, sudo)Ctrl+B iagent_here
Open a tab on another machine, whose shells stay there when the connection dropsCtrl+B Rremote_tab
Every tab's agent and whatever needs you, at a glance: what each is doing, and answering one that asksCtrl+B Aagents
The sessions there are: go to another in this terminal, start one, stop oneCtrl+B Ssessions
After a restore, run again what was running in the paneCtrl+B !run_again
In a git repository: show the changes, have the agent review them, or draft a commit messageCtrl+B ggit
Open a layout: tabs, splits and commands, as a file of yours saysCtrl+B llayout
The floating pane: open one over the tab, bring it back, or put it away (it goes on running)Ctrl+B Ffloat
Move this pane: then click another pane's middle to change places with it, or near one of its edges to go thereCtrl+B Mmove_pane