terminal

name: terminal description: Context and rules for any task involving kitty, zsh, or starship — fonts, prompt layout, color generation, plugins, and config file relationships argument-hint: [task description] allowed-tools: Bash, Read, Glob, Grep, Edit, Write

Terminal Setup

Load this before any task touching kitty config, zsh config, starship prompt, or terminal color theming.

Kitty

Config: ~/.config/kitty/kitty.conf

Color generation

colors.conf is auto-generated by matugen — never edit it directly. Edit the template at ~/.config/matugen/templates/kitty-colors instead. It is regenerated on every theme switch via theme-switch.

Colors cover: foreground, background, cursor, selection, URL, tab bar, and the 16 terminal palette colors (color0–color15). The palette maps Material Design 3 tokens:

Zsh

Config: ~/.zshrc

Key settings

Vi mode fixes

Backspace and common kill bindings are explicitly rebound to work correctly in vi insert mode:

^?  → backward-delete-char
^H  → backward-delete-char
^W  → backward-kill-word
^U  → backward-kill-line

Plugins

Syntax highlight style overrides: commands, builtins, and aliases are colored magenta.

Custom functions

asp — AWS profile switcher:

asp() { local p=$(aws configure list-profiles | fzf) && [ -n "$p" ] && export AWS_PROFILE=$p }

Opens an fzf picker of all configured AWS profiles and exports the selection as AWS_PROFILE. The starship prompt reflects the change immediately.

Completion

Menu-style completion with zstyle ':completion:*' menu select. List colors inherit from LS_COLORS, selection highlight uses 48;2;61;50;49 (a dark surface tone matching the current theme).

Prompt

Starship is initialized at the end of .zshrc:

eval "$(starship init zsh)"

Starship

Live config: ~/.config/starship.toml Source template: ~/.config/matugen/templates/starship-colors

Critical: starship.toml is auto-generated by matugen on every theme switch. Never edit starship.toml directly. Always edit the template. After editing the template, either run a theme switch or manually substitute {{colors.outline.default.hex}} with the current outline color and write to starship.toml.

The current outline color comes from color8 in ~/.config/kitty/colors.conf.

Prompt layout

Single-line prompt — no $line_break, all modules on one line:

[left modules: directory, git branch, language contexts...] [right: AWS profile]

Left side uses a custom format string. Right side uses right_format (zsh RPROMPT):

right_format = '$aws'

Left format modules (in order)

$username $hostname $directory
$git_branch $git_commit $git_state $git_metrics
$docker_context $package
$c $cmake $dart $deno $dotnet $elixir $elm $erlang $fennel $fortran $golang $gradle
$haskell $haxe $java $julia $kotlin $lua $nim $nodejs $ocaml $perl $php $python
$rlang $ruby $rust $scala $swift $zig $buf $bun
$nix_shell $conda $meson $memory_usage
$cmd_duration
$jobs $status $character

AWS module

Displayed on the right via right_format. Behavior:

No icon — symbol = "".

Style color is dynamically set from the matugen outline token: bold {{colors.outline.default.hex}}.

Profile aliases (region is embedded in alias string, not pulled from $region):

[aws.profile_aliases]
default = ""
work-dev = "work-dev (us-east-1)"
work-staging = "work-staging (us-east-1)"
work-prod = "work-prod (us-east-1)"

Icons / Nerd Font symbols

All module symbols use Nerd Fonts v3 codepoints (ttf-jetbrains-mono-nerd v3.4.0). The template has the correct unicode codepoints baked in. Most symbols that appear as spaces in plain-text editors are valid Nerd Font private-use-area characters — do not treat them as missing.

git_status is disabled.

Color theming

Only the AWS module style color is themed via matugen ({{colors.outline.default.hex}}). All other module styles use hardcoded values (bold purple, etc.).

Key File Paths

Rules

• Never edit starship.toml or colors.conf directly — changes will be overwritten on next theme switch
• Always edit matugen templates for persistent changes to prompt colors or starship config structure
• After editing the starship template, restore the live file by substituting {{colors.outline.default.hex}} with the value of color8 from colors.conf
• Nerd Font symbols in the starship template must be the actual unicode codepoints — use starship preset nerd-font-symbols to get correct values, then apply with a Python script (editors and linters tend to strip PUA characters)
• The asp function requires fzf and the AWS CLI to be available