Logger

Starship has its own log::Log implementation in src/logger.rs. It writes to a per-session file under ${STARSHIP_CACHE:-$HOME/.cache}/starship/session_<shell-pid>.log, deduplicates repeating warnings, and sweeps stale log files.

Log levels

Level	Set via	Behavior
error	STARSHIP_LOG=error	Only errors. Default.
warn	STARSHIP_LOG=warn	Errors + warnings.
info, debug, trace	etc.	Progressively noisier.

The level is parsed from the STARSHIP_LOG env var when logger::init() is called from src/main.rs.

Where logs go

The default log directory is computed by get_log_dir():

1. $STARSHIP_CACHE, if set.
2. Otherwise: ~/.cache/starship (or platform equivalent via dirs::cache_dir).
3. Last resort: <temp>/starship.

Inside the directory, log files are named session_<id>.log where <id> is the shell PID + invocation count for the current session. New runs append.

Output is also written to stderr at error level (always) and at warn/info/debug/trace if STARSHIP_LOG requests it. The stderr path is what makes STARSHIP_LOG=trace starship prompt useful for live debugging.

Deduplication

StarshipLogger tracks a RwLock<HashSet<String>> of recently-emitted messages. The same message at the same level is only written once per session. This is what stops a misconfigured custom module from filling the log with the same warning hundreds of times.

Cleanup

cleanup_log_files(log_dir) runs once per starship invocation, in a rayon background task spawned from main():

rayon::spawn(|| {
    let log_dir = logger::get_log_dir();
    logger::cleanup_log_files(log_dir);
});

It walks the log directory and deletes any session_*.log whose mtime is older than 24 hours. Errors during cleanup are silently swallowed — this is best-effort housekeeping.

Implementation notes

• The log file is opened lazily via OnceLock so no I/O happens unless something actually logs.
• The file is wrapped in Mutex<File> for thread safety; the rayon pool may have multiple modules logging concurrently.
• Log messages include color escape sequences when written to stderr, but plain text when written to disk.

Entry points for modification

• Change the log file location: edit get_log_dir in src/logger.rs.
• Change the cleanup window: the 24-hour threshold is hardcoded as 60 * 60 * 24.
• Add structured logging: today the logger emits a single line per record (level, file, line, module path, message). Adding JSON output would mean a new Log::log impl branch.