Starship Customization

Author [custom.<name>] blocks in starship.toml that surface arbitrary state in the prompt. Optimized for novel ideas the built-in modules don't cover.

Operating Principles

1. Performance is the first constraint. Every custom module runs synchronously on every prompt render. A 200ms command makes the shell feel broken. Aim for <50ms; cache or short-circuit otherwise.
2. Trigger before compute. Use detect_files / detect_folders / detect_extensions / os / require_repo to skip the module entirely outside its relevant context. Only fall back to when = "<cmd>" when filesystem triggers are insufficient.
3. Pin the shell. Default shell selection is fragile across machines. Always set shell = ['sh', '-c'] (or ['bash', '--noprofile', '--norc', '-c'] if bashisms are needed) to stop starship from inheriting heavy user profiles and to prevent recursion.
4. Boring before clever. A reliable two-line [custom.foo] beats a witty one-liner that breaks on macOS or in fish. If a recipe needs awk/sed/jq, gate it on command -v.
5. The agent must produce a runnable TOML block, not pseudo-config. Output a complete [custom.<name>] block the user can paste into ~/.config/starship.toml.

Quick Navigation