Starship Passthrough

CShip lets you embed any Starship module directly in your statusline layout, right next to native CShip modules.

How It Works

Any token in a lines format string that doesn't start with cship. is treated as a Starship module name. CShip invokes starship module <name> as a subprocess, captures its stdout, and splices the output into your statusline.

toml

[cship]
lines = [
  "$directory $git_branch $git_status",
  "$cship.model  $cship.cost  $cship.context_bar",
]

In the example above, $directory, $git_branch, and $git_status are Starship passthrough modules. $cship.model, $cship.cost, and $cship.context_bar are native CShip modules.

Prerequisite: Starship must be installed and on your $PATH.

CSHIP_* Environment Variables

Before each Starship subprocess call, cship sets the following environment variables so your Starship modules can access Claude Code session data:

Variable	Type	Example	Description
`CSHIP_MODEL`	string	`claude-sonnet-4-5`	Active model display name
`CSHIP_MODEL_ID`	string	`claude-sonnet-4-5-20251022`	Full model identifier
`CSHIP_COST_USD`	float	`1.234`	Session cost in USD
`CSHIP_CONTEXT_PCT`	float	`42.5`	Context window used (%)
`CSHIP_CONTEXT_REMAINING_PCT`	float	`57.5`	Context window remaining (%)
`CSHIP_VIM_MODE`	string	`NORMAL`	Current vim mode (empty if inactive)
`CSHIP_AGENT_NAME`	string	`claude-code`	Active agent name (empty if none)
`CSHIP_SESSION_ID`	string	`abc123...`	Session UUID
`CSHIP_CWD`	string	`/home/user/project`	Current working directory

These variables are available inside any custom Starship module you write. For example, you could create a Starship module that changes colour based on CSHIP_COST_USD.

Cache Behaviour

Passthrough module output is cached for 5 seconds per session to avoid spawning a new Starship subprocess on every statusline render.

Cache path: {dirname(transcript_path)}/cship/{transcript_stem}-starship-{module_name}

The cache is keyed by session transcript path, so different Claude Code sessions maintain independent caches. The cache directory is created automatically if missing.

Process Details

The subprocess runs with the working directory set to workspace.current_dir
Stderr from the Starship subprocess is discarded
If Starship is not found or the subprocess fails, the module renders empty (silent failure — no error shown in the statusline)
The first call in a session may take a moment; subsequent calls within 5s use the cache

Example: Mixed Native + Passthrough Config

toml

[cship]
lines = [
  """
  $directory\
  $git_branch\
  $git_status\
  $python\
  $nodejs\
  $rust
  """,
  "$cship.model $cship.agent",
  "$cship.context_bar $cship.cost $cship.usage_limits",
]

[cship.model]
symbol = "🤖 "
style  = "bold fg:#7aa2f7"

[cship.agent]
symbol = "↳ "
style  = "fg:#9ece6a"

[cship.context_bar]
width              = 10
style              = "fg:#7dcfff"
warn_threshold     = 40.0
warn_style         = "fg:#e0af68"
critical_threshold = 70.0
critical_style     = "bold fg:#f7768e"

[cship.cost]
style              = "fg:#a9b1d6"
warn_threshold     = 2.0
warn_style         = "fg:#e0af68"
critical_threshold = 5.0
critical_style     = "bold fg:#f7768e"

The first row uses a multi-line TOML string with \ line continuations to combine several Starship passthrough modules without spaces between them (Starship handles its own spacing). The second and third rows are pure native cship modules.

Caveats

Starship must be installed. The CShip curl installer can optionally install it for you.
Passthrough adds a subprocess call overhead. The 5s cache keeps this negligible after the first render.
CSHIP_* variables reflect the values at render time. Starship modules that consume them will update every 5s (cache TTL).

Starship Passthrough ​

How It Works ​

CSHIP_* Environment Variables ​

Cache Behaviour ​

Process Details ​

Example: Mixed Native + Passthrough Config ​

Caveats ​