⚓ CShip (pronounced "sea ship")

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.

🚀 Install

⚡ Method 1: curl installer (recommended)

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).

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

📦 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.

View config

[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.

View config

[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.

View config

[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]
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.

`

View config

[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.

View config

[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.

View config

[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

• Inspired by starship, built with Rust and the Claude Code status line API.

📄 License

Apache-2.0