cship 1.2.0

Beautiful, Blazing-fast, Customizable Claude Code Statusline
Documentation

⚓ CShip (pronounced "sea ship")

CI Crates.io version Crates downloads GitHub release GitHub downloads License

Beautiful, Blazing-fast, Customizable Claude Code Statusline.

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 1: curl installer (recommended)

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, wires the statusLine entry in ~/.claude/settings.json, and optionally installs Starship (needed for passthrough modules) and, on Linux, libsecret-tools (needed for usage limits).

ðŸ“Ķ Method 2: cargo install

Requires the Rust toolchain.

cargo install cship

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

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

⚙ïļ Configuration

  • The default config file is ~/.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).

A minimal working example:

[cship]
lines = ["$cship.model $cship.cost $cship.context_bar"]

ðŸŽĻ Styling example

[cship]
lines = ["$cship.model $cship.cost $cship.context_bar"]

[cship.cost]
warn_threshold = 1.0
warn_style = "bold yellow"
critical_threshold = 5.0
critical_style = "bold red"

ðŸ§Đ 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
$cship.model Claude model name
$cship.cost Session cost in USD ($X.XX)
$cship.context_bar Visual progress bar of context window usage
$cship.context_window Context window tokens (used/total)
$cship.usage_limits API usage limits (5hr / 7-day)
$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

âœĻ Showcase

Six ready-to-use configurations — from minimal to full-featured. Each can be dropped into ~/.config/cship.toml.

1. ðŸŠķ Minimal

One clean row. Model, cost with colour thresholds, context bar.

[cship]
lines = ["$cship.model  $cship.cost  $cship.context_bar"]

[cship.cost]
style              = "green"
warn_threshold     = 2.0
warn_style         = "yellow"
critical_threshold = 5.0
critical_style     = "bold red"

[cship.context_bar]
width              = 10
warn_threshold     = 40.0
warn_style         = "yellow"
critical_threshold = 70.0
critical_style     = "bold red"

2. ðŸŒŋ Git-Aware Developer

Two rows: Starship git status on top, Claude session below. Starship passthrough ($directory, $git_branch, $git_status) requires Starship to be installed.

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

[cship.model]
symbol = "ðŸĪ– "
style  = "bold cyan"

[cship.cost]
warn_threshold     = 2.0
warn_style         = "yellow"
critical_threshold = 5.0
critical_style     = "bold red"

[cship.context_bar]
width              = 10
warn_threshold     = 40.0
warn_style         = "yellow"
critical_threshold = 70.0
critical_style     = "bold red"

3. 💰 Cost Guardian

Shows cost, lines changed, and rolling API usage limits all at once. Colour escalates as budgets fill.

[cship]
lines = [
  "$cship.model $cship.cost +$cship.cost.total_lines_added -$cship.cost.total_lines_removed",
  "$cship.context_bar $cship.usage_limits",
]

[cship.model]
style = "bold purple"

[cship.cost]
warn_threshold     = 1.0
warn_style         = "bold yellow"
critical_threshold = 3.0
critical_style     = "bold red"

[cship.context_bar]
width              = 10
warn_threshold     = 40.0
warn_style         = "yellow"
critical_threshold = 70.0
critical_style     = "bold red"

[cship.usage_limits]
ttl                = 60        # cache TTL in seconds; increase if running many concurrent sessions
five_hour_format   = "5h {pct}%"
seven_day_format   = "7d {pct}%"
separator          = " "
warn_threshold     = 70.0
warn_style         = "bold yellow"
critical_threshold = 90.0
critical_style     = "bold red"

4. ðŸŽĻ Material Hex

Every style value is a fg:#rrggbb hex colour — no named colours anywhere. Amber warns, coral criticals.

`

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

[cship.model]
style = "fg:#c3e88d"

[cship.cost]
style              = "fg:#82aaff"
warn_threshold     = 2.0
warn_style         = "fg:#ffcb6b"
critical_threshold = 6.0
critical_style     = "bold fg:#f07178"

[cship.context_bar]
width              = 10
style              = "fg:#89ddff"
warn_threshold     = 40.0
warn_style         = "fg:#ffcb6b"
critical_threshold = 70.0
critical_style     = "bold fg:#f07178"

[cship.usage_limits]
five_hour_format   = "5h {pct}%"
seven_day_format   = "7d {pct}%"
separator          = " "
warn_threshold     = 70.0
warn_style         = "fg:#ffcb6b"
critical_threshold = 90.0
critical_style     = "bold fg:#f07178"

5. 🌃 Tokyo Night

Three-row layout for polyglot developers. Starship handles language runtimes and git; cship handles session data. Styled with the Tokyo Night colour palette.

[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]
symbol             = "💰 "
style              = "fg:#a9b1d6"
warn_threshold     = 2.0
warn_style         = "fg:#e0af68"
critical_threshold = 5.0
critical_style     = "bold fg:#f7768e"

[cship.usage_limits]
five_hour_format   = "⌛ 5h {pct}%"
seven_day_format   = "📅 7d {pct}%"
separator          = " "
warn_threshold     = 70.0
warn_style         = "fg:#e0af68"
critical_threshold = 90.0
critical_style     = "bold fg:#f7768e"

6. ðŸ”Ī Nerd Fonts

Requires a Nerd Font in your terminal. Icons are embedded as symbol values on each module and as literal characters in the format string for Starship passthrough rows. You can use format to control how the symbol and value are combined for each module exactly like you'd do with Starship.

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

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

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

[cship.context_bar]
symbol             = " "
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.usage_limits]
five_hour_format   = "⌛ 5h {pct}%"
seven_day_format   = "📅 7d {pct}%"
separator          = " "
warn_threshold     = 70.0
warn_style         = "fg:#e0af68"
critical_threshold = 90.0
critical_style     = "bold fg:#f7768e"

📚 Full documentation

→ cship.dev

Complete configuration reference, format string syntax, all module options, and examples.

If you found this project useful, please give us a star ⭐ on GitHub!

If you find bugs or have suggestions, open an issue or submit a pull request. Contributions are very welcome!

ðŸ’Ą Inspiration

📄 License

Apache-2.0