Customization

• 1: Prompt Presets
• 2: Custom Themes
• 3: Layouts
• 4: Custom Prompts
• 5: Agent attention titles
• 6: Color Themes

1 - Prompt Presets

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.

minimal

Directory and git branch only, with a ❯ indicator. Two-line. For distraction-free, low-noise work.

~/workspace/myproject on main
❯

nerd-font

Rich prompt with Nerd Font icons for OS, language runtimes, git status, Docker context, and system info. Requires a Nerd Font installed on the host terminal.

 ~/workspace  main  +1 !2   v1.75.0  🐳 dev  3s
❯

pastel

One-line pastel powerline prompt inspired by Starship’s Pastel Powerline preset. Directory, git, language runtimes, command duration, and character appear inline in connected colored segments. Nerd Font recommended.

 ~/workspace/myproject  main +1 
❯

powerline-pastel

Explicit name for the one-line pastel powerline prompt. The legacy pastel-powerline name is still accepted as an alias.

bracketed

Each segment wrapped in square brackets — [dir] [branch] [status]. Clean, structured appearance without special fonts. A good alternative to plain with more visual structure.

[~/workspace/myproject] [main] [+1 !2]
❯

arrow

Airline/powerline-style prompt with hard chevron separators (►). Segments for directory, git branch, and git status appear as connected colored blocks, with command duration shown inline. Requires a Nerd Font or Powerline-patched font.

 ~/workspace/myproject  main +1 !2  took 3s
❯

Changing Presets

1. Edit aibox.toml:

   [customization]
   prompt = "arrow"
   

2. Run apply:

   aibox apply
   

The Starship config is regenerated at .aibox-home/.config/starship.toml. Colors are derived from the active theme.

Font Requirements

Install a Nerd Font from nerdfonts.com and configure it in your terminal emulator to use icon-based presets.

2 - Custom Themes

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:

Color Mapping

A theme needs these terminal color slots for tmux:

Adding a Theme

To add a new theme to aibox, you need to modify cli/src/themes.rs (theme data) and cli/src/config.rs (Theme enum). See the existing themes as reference patterns.

The projectious theme (cli/src/themes.rs) is a good starting point — it uses a simple palette with clear semantic mappings.

Manual Overrides

If you don’t want to modify the CLI, you can manually edit the config files in .aibox-home/ after aibox apply. Note that aibox apply will overwrite theme-dependent files, so manual edits need to be reapplied after each apply.

3 - Layouts

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

dev

focus

cowork

Setting The Default Layout

[customization]
layout = "dev"

Options: dev, focus, cowork, ai.

Per-Session Override

aibox up --layout focus

This does not change the default in aibox.toml.

4 - Custom Prompts

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.

Adding Custom Presets

Custom presets can be added to cli/src/themes.rs in the starship_config() function. Each preset is a Starship TOML template with color variables ({bg}, {fg}, {accent}, {green}) that are replaced with theme-specific values at generation time.

See the existing presets (default, plain, minimal, nerd-font, pastel, powerline-pastel, bracketed, arrow) as reference patterns.

5 - Agent attention titles

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:

format = "{state_symbol}{harness} — {project}:{window}"

Supported placeholders are:

State is aggregated across all panes in the window. The precedence is error > question > working > done > idle, so a question in a background pane cannot be hidden by an idle active pane. Completion markers are temporary and use done-ttl-seconds.

Harness support and fallback

Harness integration is capability-based:

Current generated integrations:

Gemini and Codex classify an after-turn response ending in a question mark as question. OpenCode uses its explicit question.asked, question.replied, and question.rejected events. Copilot reports permission and elicitation dialogs as questions; its stop payload does not expose final response text.

aibox does not infer a question from process idleness. For a harness without a question hook, signal it explicitly, for example:

aibox-agent-signal question --harness my-harness --message 'Choose an option'
aibox-agent-signal working --harness my-harness
aibox-agent-signal done --harness my-harness

Signals are scoped to the current tmux pane and are safe to repeat. Outside tmux they are a no-op, so the same wrapper can be used in and out of aibox workspaces without affecting the terminal.

Terminal and shell title ownership

Terminal emulators normally display the title emitted by tmux through the standard title control sequence. Do not configure a competing fixed tab title for an aibox tab. Inside tmux, tmux should be the sole title writer; otherwise a shell precmd hook can overwrite the attention marker. This title path does not depend on Ghostty or any other specific terminal emulator.

If you currently set the title from zsh, keep that behavior outside tmux only:

if [[ -z "$TMUX" ]]; then
  precmd() {
    print -Pn '\e]2;%~\a'
  }
fi

Terminal notifications are optional and transition-based. Configure them with [customization.tmux.notifications]:

Notifications are emitted only from inside tmux and only on aggregate state transitions. OSC 9 is supported by terminals including Ghostty and iTerm2 but is not universal; choose bell when portability matters and configure the terminal’s bell attention behavior as desired. Title rendering remains independent and non-fatal if notifications are unavailable.

Security and limits

Agent-provided messages are stripped of terminal control characters and truncated to message-max-length, then the complete title is bounded by max-length. This prevents task text or a question from injecting terminal escape sequences.

6 - Color Themes

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.

mode = "light" and host-light auto use the selected theme family’s light partner when one exists. Genuinely dark-only themes stay on the selected concrete theme instead of falling back to an unrelated light theme.

Available Themes

aibox supports the tmux-powerkit popular theme roster plus aibox-specific extensions:

• tokyo-night, tokyo-night-storm, tokyo-night-day
• catppuccin-mocha, catppuccin-macchiato, catppuccin-frappe, catppuccin-latte
• dracula, dracula-soft, nord, gruvbox-dark, gruvbox-light
• rose-pine, rose-pine-moon, rose-pine-dawn
• material, material-ocean, material-palenight, material-lighter, material-darker
• solarized-dark, solarized-light
• github-dark, github-dark-dimmed, github-dark-high-contrast, github-light, github-light-high-contrast
• ayu-dark, ayu-mirage, ayu-light, night-owl, night-owl-light, moonlight
• everforest-dark, everforest-light, kanagawa-wave, kanagawa-dragon, kanagawa-lotus
• min-dark, min-light, one-dark-pro, one-light, slack-dark, slack-ochin
• vitesse-dark, vitesse-light, vitesse-black, vscode-dark-plus, vscode-light-plus
• andromeeda, aurora-x, houston, laserwave, monokai, plastic, poimandres, red, snazzy-light, synthwave-84, vesper
• projectious

Light/Dark Partners

Dark-only or single-variant themes with no light partner: andromeeda, aurora-x, houston, laserwave, monokai, moonlight, nord, plastic, poimandres, projectious, red, snazzy-light, synthwave-84, and vesper.

gruvbox-dark (default)

Retro groove color scheme with warm, earthy tones. High contrast and easy on the eyes.

• Background: #282828 (dark brown-gray)
• Accent: #D79921 (warm yellow)
• Style: Dark, warm, retro

catppuccin-mocha

Soothing pastel theme with a dark background. The most popular modern terminal theme.

• Background: #1E1E2E (deep purple-black)
• Accent: #89B4FA (soft blue)
• Style: Dark, pastel, modern

catppuccin-latte

Light variant of Catppuccin. Clean and readable in bright environments.

• Background: #EFF1F5 (warm white)
• Accent: #1E66F5 (vivid blue)
• Style: Light, pastel, modern

dracula

Dark theme with vibrant colors. A classic among developers.

• Background: #282A36 (dark gray-blue)
• Accent: #BD93F9 (purple)
• Style: Dark, vibrant, bold

tokyo-night

Inspired by Tokyo’s night lights. Clean and modern with blue tones.

• Background: #1A1B26 (deep blue-black)
• Accent: #7AA2F7 (bright blue)
• Style: Dark, cool, modern

nord

Arctic, north-bluish color palette. Minimalist and calm.

• Background: #2E3440 (dark blue-gray)
• Accent: #88C0D0 (frost blue)
• Style: Dark, cool, minimalist

projectious

The projectious.work brand theme. Deep navy base with a vivid orange accent.

• Background: #1d3352 (midnight navy)
• Accent: #E05232 (ember orange)
• Midtone: #546a82 (slate blue)
• Style: Dark, professional

How It Works

Each theme is a coordinated set of config files applied to all tools when aibox apply, aibox up, or aibox set theme.* regenerates managed runtime files:

Claude Code inherits terminal colors automatically — no separate theme file needed.

Changing Themes

To switch light/dark mode in an existing project:

aibox set theme.mode auto
aibox set theme.mode light
aibox set theme.mode dark
aibox set theme.name tokyo-night

This updates [customization].mode in aibox.toml and regenerates the mounted runtime theme files under .aibox-home/. The running container is not stopped.

If the project tmux session is running, refresh and attach it without stopping the container:

aibox set theme.mode dark --restart-session