Optimizing for Task‐Specific Functions - MoonBase-Dev/moon-base GitHub Wiki

Starship's power lies in its modularity and extensive configurability, making it an excellent tool for optimizing your prompt for various task-specific functions. By tailoring your starship.toml file, you can ensure your prompt provides exactly the information you need, when you need it, without unnecessary clutter.

Before diving into specific use cases, consider these general best practices for an optimized Starship prompt:

1. Prioritize Relevant Information: Your prompt should be an at-a-glance dashboard. Only display information that is directly useful for your current task. Remove modules that provide redundant or rarely needed details.
2. Optimize for Speed: While Starship is fast, certain modules (especially those involving external commands or large file system scans like git_status in very large repositories) can introduce latency.
   • command_timeout: Increase this value in your global settings if you find modules timing out, but be mindful of increasing overall prompt latency.
   • scan_timeout: Similar to command_timeout, this impacts file system scans.
   • Disable Unused Modules: The simplest way to optimize is to disable modules you don't use by setting disabled = true in their respective sections.
   • Contextual Display: Configure modules to only appear when their information is relevant (e.g., Python module only in Python projects).
3. Visual Hierarchy and Readability: Use colors, symbols, and formatting to create a clear visual hierarchy. Important information should stand out, while less critical details can be more subdued.
   • Palettes: Use [palettes] to define consistent color schemes for different states (e.g., success, error, specific environments).
   • format Strings: Craft concise format strings for each module.
4. Multi-line vs. Single-line: For complex workflows, a two-line prompt (using add_newline = true) can provide more real estate for information without pushing your command input too far to the right. Consider using right_format for less critical information that can intelligently hide when your input overlaps.
5. Transient Prompt: Enable transient_prompt to reduce prompt clutter after a command executes, keeping your scrollback clean and focused on output.

Here are some examples of how to optimize Starship for different roles and tasks:

Developers often need immediate feedback on their code and environment.

Key Modules to Enable/Configure:

• directory: Crucial for navigation.
  • truncation_length: Shorten long paths.
  • truncate_to_repo: Show path relative to Git root.
• git_branch: Always visible for current branch.
• git_status: Essential for understanding repository state (untracked, modified, staged, conflicts).
  • Customize symbol for each status type (e.g., 📝 for untracked, ✅ for staged).
• Language-Specific Modules:
  • nodejs, python, rust, golang, php, java, ruby, c, cpp, deno, elixir, haskell, kotlin, lua, perl, r, swift, terraform, zig.
  • Configure them to show version and relevant environment (e.g., Python virtual environment).
  • Consider detect_files, detect_extensions, detect_folders to ensure they only activate in relevant project directories.
• cmd_duration: Useful for timing builds or long-running scripts.
• container: If working with Docker/Podman (shows if inside a container).
• kubernetes: If working with Kubernetes (shows current context).

Example Snippet for starship.toml:

# Developer-focused configuration

add_newline = true
format = """\
[┌─](bold blue)\
$username@$hostname \
$directory\
$git_branch\
$git_status\
$python\
$nodejs\
$rust\
$golang\
$terraform\
[─┐](bold blue)
[└─](bold blue)\
$character
"""

# Git branch: Always visible, bold green
[git_branch]
symbol = " "
style = "bold green"
format = "[$symbol$branch]($style) "

# Git status: Detailed, custom symbols
[git_status]
conflicted = "🏳‍🌈"
ahead = "🏎️💨"
behind = "🐢"
diverged = "😵‍💫"
untracked = "📝"
stashed = "📦"
modified = "✍️"
staged = "✅"
renamed = "🔁"
deleted = "🗑️"
style = "bold purple" # Differentiate from branch color
format = "([$all_status$ahead_behind]($style))"

# Python module: Show version and virtual environment
[python]
symbol = "🐍 "
pyenv_version_name = true
format = "via [${symbol}${version}(\\($virtualenv\\))]($style) "
style = "bold yellow"

# Node.js module: Show version
[nodejs]
symbol = " "
format = "via [${symbol}${version}]($style) "
style = "bold green"

# Command duration: Show for commands longer than 5 seconds
[cmd_duration]
min_time = 5000 # milliseconds
format = "took [$duration]($style) "
style = "bold yellow"

# Kubernetes module: Only show if Kubeconfig is active
[kubernetes]
format = "on [󱃾 $context](bold cyan) "
disabled = false # Ensure it's enabled if you use K8s

Sysadmins and DevOps engineers need quick access to host, user, and network information, as well as status of services and cloud environments.

Key Modules to Enable/Configure:

• username: Crucial, especially for distinguishing between regular user and root.
  • show_always = true (if on shared systems).
  • style_root: Make root user prompt very distinct (e.g., bold red).
• hostname: Essential for remote sessions (SSH).
  • ssh_only = false (if you want it always, or true if only for SSH).
• shlvl: Indicates nested shell levels.
• aws, gcloud, azure: Crucial for cloud context.
  • Display account/profile, region.
• kubernetes: As above, if managing clusters.
• custom modules: For specific checks (e.g., ping to a critical service, custom scripts for server health).
  • See "Leveraging Custom Modules" below.
• time: Can be useful for logging or tracking.
• battery: Less critical for servers, but good for laptops used by sysadmins.

Example Snippet for starship.toml:

# Sysadmin/DevOps-focused configuration

add_newline = false # Keep it compact
format = """\
$username@$hostname \
$shlvl\
$directory\
$git_branch\
$git_status\
$aws\
$gcloud\
$kubernetes\
$character
"""

# Username module: Always show, distinct for root
[username]
show_always = true
style_user = "bold blue"
style_root = "bold red"
format = "[$user]($style) "

# Hostname module: Always show, distinct color
[hostname]
ssh_only = false # Show hostname even when not SSHing
style = "bold green"
format = "on [$hostname]($style) "

# AWS module: Show profile and region
[aws]
symbol = " "
format = "on [$symbol($profile )($region )]($style) "
style = "bold orange"

# Kubernetes module: Show context and namespace
[kubernetes]
symbol = "󱃾 "
format = "on [$symbol$context/$namespace]($style) "
style = "bold cyan"
disabled = false

# Custom module for a quick health check (e.g., check if a critical service is running)
[custom.service_status]
description = "Check status of a critical service"
command = "systemctl is-active --quiet critical-service.service && echo '✅' || echo '❌'"
when = "true" # Always run, or contextually
shell = ["bash", "--noprofile", "--norc"] # Ensures fast execution
format = "[$output]($style) "
style = "bold white"

Data scientists often work with Python, Conda environments, Jupyter notebooks, and specific data formats.

Key Modules to Enable/Configure:

• directory: Especially truncate_to_repo for project roots.
• python: Crucial for virtual environments (venv, Conda).
  • Ensure it displays the active environment.
• conda: Explicitly show Conda environment.
• docker_context: If using Docker for isolated environments.
• custom modules:
  • Detecting specific data file types (e.g., .ipynb for Jupyter, .parquet, .csv).
  • Indicating an active Jupyter kernel.
• time: For timing long data processing jobs.

Example Snippet for starship.toml:

# Data Scientist / ML Engineer configuration

add_newline = true
format = """\
$directory\
$git_branch\
$git_status\
$conda\
$python\
$docker_context\
$custom.jupyter_status\
$character
"""

# Python module: Focus on virtual environment
[python]
symbol = "🐍 "
pyenv_version_name = true
format = "via [${symbol}${version} (\($virtualenv\))]($style) "
style = "bold blue"

# Conda module: Separate from Python, if needed for clarity
[conda]
symbol = " "
format = "on [${symbol}${environment}]($style) "
style = "bold green"

# Custom module: Indicate if a Jupyter notebook is active
[custom.jupyter_status]
description = "Indicate active Jupyter server"
command = "pgrep -f jupyter-notebook > /dev/null && echo '📓' || true" # Check for running Jupyter process
when = "true" # Or define specific project contexts
shell = ["bash", "--noprofile", "--norc"]
format = "[$output]($style) "
style = "bold yellow"

Starship's [custom.<name>] module is incredibly powerful for task-specific functions. You can:

• Run Arbitrary Commands: Display the output of any shell command.
• Detect Files/Folders: Use detect_files, detect_extensions, detect_folders to make custom modules appear only when relevant.
• Environment Variables: Check specific environment variables (when = "env STARSHIP_MY_VAR") to activate a module.
• Conditional Display: Use when to define complex conditions for module visibility.

Example: Custom Module for npm Script Availability:

[custom.npm_scripts]
description = "Show if package.json has scripts"
command = "test -f package.json && grep -q '\"scripts\":' package.json && echo '📜' || true"
detect_files = ["package.json"]
format = "[$output]($style)"
style = "bold magenta"

• starship explain: This command will show you the parsed configuration and active modules.
• starship timings: This command is invaluable for debugging performance issues. It breaks down the time taken by each module to render, helping you identify bottlenecks.
  • Run env STARSHIP_LOG=trace starship timings for very verbose output.
• Test in New Shells: Always open a new terminal session after modifying starship.toml to ensure changes are applied and to test initial load times.

By thoughtfully configuring your starship.toml with these best practices and task-specific modules, you can transform your Starship prompt into an indispensable tool that enhances your productivity in any workflow.