System modules

Modules that reflect the operating system, the shell, the user, the working directory, and the result of the previous command. These are the modules most users see on every prompt.

Modules

Module	Default symbol	What it shows	Source
directory	(truncated path)	Current working directory, contracted at $HOME and the git root	src/modules/directory.rs (~1.9K lines)
username	<user>	Active user, only when SSH/different from the login user/root	src/modules/username.rs
hostname	<host>	System hostname, only over SSH by default	src/modules/hostname.rs
localip	(IPv4)	Currently assigned IPv4 address (off by default)	src/modules/localip.rs
os	(icon)	OS family, with per-distro icon in the Nerd Font preset	src/modules/os.rs
shell	(e.g. bsh)	Current shell name (off by default)	src/modules/shell.rs
shlvl	↕️	Current SHLVL (nested shells; off by default)	src/modules/shlvl.rs
time	🕐 hh:mm	Local time (off by default)	src/modules/time.rs
battery	🔋	Battery level + charging state (feature-gated)	src/modules/battery.rs
memory_usage	🐏	Free memory and swap (off by default)	src/modules/memory_usage.rs
jobs	✦	Number of background jobs	src/modules/jobs.rs
cmd_duration	took 2s	Time the previous command took	src/modules/cmd_duration.rs
status	✘ 1	Exit code of the previous command (off by default)	src/modules/status.rs
sudo	sudo	Indicator that sudo credentials are cached (off by default)	src/modules/sudo.rs
character	❯ (red on error)	Final prompt arrow with success/error/vi-mode color	src/modules/character.rs
line_break	\n	Forces a newline (separates prompt into two lines)	src/modules/line_break.rs

Standout modules

directory

The directory module is one of the largest modules at ~1.9K lines because it juggles a lot of concerns:

• Contraction of $HOME to a configurable home symbol (default ~) and the git repo root to the repo name.
• Substitution of arbitrary substrings via the [directory.substitutions] table — configurable regex replacements applied to the full path.
• Truncation to N path components (default 3) with optional fish-style abbreviated parents (e.g. ~/.l/s/starship).
• Repo style — separate styles for in-repo paths and in-repo prefixes via repo_root_style / repo_root_format.
• Read-only / unwritable indicator via read_only symbol.
• Cross-platform path normalization — Windows extended-path stripping, slash normalization, UNC handling.

Platform-specific helpers live under src/modules/utils/directory_nix.rs and directory_win.rs, dispatched at compile time.

character

The character module owns the final prompt arrow. It has special handling for shell vi mode: zsh's vicmd, fish's default (which is the vi normal mode), and PowerShell/Cmd's vi. The init scripts pass the current keymap into starship prompt via --keymap=.... The module then picks one of:

• success_symbol (default ❯ bold green)
• error_symbol (default ❯ bold red)
• vimcmd_symbol (default ❮ bold green)
• vimcmd_visual_symbol / vimcmd_replace_symbol / vimcmd_replace_one_symbol

Fish reports normal mode as default, which is also the name fish uses when vi mode is off. The init script in src/init/starship.fish does environment detection so non-vi fish always reports insert.

cmd_duration

This module receives the elapsed time of the previous command via --cmd-duration=…. The shell init scripts compute it by running starship time (epoch milliseconds) before and after each command — see src/init/starship.bash for the bash flavor that relies on the DEBUG trap and STARSHIP_PREEXEC_READY flag, or src/init/starship.fish for the fish flavor that uses $CMD_DURATION directly.

status

The status module receives the previous command's exit status via --status=$? and (where supported) the full pipeline status via --pipestatus=$PIPESTATUS. It can decode signal numbers (SIGTERM=15, etc.), display "common" exit codes by name, recognize SIGPIPE as a non-error, and apply a different style on signal vs non-zero exit.

os

The os module shows an icon for the detected OS family. Symbols for ~50 distros are baked into src/configs/os.rs (Alpine, Arch, Arkane, BSD, Debian, …), each as both an emoji and a Nerd Font glyph. The os_info crate detects the host OS.

battery

battery is feature-gated behind --features battery and uses the starship-battery crate. It is disabled on Termux because the underlying Rust battery crate does not build there. The module supports multiple thresholds: full_symbol, charging_symbol, discharging_symbol, unknown_symbol, empty_symbol, plus per-threshold display rules.

Special render targets

These three modules are aware of the prompt's render target (left, right, continuation):

• character — only renders for Target::Main and (some configurations of) Target::Profile.
• line_break — emits a newline. The right prompt strips newlines, so on Target::Right this module's output is dropped.
• fill — pads the line to terminal width using a configurable pad string. See Special modules.

Entry points for modification

• New OS icon: edit src/configs/os.rs.
• New status decoding (e.g., a new signal): edit find_signal_name in src/modules/status.rs.
• New directory truncation strategy: edit truncate in src/modules/utils/directory.rs.
• New keymap mapping for vi mode: edit module(context) in src/modules/character.rs and update the corresponding init script if a new shell is involved.