Themes

Keep your terminal's own colors, pick one of the built-in themes with a live preview, or make a theme of your own.

Your terminal's own colors

Out of the box Astrum uses the theme called terminal: your terminal app's own colors, for the tab bar, the status bar and the agent panel, and for everything programs draw. So starting Astrum changes nothing about how your terminal looks, and if you change your terminal's color scheme, Astrum changes with it. Its highlights are your terminal's own standard colors, and a chosen row is shown in reverse.

In the list of themes it is called Terminal (follow host colors).

Choosing a theme

Open the list of themes with ≡ menu → Choose a theme, or from ≡ menu → Settings → Theme. From the keyboard, press Ctrl+B then s, or type /theme in the agent panel.

The list is a live preview. The theme you are on is put on the whole screen at once, the session behind the list included, so you see it on your own work before you choose it.

The list of themes open over a session split into a test run and an editor, with one theme highlighted and the whole screen behind it drawn in that theme's colorsThe list of themes open over a session split into a test run and an editor, with one theme highlighted and the whole screen behind it drawn in that theme's colors
Moving through the list puts each theme on the screen

To choose one by name, give it to /theme: /theme nord. Capitals do not matter and spaces count as dashes, so /theme Blade Runner 2049 works too.

A theme chosen inside Astrum is remembered for every session, in state.toml. To set it in the config file instead, put theme at the top of the file:

theme = "nord"

A theme chosen inside Astrum takes the place of the config file's until it is forgotten: see Choices made inside Astrum. astrum themes lists the name of every theme there is, yours included.

Colors for programs too

A chosen theme colors Astrum's own bars and panel, and with them what programs draw: their sixteen standard colors, and the plain text and background, are taken from the theme. So a theme is one look, rather than Astrum's bars in one set of colors around a shell in another. A program that asks the terminal for its colors, to tell a dark screen from a light one, is told the theme's.

Colors a program gives exactly, as 24-bit colors or from the 256-color palette beyond its first sixteen, are drawn as the program gave them.

To keep a theme to Astrum's bars and panel and leave programs in your terminal's own colors, turn off Programs use the theme's colors too on the settings screen, or set:

theme_terminal = false

With the terminal theme this makes no difference: there is nothing to recolor programs with.

A light theme for a light terminal

A terminal that is light by day and dark by night can have a theme for each. theme is the one for a dark background and theme_light the one for a light background:

theme = "tokyo-night"
theme_light = "catppuccin-latte"

Which of the two applies is read from the terminal each time one attaches: Astrum asks it what color its background is. A terminal that does not answer counts as dark. While theme_light is set, a theme chosen in /theme goes to whichever the terminal is now, so one chosen on a light background becomes the light theme.

With the default terminal theme there is nothing to set: it is your terminal's own colors either way. Among the built-in themes, Catppuccin Latte is the light one.

24-bit color

A terminal that supports 24-bit color is sent each theme's exact colors. Others are sent the nearest match from the 256-color palette. Astrum tells which a terminal is from what it says about itself (COLORTERM, TERM and TERM_PROGRAM), each time one attaches.

Over SSH, where terminals often cannot say that they have 24-bit color, colors can look reduced. Then set:

truecolor = true

If a terminal claims 24-bit color and shows it wrongly, truecolor = false sends it the 256-color palette instead. Either applies to terminals that attach after it is set: detach and run astrum again. Programs inside Astrum are always told that 24-bit color is there (COLORTERM=truecolor), and Astrum turns what it draws into what your terminal can show.

A theme of your own

A theme of your own is a table in the config file. Every color in it is optional: what you leave out comes from the theme named in based_on. It then appears in /theme and astrum themes with the built-in ones, and is used like them.

theme = "mine"

[themes.mine]
label = "Mine"
based_on = "matrix"
bg = "#000000"
text = "#33ff66"
accent = "#33ff66"

Changes to the table take effect as soon as the file is saved, on the theme in use too. Something that cannot be read, such as a color that is not a color, is left as the theme it is based on had it, and Astrum says what was wrong; astrum themes prints the same.

These are the colors a theme has:

ColorWhat it paints
barThe tab bar and the status bar.
bgThe agent panel, menus and lists.
surfaceRaised parts: the tab in front, the input box, cards.
overlayThe row under the pointer, and the chosen row in a list.
borderFrames, and the dividers between panes.
textOrdinary text.
subtextQuieter text, such as the labels on the bars.
mutedHints, and the faintest labels.
accentThe main highlight: chips, headings, a lit divider.
accent2The second highlight: the + in the tab bar, the spinner of an agent at work, the values on the settings screen.
green, yellow, red, blueWhat is going on: green for a finished agent and for ask first, yellow for an agent that is asking, red for one that stopped, blue for auto read-only.
selectionThe background of text selected in a pane.
on_accentText on an accent-colored chip. Unless given, it is your bar color, if you set one.
term_fg, term_bgThe plain text and the background programs draw in. Unless given, they are your text and bg, if you set those.
ansiThe sixteen standard colors programs use, in their usual order: black, red, green, yellow, blue, magenta, cyan and white, then the bright version of each. It takes all sixteen or none.

term_fg, term_bg and ansi are used only while programs take the theme's colors (theme_terminal).

A light theme of your own, with programs' colors of its own as well:

theme_light = "paper"

[themes.paper]
label = "Paper"
based_on = "catppuccin-latte"
bg = "#fbf8f1"
bar = "#ece6d8"
ansi = [
  "#3b3b3b", "#b3261e", "#2e7d32", "#9a6700", "#1e5fa8", "#8e44ad", "#00838f", "#c8c8c8",
  "#6b6b6b", "#d93025", "#43a047", "#b7791f", "#3182ce", "#9b59b6", "#00acc1", "#ffffff",
]

The built-in themes

Twenty-one themes come with Astrum besides terminal, from calm to neon. Each is drawn here in its own colors, with the name that theme and /theme take:

● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Astrum Night astrum
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Nebula nebula
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Tokyo Night tokyo-night
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Catppuccin Mocha catppuccin
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Catppuccin Latte (light) catppuccin-latte
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Gruvbox Dark gruvbox
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Nord nord
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Dracula dracula
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Rosé Pine rose-pine
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Kanagawa kanagawa
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Everforest everforest
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
One Dark one-dark
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Synthwave synthwave
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Outrun outrun
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Blade Runner 2049 blade-runner-2049
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Cyberpunk 2077 cyberpunk-2077
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Chaos Theory chaos-theory
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Matrix matrix
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
McDermott mcdermott
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Monokai monokai
● 1 zsh 2 logs≡ menu
~/code ❯ ls
src README.md Cargo.toml
error: not found
Solarized Dark solarized
1 zsh≡ menu
~/code ❯ ls
src README.md Cargo.toml
Your terminal's own colors, as they are.
Terminal (follow host colors) terminal