Configuration Reference

CShip is configured via a TOML file. The config discovery order is:

1. --config <path> flag (if provided)
2. cship.toml found walking up from the workspace directory
3. starship.toml found walking up from the workspace directory
4. ~/.config/cship.toml (global)
5. ~/.config/starship.toml (global)
6. Built-in defaults (no config required)

The recommended file is ~/.config/cship.toml.

Editor Schema

Add a $schema key to get autocomplete and validation for the [cship] section in editors that support JSON Schema for TOML (e.g. VS Code's Even Better TOML):

"$schema" = 'https://cship.dev/config-schema.json'

Run cship config-schema to print the same schema locally.

Layout

The [cship] section controls the overall layout:

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

Field	Type	Default	Description
lines	string[]	[]	Each element is one statusline row. Supports $cship.<module> tokens and Starship passthrough tokens.
format	string	—	Starship-compatible format string. Split on $line_break to produce multiple rows. Takes priority over lines when both are set.
width	integer	—	Fallback terminal width (columns) for $fill when auto-detection fails (see $fill).
width_offset	integer	3	Columns Claude Code reserves around the statusline, subtracted from the terminal width for $fill.

Format String Syntax

All format fields (and the lines strings) use Starship-compatible format syntax:

Syntax	Meaning
$value	Interpolate the variable named value
$symbol	Interpolate the module's configured symbol
[text]($style)	Render text with the ANSI style $style
($group)	Conditional group — renders only if all variables inside it are non-empty
$line_break	Insert a newline (for use in format, not lines)

Style values

Styles follow the same syntax as Starship:

"bold"
"italic"
"underline"
"bold green"
"fg:#c792ea"
"bold fg:#ff5370 bg:#1a1a2e"
"fg:208"              # 256-color index

Supported named colors: black, red, green, yellow, blue, purple, cyan, white, and their bright_* variants. Hex colors: #RRGGBB (24-bit) or #RGB (shorthand). 256-color: numeric index 0–255.

Common Module Fields

All native CShip modules share these optional fields:

Field	Type	Default	Description
disabled	bool	false	Set true to hide this module entirely (silent None)
style	string	module default	ANSI style for the rendered output
symbol	string	module default	Prefix symbol prepended to the value
format	string	"[$symbol$value]($style)"	Controls how symbol, value, and style are combined

---

[cship.model] — Model Name

Displays the active Claude model name.

Token: $cship.model

Field	Type	Default	Description
disabled	bool	false	Hide this module
style	string	"bold"	ANSI style (fallback when no per-family style matches)
symbol	string	""	Prefix symbol
format	string	"[$symbol$value]($style)"	Format string; $value = model display name
haiku_style	string	—	Style applied when the key contains "haiku" (case-insensitive)
sonnet_style	string	—	Style applied when the key contains "sonnet" (case-insensitive)
opus_style	string	—	Style applied when the key contains "opus" (case-insensitive)
family_style	table	—	Map of substring → style, for families beyond haiku/sonnet/opus (e.g. fable)

Variables: $value (display name, e.g. Claude Sonnet 4.5), $symbol, $style

Per-family styles are matched case-insensitively against model.id (e.g. claude-opus-4-7). If id is absent, display_name is used as the key instead — so a display name like "My Sonnet Setup" will trigger sonnet_style. family_style works the same way but lets you add arbitrary family names without waiting on a cship release — new model families can be styled the moment they ship. haiku_style/sonnet_style/opus_style take priority over a matching family_style entry. When several family_style keys match the same model, the longest key wins. An empty key is ignored (it would otherwise match every model) with a one-time warning. When no family style matches or is set, style is used as the fallback.

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

# Per-model colors
haiku_style  = "green"
sonnet_style = "cyan"
opus_style   = "magenta"

# Any other family
family_style.fable = "yellow"

For multiple entries, family_style can also be written as its own table instead of repeated dotted keys:

[cship.model.family_style]
fable = "yellow"
mythos = "red"

---

[cship.cost] — Session Cost

Displays total session cost with threshold-based colour escalation. The display currency and conversion rate are configurable; the underlying value is always total_cost_usd (USD). Thresholds are evaluated against the converted display value (total_cost_usd × conversion_rate); configure them in your display currency.

Token: $cship.cost

Field	Type	Default	Description
disabled	bool	false	Hide this module
style	string	"green"	Base ANSI style
symbol	string	""	Prefix symbol
format	string	"[$symbol$value]($style)"	Format string
warn_threshold	float	—	Display-currency amount at which style switches to warn_style
warn_style	string	"yellow"	Style applied when cost ≥ warn_threshold
critical_threshold	float	—	Display-currency amount at which style switches to critical_style
critical_style	string	"bold red"	Style applied when cost ≥ critical_threshold
currency_symbol	string	"$"	Symbol prepended to the displayed value (e.g. "£", "€")
conversion_rate	float	1.0	Multiplier applied to total_cost_usd before display; thresholds are evaluated against the converted value, so express them in your display currency

Variables: $value (e.g. $1.23 or £0.97 with a custom currency), $symbol, $style

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

Cost sub-field modules

Individual cost metrics can also be referenced directly:

Token	Description
$cship.cost.total_cost_usd	Total cost in USD
$cship.cost.total_duration (alias: total_duration_ms)	Total wall-clock duration, human-readable (45s, 1m30s, 2h15m30s, or 750ms for sub-second)
$cship.cost.total_api_duration (alias: total_api_duration_ms)	Total API time, human-readable
$cship.cost.total_lines_added	Lines added this session
$cship.cost.total_lines_removed	Lines removed this session

Each sub-field has its own [cship.cost.<name>] section with the same fields as the parent (style, symbol, format, warn_threshold, warn_style, critical_threshold, critical_style, disabled).

total_duration / total_api_duration and the _ms-suffixed names are accepted interchangeably as TOML keys and as $cship.cost.… variables — pick the spelling that reads better. Threshold values are still compared in raw milliseconds (e.g. warn_threshold = 30000.0 fires at 30s).

[cship.cost.total_lines_added]
style = "green"
warn_threshold = 500
warn_style = "yellow"

[cship.cost.total_duration]
warn_threshold = 30000.0   # 30s, compared in raw ms
warn_style = "yellow"

---

[cship.context_bar] — Context Window Progress Bar

Renders a visual ASCII progress bar showing context window usage.

Token: $cship.context_bar

Field	Type	Default	Description
disabled	bool	false	Hide this module
style	string	"green"	Base ANSI style
symbol	string	""	Prefix symbol
format	string	"[$symbol$value]($style)"	Format string
width	integer	10	Number of characters in the bar
filled_char	string	"█"	Character used for the filled portion. Any Unicode character is allowed.
empty_char	string	"░"	Character used for the empty portion. Any Unicode character is allowed.
warn_threshold	float	—	% at which style switches to warn_style
warn_style	string	"yellow"	Style at warn level
critical_threshold	float	—	% at which style switches to critical_style
critical_style	string	"bold red"	Style at critical level
empty_style	string	—	Style for the bar when no context data is available (e.g., "dim")

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

For a circle-style bar (●●●●○○○○○○40%):

[cship.context_bar]
filled_char = "●"
empty_char  = "○"

---

[cship.context_window] — Context Window Details

Displays detailed context window token counts. The parent token shows used/total summary.

Token: $cship.context_window

Field	Type	Default	Description
disabled	bool	false	Hide this module
style	string	—	ANSI style
warn_threshold	float	—	% threshold for warning
warn_style	string	—	Style at warn level
critical_threshold	float	—	% threshold for critical
critical_style	string	—	Style at critical level
format	string	—	Format string

Context window sub-field modules

Token	Description
$cship.context_window.used_percentage	% of context window used
$cship.context_window.remaining_percentage	% of context window remaining
$cship.context_window.size	Total context window size (tokens)
$cship.context_window.total_input_tokens	Total input tokens this session
$cship.context_window.total_output_tokens	Total output tokens this session
$cship.context_window.current_usage_input_tokens	Current turn input tokens
$cship.context_window.current_usage_output_tokens	Current turn output tokens
$cship.context_window.current_usage_cache_creation_input_tokens	Cache creation tokens
$cship.context_window.current_usage_cache_read_input_tokens	Cache read tokens
$cship.context_window.used_tokens	Token counts computed from current_usage (input_tokens + cache_creation + cache_read) and context_window_size. Percentage from the API's used_percentage field — may not equal used/total × 100 as the API includes overhead (e.g. system prompt, tool schemas). Renders as e.g. 8%(79k/1000k). Returns nothing before first API call.

Each sub-field supports style, symbol, format, warn_threshold, warn_style, critical_threshold, critical_style, disabled, and invert_threshold.

invert_threshold — set to true for metrics where low is bad (e.g. remaining_percentage): the warning fires when value falls below the threshold.

[cship.context_window.remaining_percentage]
warn_threshold    = 30.0
warn_style        = "yellow"
critical_threshold = 10.0
critical_style    = "bold red"
invert_threshold  = true

---

[cship.vim] — Vim Mode

Displays the current vim mode (NORMAL, INSERT, VISUAL, etc.). Returns nothing when vim mode is inactive.

Token: $cship.vim

Field	Type	Default	Description
disabled	bool	false	Hide this module
style	string	—	Base ANSI style
symbol	string	—	Prefix symbol
format	string	—	Format string
normal_style	string	"bold green"	Style applied in NORMAL mode
insert_style	string	"bold blue"	Style applied in INSERT mode

[cship.vim]
normal_style = "bold green"
insert_style = "bold blue"

---

[cship.agent] — Agent Name

Displays the active sub-agent name. Returns nothing when no agent is running.

Token: $cship.agent

Field	Type	Default	Description
disabled	bool	false	Hide this module
style	string	—	ANSI style
symbol	string	"↳ "	Prefix symbol
format	string	—	Format string

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

---

[cship.effort] — Reasoning Effort

Displays the current reasoning effort level (low, medium, high, xhigh, or max), reflecting mid-session /effort changes. Returns nothing when the active model does not support the effort parameter.

Token: $cship.effort (alias for $cship.effort.level)

Field	Type	Default	Description
disabled	bool	false	Hide this module
style	string	—	Base ANSI style (fallback when no per-level style matches)
symbol	string	—	Prefix symbol
format	string	—	Format string; $value = effort level
low_style	string	—	Style applied when the level is low
medium_style	string	—	Style applied when the level is medium
high_style	string	—	Style applied when the level is high
xhigh_style	string	—	Style applied when the level is xhigh
max_style	string	—	Style applied when the level is max

Variables: $value (effort level, e.g. high), $symbol, $style

Per-level styles are matched case-insensitively against the effort level. When no per-level style matches or is set, style is used as the fallback.

[cship.effort]
symbol      = "⚡ "
style       = "dim"
high_style  = "yellow"
xhigh_style = "bold yellow"
max_style   = "bold red"

---

[cship.session] — Session Identity

Displays session metadata (session ID, transcript path, output style, cship version).

Token: $cship.session

Field	Type	Default	Description
disabled	bool	false	Hide this module
style	string	—	ANSI style
symbol	string	—	Prefix symbol
format	string	—	Format string

---

[cship.workspace] — Workspace Directory

Displays the current working directory or project directory.

Token: $cship.workspace

Field	Type	Default	Description
disabled	bool	false	Hide this module
style	string	—	ANSI style
symbol	string	—	Prefix symbol
format	string	—	Format string

---

[cship.usage_limits] — API Usage Limits

Displays 5-hour and 7-day API utilization percentages with time-to-reset.

Data sources (in priority order):

1. stdin rate_limits — Claude Code (v2.1+) sends rate_limits directly in the session JSON for Pro/Max subscribers. When present, cship uses this data immediately with zero latency and no credential setup required.
2. OAuth API fetch — Falls back to fetching from https://api.anthropic.com/api/oauth/usage using your OAuth token (stored in the OS credential store). Results are cached for the configured TTL (default 60s).

Tokens:

Token	Renders
$cship.usage_limits	5h + 7d window summary. Per-model and extra-usage sections are appended only when show_per_model = true (opt-in for backwards compatibility)
$cship.usage_limits.per_model	Only the per-model 7-day breakdown (opus/sonnet/cowork/oauth)
$cship.usage_limits.opus	7-day Opus utilization only
$cship.usage_limits.sonnet	7-day Sonnet utilization only
$cship.usage_limits.cowork	7-day Cowork utilization only
$cship.usage_limits.oauth_apps	7-day OAuth-apps utilization only
$cship.usage_limits.extra_usage	Extra-credits display (only when the account has extra usage enabled)

The sub-tokens let you place sections independently in your lines layout — e.g., keep the 5h/7d pair on one row and push per-model onto a second row.

Field	Type	Default	Description
disabled	bool	false	Hide this module
style	string	—	Base ANSI style
format	string	—	Reserved; use the per-section formats below
five_hour_format	string	"5h: {pct}% resets in {reset}"	Format for the 5h window
seven_day_format	string	"7d: {pct}% resets in {reset}"	Format for the 7d window
opus_format	string	"opus {pct}%"	Format for the 7-day Opus section
sonnet_format	string	"sonnet {pct}%"	Format for the 7-day Sonnet section
cowork_format	string	"cowork {pct}%"	Format for the 7-day Cowork section
oauth_apps_format	string	"oauth {pct}%"	Format for the 7-day OAuth-apps section
extra_usage_format	string	"{active} extra: {pct}% (${used}/${limit})"	Format for the extra-usage section
show_per_model	bool	false	When true, $cship.usage_limits appends the per-model breakdown (opus, sonnet, cowork, oauth) to the default 5h | 7d output. The extra-usage section always renders when enabled, regardless of this flag. Default is false so existing status bars retain their pre-1.5 shape.
separator	string	" | "	String placed between sections
warn_threshold	float	—	% at which style switches to warn_style
warn_style	string	"yellow"	Style at warn level
critical_threshold	float	—	% at which style switches to critical_style
critical_style	string	"bold red"	Style at critical level
ttl	integer	60	Cache refresh interval in seconds. Increase to reduce API pressure when running multiple concurrent sessions.

Placeholders (available in all *_format strings):

Placeholder	Meaning
{pct}	Percentage used as integer (e.g. 23)
{remaining}	Percentage remaining as integer (e.g. 77)
{reset}	Time-until-reset string (e.g. 4h12m)
{reset_at}	Absolute local reset time — clock-only if today (e.g. 7:42 PM), weekday-prefixed otherwise (e.g. Mon 9:00 AM); ? if unknown, now if already past
{pace}	Signed headroom vs linear consumption — +20% (under pace), -15% (over pace), or ? when unknown

Placeholders specific to extra_usage_format (the standard {remaining} percentage placeholder does not apply here — use {remaining_credits} instead):

Placeholder	Meaning
{used}	Extra credits consumed, in dollars (e.g. 12.34)
{limit}	Monthly extra-credit limit, in dollars (e.g. 50)
{remaining_credits}	Remaining extra-credit budget, in dollars (e.g. 138.05)
{active}	⚡ when 5h or 7d utilization is at 100% (actively consuming extra credits), 💤 otherwise

Prerequisites: If Claude Code sends rate_limits in its session JSON (v2.1+, Pro/Max plans), no setup is needed for the 5h/7d totals. Per-model breakdowns and extra-usage data always come from the OAuth API — on Linux/WSL2 install libsecret-tools and store your OAuth token with secret-tool. See FAQ for setup instructions.

[cship.usage_limits]
ttl                = 300       # 5 minutes; increase if you run many concurrent sessions
five_hour_format   = "5h {pct}% resets at {reset_at} ({reset})"
seven_day_format   = "7d {pct}% resets at {reset_at} ({reset})"
opus_format        = "opus {pct}%"
sonnet_format      = "sonnet {pct}%"
extra_usage_format = "{active} extra {pct}% (${used}/${limit})"
separator          = " | "
warn_threshold     = 70.0
warn_style         = "bold yellow"
critical_threshold = 90.0
critical_style     = "bold red"

Composing with sub-tokens

Place per-model and extra usage on a separate line from the 5h/7d summary:

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

Each sub-token returns nothing when its data is absent, so the row collapses cleanly on accounts without a given breakdown.

Hiding a usage period

To hide one of the two main windows, set its format and the separator to empty strings. For example, to show only the 5-hour window:

[cship.usage_limits]
seven_day_format = ""
separator        = ""

To show only the 7-day window:

[cship.usage_limits]
five_hour_format = ""
separator        = ""

Setting both formats to "" effectively hides the combined token. Per-model sections render only when the API returns data for that model, so they disappear automatically on accounts that don't expose a given breakdown.

Claude Enterprise plans

On Enterprise, the OAuth usage API only populates extra_usage (the standard 5h/7d fields are null). cship.usage_limits automatically renders just the extra_usage line, and threshold styling falls back to extra_usage_utilization.

If cship.usage_limits is empty on Enterprise, run cship explain for specific diagnostics.

---

[cship.account] — Authenticated Account

Displays which Anthropic account the active Claude Code session is signed in to — handy for telling work and personal accounts apart at a glance. Profile data is fetched once from the OAuth /api/oauth/profile endpoint and cached for 24 hours (the profile rarely changes). The OAuth token is held only for the duration of the fetch — never written to disk, cache, stdout, or stderr.

Token: $cship.account

Field	Type	Default	Description
disabled	bool	false	Hide this module
style	string	—	ANSI style applied to the rendered value
symbol	string	""	Prefix symbol prepended to the value
format	string	"{label}"	Format string built from the placeholders below
ttl	integer	86400	Cache TTL in seconds (default 24h). The cache is also invalidated automatically when you switch accounts (token fingerprint change).
labels	table	—	Opt-in map from raw organization name → friendly label, e.g. { "Fulcrum Genomics" = "work", "Personal Workspace" = "personal" }

Placeholders (available in format):

Placeholder	Meaning
{label}	Resolved label: a labels mapping for the organization if present, else the raw organization name, else the account display name
{organization}	Raw organization name (e.g. Fulcrum Genomics)
{display_name}	Account display name (e.g. Nils)
{email}	Account email — treat as PII; opt in by referencing it in format
{tier}	Organization rate-limit tier (e.g. default_claude_max_5x)
{type}	Organization type (e.g. claude_team, personal)

Prerequisites: Requires an OAuth token in the OS credential store (the same credential used by usage_limits). On Linux/WSL2, install libsecret-tools and store your token with secret-tool. If the module renders nothing, run cship explain cship.account for a diagnosis (missing credential, expired token, or unreachable API).

[cship.account]
symbol = " "
style  = "bold fg:#7aa2f7"
format = "{label}"

# Map raw org names to short labels
[cship.account.labels]
"Fulcrum Genomics" = "work"
"Personal Workspace" = "personal"

To show more detail, reference additional placeholders:

[cship.account]
format = "{display_name} @ {organization}"

---

[cship.peak_usage] — Peak-Time Indicator

Shows when Anthropic's peak-time rate limiting is likely active, based on current time relative to US Pacific business hours. Returns nothing outside peak hours so the indicator disappears entirely.

The check is purely time-based (Mon–Fri, default 07:00–17:00 Pacific) — no network calls.

Token: $cship.peak_usage

Field	Type	Default	Description
disabled	bool	false	Hide this module
style	string	—	ANSI style
symbol	string	"⏰ "	Prefix symbol
format	string	"[$symbol$value]($style)"	Format string; $value = Peak
start_hour	integer	7	Start of peak window in US Pacific time (0–23)
end_hour	integer	17	End of peak window in US Pacific time, exclusive (0–24). Use 24 to mean through end of day

Variables: $value (Peak), $symbol, $style

US Pacific DST is handled automatically — PDT (UTC−7) from the second Sunday of March to the first Sunday of November, PST (UTC−8) otherwise.

[cship.peak_usage]
symbol     = "⏰ "
style      = "fg:#e0af68"
start_hour = 7
end_hour   = 17

---

[cship.starship_prompt] — Full Starship Prompt

Renders your entire Starship-configured prompt in a single call. Unlike per-module passthrough (e.g., $directory, $git_branch), this token invokes starship prompt to produce the complete rendered prompt with all configured modules.

Token: $starship_prompt

Field	Type	Default	Description
disabled	bool	false	Set to true to hide this token silently

[cship.starship_prompt]
disabled = false

---

$fill — Fill / Right-Alignment

$fill expands to fill the remaining horizontal space on a line, pushing whatever follows it to the right. Multiple $fill tokens on one line split the leftover space evenly, so content after the last $fill is right-aligned to the edge. This mirrors Starship's fill module.

Token: $fill — configured via [cship.fill].

Field	Type	Default	Description
symbol	string	"."	Character used to fill the gap. Use " " for an invisible gap.
style	string	"bold black"	ANSI style applied to the fill characters.
disabled	bool	false	When true, the $fill token renders as nothing (literal spaces around it in your format still remain).

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

[cship.fill]
symbol = "·"
style  = "fg:#414868"

A line whose only visible content is $fill (e.g. every module on it rendered empty) is dropped rather than emitting a bare full-width rule, consistent with how cship omits empty lines.

⚠️ Terminal-width limitation (read before using)

$fill needs to know the terminal width, and Claude Code does not provide it to the statusline command — there's no $COLUMNS, no controlling tty, and no width field in its JSON (claude-code#22115). cship works around this on macOS and Linux by walking up the process tree to Claude Code's controlling terminal and reading its size. This is best-effort:

• Windows, the web/desktop apps, and other no-tty environments can't be detected — cship falls back to [cship] width (if set) and then to 80 columns.
• The width resolution order is: detected terminal width → $COLUMNS → [cship] width → 80, then minus [cship] width_offset (default 3, ≈2 left + 1 right) to account for the margin Claude Code reserves.
• If right-alignment looks a few columns off, tune width_offset; if detection isn't available in your environment, pin [cship] width to your terminal's column count.
• Nerd Font glyphs may be measured one column narrower than they render (a Unicode-width limitation shared by Starship), which can nudge alignment by a column per glyph.