⚓ CShip (pronounced "sea ship")

A beautiful, fully customizable statusline for Claude Code Starship-style TOML config, themeable colours, Nerd Font glyphs, and tunable cost/context/usage thresholds.

cship renders a live statusline for Claude Code sessions, showing session cost, context window usage, model name, API usage limits, and more — all configurable via a simple TOML file.

Key features:

• 🎨 Fully Customizable: Configure every module with Starship-compatible TOML. Colors, symbols, thresholds — your statusline, your rules.
• ⚡ Blazing Fast: Written in Rust with a ≤10ms render budget.
• 🔌 Starship Passthrough: Embed any Starship module (git_branch, directory, language runtimes) right next to native CShip modules.
• 💰 Session Insights: Track cost, context window usage, API limits, vim mode, agent name, and more — all from Claude Code's live JSON feed. Implement custom warn and critical thresholds with custom colors for each.

🚀 Install

⚡ Method 1a: curl installer (macOS / Linux)

curl -fsSL https://cship.dev/install.sh | bash

Auto-detects your OS and architecture (macOS arm64/x86_64, Linux x86_64/aarch64), downloads the binary to ~/.local/bin/cship, creates a starter config at ~/.config/cship.toml, and wires the statusLine entry in ~/.claude/settings.json.

Optional dependencies (Starship for passthrough modules, and libsecret-tools on Linux for usage limits) are handled as follows:

• Interactive terminal — the installer prompts you for each.
• --yes / -y — auto-installs all optional deps without prompting:

  curl -fsSL https://cship.dev/install.sh | bash -s -- --yes
  

• Non-interactive (Docker RUN, CI pipelines, no TTY) — optional deps are skipped automatically; the installer prints instructions for manual installation.

🪟 Method 1b: PowerShell installer (Windows)

Run this one-liner in PowerShell (5.1 or later):

irm https://cship.dev/install.ps1 | iex

Installs to %USERPROFILE%\.local\bin\cship.exe, writes config to %USERPROFILE%\.config\cship.toml, and registers the statusline in %USERPROFILE%\.claude\settings.json.

You can inspect the script before running: install.ps1

📦 Method 2: cargo install

Requires the Rust toolchain.

cargo install cship

After installing with cargo on macOS / Linux, wire the statusline manually in ~/.claude/settings.json:

{
  "statusLine": { "type": "command", "command": "cship" }
}

After installing with cargo on Windows, wire the statusline manually in %APPDATA%\\Claude\\settings.json:

{
  "statusLine": { "type": "command", "command": "cship" }
}

⚙️ Configuration

• The default config file is ~/.config/cship.toml (on Windows: %USERPROFILE%\.config\cship.toml).
• You can also place a cship.toml in your project root for per-project overrides.
• The lines array defines the rows of your statusline.
• Each element is a format string mixing $cship.<module> tokens (native cship modules) with Starship module tokens (e.g. $git_branch).
• See the Showcase below for ready-to-use configs you can drop straight into ~/.config/cship.toml.

🧩 Available modules

Everything in the Claude Code status line documentation is available as a $cship.<module> token for you to mix and match in the lines format strings. Here are the most popular ones:

| Token | Description | |-------|-------------| | $starship_prompt | Full rendered Starship prompt (all configured modules in one row) | | $cship.model | Claude model name | | $cship.cost | Session cost (configurable currency; default $X.XX) | | $cship.context_bar | Visual progress bar of context window usage | | $cship.context_window | Context window tokens (used/total) | | $cship.context_window.used_tokens | Real token count in context with percentage (e.g. 8%(79k/1000k)) | | $cship.cost.total_lines_added | Lines added this session | | $cship.cost.total_lines_removed | Lines removed this session | | $cship.usage_limits | API usage limits (5hr / 7-day, plus per-model and extra-usage when available) | | $cship.usage_limits.per_model | 7-day per-model breakdown (opus / sonnet / cowork / oauth) | | $cship.usage_limits.extra_usage | Extra-credits section with {active} indicator | | $cship.peak_usage | Peak-time indicator (US Pacific business hours) | | $cship.agent | Sub-agent name | | $cship.session | Session identity info | | $cship.workspace | Workspace/project directory |

Full configuration reference: https://cship.dev

🔍 Debugging

Run cship explain to inspect what cship sees from Claude Code's context JSON — useful when a module shows nothing or behaves unexpectedly.

cship explain

To check the installed binary version:

cship --version   # or: cship -v

✨ Showcase

Ready-to-use configurations — from the recommended full-featured setup down to a minimal single-line bar. Each can be dropped into ~/.config/cship.toml.

1. ⚓ Hero / Recommended

My personal setup, end to end. Top row: $starship_prompt running Starship's Catppuccin Powerline preset. Bottom row: model, cost, context bar, 7-day per-model usage, extra credits, peak-hours indicator — thresholds escalate cool → warn → critical as budgets fill.

~/.config/cship.toml

[cship]
lines = [
  "$starship_prompt",
  "$cship.model $cship.cost $cship.context_bar $cship.usage_limits $cship.peak_usage",
]

[cship.model]
symbol = " "
style  = "bold cyan"

[cship.context_bar]
symbol             = " "
filled_char        = "●"
empty_char         = "○"
format             = "[$symbol$value]($style)"
width              = 10
style              = "fg:#7dcfff"
warn_threshold     = 40.0
warn_style         = "fg:#e0af68"
critical_threshold = 70.0
critical_style     = "bold fg:#f7768e"

[cship.cost]
symbol             = "💰 "
style              = "fg:#a9b1d6"
warn_threshold     = 10
warn_style         = "fg:#e0af68"
critical_threshold = 50
critical_style     = "bold fg:#f7768e"

[cship.usage_limits]
five_hour_format   = " 5h {pct}% ({reset})"
seven_day_format   = " 7d {pct}% ({reset})"
separator          = " "
warn_threshold     = 50.0
warn_style         = "fg:#e0af68"
critical_threshold = 80.0
critical_style     = "bold fg:#f7768e"

~/.config/starship.toml — Starship's Catppuccin Powerline preset:

"$schema" = 'https://starship.rs/config-schema.json'

format = """
[](red)\
$os\
$username\
[](bg:peach fg:red)\
$directory\
[](bg:yellow fg:peach)\
$git_branch\
$git_status\
[](fg:yellow bg:green)\
$c\
$rust\
$golang\
$nodejs\
$php\
$java\
$kotlin\
$haskell\
$python\
[](fg:green bg:sapphire)\
$conda\
[](fg:sapphire bg:lavender)\
$time\
[ ](fg:lavender)\
$cmd_duration\
$line_break\
$character"""

palette = 'catppuccin_mocha'

[os]
disabled = false
style = "bg:red fg:crust"
format = "[$symbol ]($style)"

[os.symbols]
Macos = "󰀵"
# (full OS symbol list trimmed for brevity — see the preset link above)

[username]
show_always = false
style_user = "bg:red fg:crust"
style_root = "bg:red fg:crust"
format = '[ $user]($style)'

[directory]
style = "bg:peach fg:crust"
format = "[ $path ]($style)"
truncation_length = 3
truncation_symbol = "…/"

[directory.substitutions]
"Documents" = "󰈙 "
"Downloads" = " "
"Music" = "󰝚 "
"Pictures" = " "
"Developer" = "󰲋 "

[git_branch]
symbol = ""
style = "bg:yellow"
format = '[[ $symbol $branch ](fg:crust bg:yellow)]($style)'

[git_status]
style = "bg:yellow"
format = '[[($all_status$ahead_behind )](fg:crust bg:yellow)]($style)'

[nodejs]
symbol = ""
style = "bg:green"
format = '[[ $symbol( $version) ](fg:crust bg:green)]($style)'

[rust]
symbol = ""
style = "bg:green"
format = '[[ $symbol( $version) ](fg:crust bg:green)]($style)'

[golang]
symbol = ""
style = "bg:green"
format = '[[ $symbol( $version) ](fg:crust bg:green)]($style)'

[python]
symbol = ""
style = "bg:green"
format = '[[ $symbol( $version)(\(#$virtualenv\)) ](fg:crust bg:green)]($style)'

[conda]
symbol = "  "
style = "fg:crust bg:sapphire"
format = '[$symbol$environment ]($style)'
ignore_base = false

[time]
disabled = false
time_format = "%R"
style = "bg:lavender"
format = '[[  $time ](fg:crust bg:lavender)]($style)'

[line_break]
disabled = true

[character]
success_symbol = '[❯](bold fg:green)'
error_symbol = '[❯](bold fg:red)'
vimcmd_symbol = '[❮](bold fg:green)'

[cmd_duration]
show_milliseconds = true
format = "⏳ $duration "
style = "bg:lavender"
show_notifications = true
min_time_to_notify = 45000

# Catppuccin Mocha palette — fu