Customization on aibox

Prompt Presets

Mon, 01 Jan 0001 00:00:00 +0000

Starship Prompt Presets

aibox includes 8 Starship prompt presets that work with any theme. Set a preset in aibox.toml:

[customization]
prompt = "default"

Available Presets

default

Full-featured two-line prompt with directory, git branch/status, language versions, and command duration. Uses Nerd Font symbols.

 ~/workspace/myproject main ✓ v1.75.0 took 2s
❯

plain

Same information as default but uses ASCII characters only — no Nerd Font or special font needed. Works in any terminal.

~/workspace/myproject [main +1 !2] [v1.75.0] took 2s
>

Good for remote SSH sessions or environments without font customization.

Custom Themes

Mon, 01 Jan 0001 00:00:00 +0000

Creating Custom Themes

aibox ships 7 built-in themes. You can create a custom theme by adding entries to the CLI source code.

Theme Structure

Each theme defines colors for 5 tools:

Tool	Config Location	Format
tmux	`.config/tmux/themes/<name>.conf`	tmux style settings
Vim	`.vim/colors/<name>.vim`	Vim colorscheme
Yazi	`.config/yazi/theme.toml`	TOML with hex colors
lazygit	`.config/lazygit/config.yml`	YAML gui.theme section
Starship	`.config/starship.toml`	TOML with palette

Color Mapping

A theme needs these terminal color slots for tmux:

Layouts

Mon, 01 Jan 0001 00:00:00 +0000

Layouts

aibox ships four tmux layouts. Harness placement follows [ai].harness_order: the 1st harness is the first enabled harness in that order, then the 2nd, 3rd, and so on. Enabled harnesses missing from harness_order are appended in canonical order.

Generated layouts can include an extended PowerKit status bar with host, network, development, cloud, resource, and aibox runtime segments.

Available Layouts

ai

Window	Contents
1 · work	left 50%: yazi · right 50%: 1st harness
2 · ai	all further harnesses, split as full-height even horizontal panes
3 · lazygit	lazygit, when `git-ui` selects `lazygit`
3/4 · shell	bash

dev

Window	Contents
1 · work	left 50%: yazi top 50% / 1st harness bottom 50% · right 50%: shell
2 · lazygit	lazygit, when `git-ui` selects `lazygit`
2/3 · ai	all further harnesses, split as full-height even horizontal panes
final · shell	bash

focus

Window	Contents
1 · files	yazi
2..n · harness name	one fullscreen window per harness in `harness_order`
next · lazygit	lazygit, when `git-ui` selects `lazygit`
final · shell	bash

cowork

Window	Contents
1 · work	left 50%: yazi · right 50%: shell
2 · ai	all harnesses, split as full-height even horizontal panes
3 · lazygit	lazygit, when `git-ui` selects `lazygit`

Setting The Default Layout

[customization]
layout = "dev"

Options: dev, focus, cowork, ai.

Custom Prompts

Mon, 01 Jan 0001 00:00:00 +0000

Creating Custom Prompts

aibox generates Starship prompt configurations from the selected preset and theme. You can customize the prompt by editing the generated config.

Generated Config Location

After aibox apply, the Starship config is at:

.aibox-home/.config/starship.toml

Manual Customization

Edit .aibox-home/.config/starship.toml directly with any valid Starship configuration. Changes take effect immediately in new shell sessions.

Apply overwrites

aibox apply regenerates starship.toml from the preset and theme. To preserve manual edits, either avoid running apply or back up your config first.

Agent attention titles

Mon, 01 Jan 0001 00:00:00 +0000

When an AI harness needs a human response, aibox can mark the tmux window in the terminal tab title. This is useful when the agent is running in a background pane or another tmux window: the title remains visible even when that pane is not selected.

Configuration

Titles are configured in aibox.toml:

[customization.tmux.title]
enabled = true
format = "{state_symbol}{project}:{window} — {directory}"
max-length = 60
directory-style = "basename"
done-ttl-seconds = 10
message-max-length = 32

[customization.tmux.title.states]
working = "● "
question = "❓ "
done = "✓ "
error = "! "
idle = ""

[customization.tmux.notifications]
enabled = false
protocol = "osc-9" # or "bell"
states = ["question", "error"]
include-message = true

enabled = false disables generated title settings. The default title is short and project-oriented; use a custom format when session or harness identity is more useful than the directory:

Color Themes

Mon, 01 Jan 0001 00:00:00 +0000

Themes

aibox supports consistent color theming across all terminal tools. Set a theme in aibox.toml:

[customization]
theme = "gruvbox-dark"
mode = "auto"

Or during project initialization:

aibox init --theme catppuccin-mocha

The selected theme is applied to tmux, Vim, Yazi, lazygit, and Starship simultaneously.

mode = "auto" follows the host OS light/dark appearance when a host signal is detectable during aibox apply, aibox up, or aibox set theme.*. Containers do not receive live macOS/Windows/Linux appearance-change events, so rerun one of those commands to regenerate mounted runtime theme files after changing the host appearance. If the host appearance cannot be detected, auto preserves the selected concrete theme.