FAQ

Does cship conflict with Starship?

No. cship and Starship serve different purposes:

• Starship renders your shell prompt (the line before your commands in the terminal).
• CShip renders Claude Code's statusline (the line shown at the bottom of the Claude Code UI, inside the AI session).

They operate in completely separate contexts and never interfere with each other. In fact, they work better together — CShip can invoke any Starship module as a passthrough, so your Starship-configured git status, directory, and language runtime indicators can appear right in your Claude Code statusline.

---

Why not just use Starship for the Claude Code statusline?

Starship is a shell prompt renderer — it reads shell context (environment variables, git state, file system). It has no knowledge of Claude Code internals like session cost, context window usage, model name, or API limits.

Claude Code exposes this session data via a JSON feed piped to the statusline command on every render cycle. CShip is purpose-built to consume that JSON feed and render it with the same TOML-based customization model you already know from Starship.

In short: Starship knows about your shell, CShip knows about your Claude Code session. Together they cover everything.

---

How do I debug my config?

Run cship explain:

cship explain

This shows:

• Which config file was loaded (and from where)
• Each module's current rendered value
• Any warnings about missing data, misconfiguration, or disabled modules

cship explain reads from ~/.config/cship/sample-context.json if no stdin is piped, so it works outside of a Claude Code session. On first run, CShip auto-creates this file with representative values.

---

How do I set up usage limits on Linux/WSL2?

The CShip usage_limits module fetches data from the Anthropic API using your Claude Code OAuth token, which is stored in the OS credential store.

Prerequisites:

1. Install libsecret-tools:

   # Debian/Ubuntu/WSL2
   sudo apt-get install -y libsecret-tools

2. Store your Claude Code OAuth token with secret-tool:

   secret-tool store --label="Claude Code" service "claude.ai" account "claude-code"

   When prompted for a password, paste your OAuth token.

   You can find your token in ~/.claude/.credentials.json (look for the access_token field) or by logging out and back into Claude Code.

3. Run cship explain to verify the token is found and the usage limits module is rendering.

macOS: CShip reads the OAuth token from the macOS Keychain automatically — no manual setup required.

---

What do {pace} and {active} mean in the usage_limits format strings?

{pace} is the signed headroom versus linear consumption of the current window. If you were perfectly on pace to land at 100% exactly when the window resets, {pace} would be 0%. A positive value (e.g. +20%) means you have 20 percentage points of headroom over the linear pace — you can comfortably keep going. A negative value (e.g. -15%) means you're 15 points ahead of pace and will hit the limit before reset unless you slow down. It renders as ? when the reset time is unknown.

{pace} is available in five_hour_format, seven_day_format, and each per-model format (opus_format, sonnet_format, cowork_format, oauth_apps_format).

{active} is only available in extra_usage_format. It renders ⚡ when either the 5h or 7d window is at 100% — meaning fresh requests are now drawing down extra credits rather than plan credits — and 💤 otherwise. Pair it with {used} / {limit} (dollars) and {pct} (utilization of the monthly extra-credit cap) for a one-glance view of supplemental spend.

[cship.usage_limits]
five_hour_format   = "5h {pct}% ({pace})"
seven_day_format   = "7d {pct}% ({pace})"
extra_usage_format = "{active} ${used}/${limit}"

---

I'm on a Claude Enterprise plan and cship.usage_limits shows nothing — why?

Claude Enterprise reports usage through extra_usage (monthly credit pool) rather than the standard 5-hour and 7-day windows used for Pro and Max. cship now renders the extra_usage line directly when standard fields are absent, with threshold styling applied to monthly credit utilization.

If you still see no output, run cship explain — it will surface the specific reason (missing credential, expired token, or extra-credit billing not enabled on your Enterprise account).

---

How does the peak-time indicator handle time zones and DST?

The peak_usage module checks whether the current time falls within the configured peak window in US Pacific time. It computes the UTC→Pacific offset internally — PDT (UTC−7) from the second Sunday of March through the first Sunday of November, PST (UTC−8) the rest of the year.

There are no dependencies on system locale or TZ environment variable; the DST boundaries are calculated from the UTC date using Tomohiko Sakamoto's day-of-week algorithm.

Defaults: Mon–Fri, 07:00–17:00 Pacific. To customise:

[cship.peak_usage]
start_hour = 9   # 9 AM Pacific
end_hour   = 18  # 6 PM Pacific (exclusive)

Set end_hour = 24 to mean "through end of day". Weekends always return nothing.

---

Why is my cost or context not updating?

Cost and context window data comes from Claude Code's JSON feed, which is updated on every statusline render (every time Claude Code calls cship). If these values appear stuck, check:

• The statusline command is correctly set in ~/.claude/settings.json:

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

• Run cship explain to confirm cship is receiving a valid JSON context.

Usage limits data is cached:

• Cache TTL: configurable (default 60 seconds), or until the rate-limit reset window passes (whichever comes first). Set [cship.usage_limits] ttl to increase the cache interval if you run many concurrent sessions.
• The first call in a session always fetches fresh data; subsequent calls within the configured TTL return the cached value.
• If the cache seems stale, check that your OAuth token is valid (re-login to Claude Code if needed).

You can see the current cache state by running cship explain — it shows the usage limits value being rendered and any warnings if the API call failed.