Cship
⚡Beautiful, Blazing-fast, Customizable status line for Claude Code. Now with full Starship pass through!
Install / Use
/learn @stephenleo/CshipQuality Score
Category
Development & EngineeringSupported Platforms
README
⚓ CShip (pronounced "sea ship")
Beautiful, Blazing-fast, Customizable Claude Code Statusline.
<img src="./docs/examples/cship.png" alt="cship features" centered>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, 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 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.tomlin your project root for per-project overrides. - The
linesarray 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 |
|-------|-------------|
| $starship_prompt | Full rendered Starship prompt (all configured modules in one row) |
| $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.context_window.used_tokens | Real token count in context with percentage (e.g. 8%(79k/1000k)) |
| $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.
<img src="./docs/examples/03.gif" alt="Minimal cship statusline example" width="600"> <details> <summary>View config</summary>[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.
<img src="./docs/examples/05.png" alt="Cost guardian cship statusline example" width="600"> <details> <summary>View config</summary>[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.
`<img src="./docs/examples/06.png" alt="Material Hex cship statusline example" width="600">
<details> <summary>View config</summary>[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.
<img src="./docs/examples/07.png" alt="Tokyo Night cship statusline example" width="600"> <details> <summary>View config</summary>[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 =
