Spaceship Prompt — Powerful Customizable Zsh Prompt

Introduction

Spaceship is a Zsh prompt theme that surfaces context-aware information right in your terminal prompt. It shows the current Git branch, package version, active runtime versions, Docker context, kubectl cluster, and battery status without requiring manual commands. Its async rendering keeps the prompt fast even with many sections enabled.

What Spaceship Does

• Displays Git status, branch, and stash count inline in the prompt
• Shows active versions for Node, Python, Ruby, Go, Rust, PHP, and others
• Renders Docker, kubectl, Terraform, and AWS context when relevant
• Uses async rendering so slow sections do not block prompt display
• Supports custom sections via a documented plugin API

Architecture Overview

Spaceship is written in pure Zsh script with no external dependencies beyond Zsh itself. Each prompt section is a self-contained function that checks whether its context is relevant (e.g., a package.json exists) before rendering. Sections run asynchronously using zsh-async, and results are cached until the working directory changes.

Self-Hosting & Configuration

• Configure via a .spaceshiprc.zsh file or SPACESHIP_* environment variables
• Enable or disable individual sections with SPACESHIP_
  _SHOW=true|false
• Reorder sections by setting SPACESHIP_PROMPT_ORDER as an array
• Custom colors and symbols are configurable per section
• Works with any Zsh plugin manager: Oh My Zsh, Zinit, Sheldon, Antidote

Key Features

• 40+ built-in sections covering languages, tools, cloud providers, and VCS
• Async rendering keeps prompt latency low regardless of section count
• Extensible plugin API for adding custom sections
• vi-mode indicator and execution time display built in
• Active community with frequent updates and comprehensive documentation

Comparison with Similar Tools

• Starship — cross-shell Rust binary; Spaceship is Zsh-native with deeper Zsh integration
• Powerlevel10k — Zsh theme focused on speed with wizard setup; Spaceship favors simplicity and readability
• Pure — minimalist Zsh prompt; Spaceship shows far more contextual information
• Oh My Posh — cross-platform Go-based prompt engine; Spaceship requires no external binary
• Liquidprompt — Bash/Zsh adaptive prompt; Spaceship offers richer language-runtime sections

FAQ

Q: Does Spaceship slow down my terminal? A: Async rendering ensures slow-to-compute sections (like Git status on large repos) do not block the prompt.

Q: Can I use Spaceship with Bash or Fish? A: No. Spaceship is Zsh-only. For cross-shell prompts, consider Starship.

Q: How do I add a custom section? A: Create a spaceship_ function following the section API docs, then add it to SPACESHIP_PROMPT_ORDER.

Q: Does it work in VS Code and JetBrains terminals? A: Yes, as long as the integrated terminal runs Zsh and a Nerd Font is configured.

Sources

• https://github.com/spaceship-prompt/spaceship-prompt
• https://spaceship-prompt.sh