Customization

• 1: Prompt Presets
• 2: Custom Themes
• 3: Layouts
• 4: Custom Prompts
• 5: 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 - 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