{"id":50661907,"url":"https://github.com/hankegui/cc-status","last_synced_at":"2026-06-08T03:04:06.040Z","repository":{"id":362598417,"uuid":"1259532072","full_name":"hankeGui/cc-status","owner":"hankeGui","description":"Multi-line, mode-switchable status line for Claude Code with prompt-cache TTL, hit rate, burn rate, skill/MCP usage","archived":false,"fork":false,"pushed_at":"2026-06-05T03:12:18.000Z","size":109,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T04:07:06.968Z","etag":null,"topics":["anthropic","claude-code","cli","rust","statusline"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hankeGui.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-04T15:47:34.000Z","updated_at":"2026-06-05T03:12:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hankeGui/cc-status","commit_stats":null,"previous_names":["hankegui/cc-status"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/hankeGui/cc-status","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hankeGui%2Fcc-status","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hankeGui%2Fcc-status/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hankeGui%2Fcc-status/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hankeGui%2Fcc-status/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hankeGui","download_url":"https://codeload.github.com/hankeGui/cc-status/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hankeGui%2Fcc-status/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34046005,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","claude-code","cli","rust","statusline"],"created_at":"2026-06-08T03:04:04.904Z","updated_at":"2026-06-08T03:04:06.035Z","avatar_url":"https://github.com/hankeGui.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cc-status\n\n\u003e Multi-line, mode-switchable status line for [Claude Code](https://docs.claude.com/en/docs/claude-code) — written in Rust. Token cost tracking, prompt-cache TTL, hit rate, burn rate, Skill/MCP usage, daemon mode, all in one binary.\n\n[![npm](https://img.shields.io/npm/v/@cc-status-line/cli?label=npm\u0026color=brightgreen)](https://www.npmjs.com/package/@cc-status-line/cli)\n[![GitHub release](https://img.shields.io/github/v/release/hankeGui/cc-status?display_name=tag\u0026sort=semver)](https://github.com/hankeGui/cc-status/releases)\n[![License](https://img.shields.io/github/license/hankeGui/cc-status)](LICENSE)\n\n🌐 **Site**: \u003chttps://hankegui.github.io/cc-status\u003e\n🐙 **Source**: \u003chttps://github.com/hankeGui/cc-status\u003e\n📦 **npm**: `npm install -g @cc-status-line/cli`\n\n```\n~/hanke-dev/cc-status main  Claude Opus 4.7  ctx 86% █████▏  154.6k/950k\n```\n\n```\n~/hanke-dev/cc-status main  Claude Opus 4.7\nctx 86% █████▏ 154.6k/950k  ↑154.6k ↓185 +687 🎯99%  cache 4:47  hit 96%  🔥 32.4k/min\nskills: jira×3 wiki×1   mcp: github×2\n```\n\n\u003e Run `bash scripts/screenshots.sh` (with `freeze` on PATH) to regenerate the PNG/SVG screenshots embedded above.\n\n## Why\n\nMost Claude Code status lines stop at \"model name + ctx percentage.\" That hides what actually drives cost and behavior:\n\n- How many tokens did the **last turn** burn, and how many were a cache hit (10× cheaper)?\n- Is the **prompt cache** about to expire (5-min TTL) — and how much will the next turn cost if it does?\n- What's my **session-wide hit rate** — and how fast am I burning tokens?\n- Which **Skills / MCP servers** has this session called?\n- On a 1M-context model, is my percentage actually computed against 1M, or am I about to be auto-compacted at 200k?\n- **What did this session actually cost in USD** — and how does today / this week compare?\n\ncc-status answers all of these in three lines and lets you switch modes with a single command.\n\n## Highlights\n\n- **7 built-in modes** (`compact` / `minimal` / `detailed` / `cost` / `tokens` / `tools` / `debug`) plus user-defined modes via `ccs mode add` / `append` / `edit`.\n- **17 segments** ranging from `{dir}` and `{git}` to `{cost_today}` / `{burn}` / `{cache_ttl}`. Mix and match.\n- **Per-model USD pricing** with built-in defaults for Opus / Sonnet / Haiku 4.x and a 1M-context tier multiplier. Override per model in `config.toml`.\n- **`ccs cost`** prints a multi-day ASCII dashboard with per-day bars, per-model breakdowns, and `--debug` per-file reconciliation when numbers don't match another tool.\n- **`ccs status`** is a self-explanatory dashboard for the current session — every number labeled, every unit annotated.\n- **`ccs setup`** writes the `statusLine` block to `~/.claude/settings.json` for you (with backup), so users don't have to hand-edit JSON.\n- **Optional Unix-socket daemon** for sub-millisecond renders on slow git repos. `ccs render` falls back to inline rendering if the daemon isn't running.\n- **Streaming-aware token accounting**: matches `ccusage` and `cc-switch`'s `(message.id, requestId)` dedupe so we don't double-count partial / final stream events.\n- **Local-time day buckets** matching what the Anthropic console shows.\n- **Fault-isolated rendering**: a panicking or stuck segment becomes empty space, never blanks the whole status line.\n\n## Install\n\ncc-status is a Rust binary, but you don't need a Rust toolchain — pick whichever channel suits your machine.\n\n\u003e **Heads-up: `npx` is for trying it once. Don't use `npx` to install — Claude Code's `statusLine` runs on every prompt refresh, so you want the binary on PATH.** Use `npm install -g`, `curl`, or Homebrew below.\n\n### npm (recommended for Claude Code users)\n\nYou already have Node.js if you use Claude Code.\n\n```sh\nnpm install -g @cc-status-line/cli\nccs --version\nccs setup           # writes the statusLine block into ~/.claude/settings.json (with backup)\n```\n\nIn China? Use a faster mirror once:\n\n```sh\nnpm install -g --registry=https://registry.npmmirror.com @cc-status-line/cli\nccs setup\n```\n\nTo **try it without installing** (binary won't stay on PATH afterwards):\n\n```sh\nnpx -y @cc-status-line/cli --version\n```\n\nThis is fine for kicking the tires, but for actual Claude Code use you want the global install above.\n\n### curl install script\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/hankeGui/cc-status/main/install.sh | sh\nccs setup\n```\n\nInstalls to `~/.local/bin/ccs`. Pass `--bin-dir` or `--version` to customize.\n\n### Homebrew (macOS / Linux)\n\n```sh\nbrew install hankeGui/tap/ccs\nccs setup\n```\n\n### Manual download\n\nPick a tarball from [releases](https://github.com/hankeGui/cc-status/releases), unpack, drop `ccs` somewhere on PATH. Then `ccs setup`.\n\n### From source (requires a Rust toolchain)\n\n```sh\ncargo install --git https://github.com/hankeGui/cc-status --locked\n```\n\n\u003e **Note**: `cargo install` puts the binary at `~/.cargo/bin/ccs`. If `~/.cargo/bin` is not on your PATH, add it (rustup's installer normally does this for you):\n\u003e\n\u003e ```sh\n\u003e export PATH=\"$HOME/.cargo/bin:$PATH\"\n\u003e ```\n\u003e\n\u003e `ccs setup` writes an absolute path either way, so Claude Code finds it even if your shell doesn't.\n\nOr clone and build:\n\n```sh\ngit clone https://github.com/hankeGui/cc-status\ncd cc-status\ncargo build --release\ncp target/release/ccs ~/.local/bin/\n```\n\n## After installing — wire it into Claude Code\n\n```sh\nccs setup\n```\n\nThis inspects `~/.claude/settings.json`, shows the proposed `statusLine` change, prompts y/N, and writes a backup before saving. Pass `--yes` to skip the prompt or `--check` to inspect without modifying. To remove the line later: `ccs setup --uninstall`.\n\nIf you'd rather edit by hand:\n\n```json\n{\n  \"statusLine\": {\n    \"type\": \"command\",\n    \"command\": \"/absolute/path/to/ccs render\"\n  }\n}\n```\n\nUse absolute paths — Claude Code's status-line shell does not always inherit your login `PATH`.\n\nRestart Claude Code and the bar appears at the top of every prompt.\n\n## Three ways to interact\n\ncc-status follows a \"passive bar + on-demand panel\" design. You don't need to read every metric every turn.\n\n### 1. The status line itself\n\nThe bar at the top of every Claude Code prompt. Choose a layout:\n\n```sh\nccs mode compact     # 1 line, the basics (default)\nccs mode minimal     # 1 line, just dir + ctx\nccs mode detailed    # 3 lines, all metrics\nccs mode cost        # 2 lines focused on $ spent\nccs mode tokens      # 3 lines focused on token flow\nccs mode tools       # 3 lines focused on Skill / MCP usage\nccs mode debug       # 8 lines, one metric per line with labels\n```\n\nOr build your own without rewriting:\n\n```sh\nccs segments                                      # see all segments\nccs mode append cost_today                        # append a new line to current mode\nccs mode append hit_rate burn                     # append several segments together\nccs mode append --line 1 git                      # append to an existing line\nccs mode append --mode detailed cost_today        # target a specific mode\nccs mode edit                                     # full edit in $EDITOR\nccs mode add mine -l \"{dir} {git}\" \\\n                  -l \"{last_turn} {hit_rate}\"     # define a brand-new mode\nccs mode list                                     # show all modes\nccs mode rm mine                                  # delete one\n```\n\n### 2. The detail panel (`ccs status`)\n\nPrint a self-explanatory dashboard for the *current session* — every number labeled, every unit annotated:\n\n```sh\nccs status\n```\n\nThe panel auto-locates the transcript by `cwd`, so it works from anywhere — even outside Claude Code's status-line invocation context.\n\n### 3. The legend (`ccs explain`)\n\nForgot what `+865` or `🎯99%` means?\n\n```sh\nccs explain\n```\n\nPrints a colored cheat-sheet of every segment, every color, every glyph.\n\n## Segments\n\n| Token | Output | Meaning |\n|---|---|---|\n| `{dir}` | `~/hanke-dev/cc-status` | Last 3 path components, `~` for HOME |\n| `{git}` | `wt:NAME branch ⇡2⇣1 [+!?]` | Worktree, branch, ahead/behind, dirty flags |\n| `{model}` | `Claude Opus 4.7` | CC's reported model |\n| `{ctx}` | `ctx 86% █████▏ 154.6k/950k` | Remaining %, bar, used / capacity |\n| `{ctx_tokens}` | `154.6k/950k` | Just the token numbers |\n| `{last_turn}` | `↑12.3k ↓2.1k +865 🎯89%` | Last turn input ↑ / output ↓ / cache write + / hit rate 🎯 |\n| `{cache_ttl}` | `cache 3:42` | Prompt-cache 5-min TTL countdown (red \u003c 1 min) |\n| `{hit_rate}` | `hit 96%` | Session-wide cache hit rate |\n| `{burn}` | `🔥 32.4k/min` | Session-average token rate |\n| `{skills}` | `skills: jira×3 wiki×1` | Skill calls, top 4 by count |\n| `{mcp}` | `mcp: github×2` | MCP-server calls, top 4 |\n| `{cost_last}` | `last $0.012` | USD cost of the last turn (current model price) |\n| `{cost_session}` | `sess $1.42` | Cumulative USD cost for the current session |\n| `{cost_today}` | `today $4.18` | USD cost across all sessions today |\n| `{cost_week}` | `7d $24.50` | USD cost over the last 7 days |\n| `{cost}` | `last $0.012 · today $4.18` | Combo: `cost_last + cost_today` |\n| `{mode}` | `[detailed]` | Current mode label |\n\n## Configuration\n\nLives at `$XDG_CONFIG_HOME/cc-status/config.toml` (macOS: `~/Library/Application Support/dev.hanke.cc-status/config.toml`).\n\n```sh\nccs init             # write defaults if missing\nccs init --force     # overwrite existing\nccs config-path      # print resolved path\n```\n\nExample:\n\n```toml\ncurrent_mode = \"detailed\"\n\n[modes.compact]\nlines = [\"{dir} {git} {model} {ctx}\"]\n\n[modes.detailed]\nlines = [\n  \"{dir} {git} {model}\",\n  \"{ctx} {last_turn} {cache_ttl} {hit_rate} {burn}\",\n  \"{skills} {mcp}\",\n]\n\n[theme]\nctx_low = 20    # red below this remaining %\nctx_med = 50    # yellow below this\n```\n\nAdd your own modes — any TOML key under `[modes.X]` becomes selectable via `ccs mode X`.\n\n## Capacity calculation (1M context support)\n\n`{ctx}` reports `used / capacity` where:\n\n```\nphysical_window = used_tokens / (1 - CC_remaining_percentage / 100)\ncapacity        = physical_window × CLAUDE_AUTOCOMPACT_PCT_OVERRIDE / 100\n```\n\nIn plain English: cc-status backsolves the *real* context window from CC's reported percentage, then applies your auto-compact threshold to show the *usable* capacity — i.e., the point at which Claude Code will trigger auto-compact.\n\nTwo relevant Claude Code env vars (set in `~/.claude/settings.json` `env` block):\n\n| Env var | Meaning | Default |\n|---|---|---|\n| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Treat the window as N tokens (e.g. `1000000` for 1M-context models) | model-detected |\n| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Compact at N % of window | `95` |\n\ncc-status reads `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` from the process env at render time, so the bar always matches Claude Code's actual compact behavior.\n\n## Pricing \u0026 cost segments\n\nThe `cost*` segments compute USD by multiplying per-model token counts\nagainst built-in Anthropic prices (Opus, Sonnet, Haiku, with the 1M\ncontext tier doubling input/output when the model name contains\n`[1m]` / `(1m)`). Override or extend the table in your config:\n\n```toml\n[pricing.opus]\ninput  = 12.00     # $/M tokens\noutput = 60.00\n\n# Or pin an exact model id (substring match, case-insensitive)\n[pricing.\"anthropic--claude-opus-latest\"]\ninput  = 13.00\noutput = 65.00\n```\n\n`{cost_today}` and `{cost_week}` walk every transcript under\n`~/.claude/projects/`, incrementally folded into a rollup at\n`$XDG_CACHE_HOME/cc-status/rollup.json`. First scan touches every\nfile; subsequent renders only read newly-appended bytes.\n\n\u003e **Caveat**: today/7d cost relies on the model id Claude Code writes\n\u003e into the transcript (`message.model`), which is the canonical id\n\u003e like `claude-opus-4-7` without the `[1m]` suffix. If you run on a\n\u003e 1M-context tier, today/7d under-counts unless you add a matching\n\u003e `[pricing.opus]` override that bakes the doubled price in.\n\n### Reconciling against another tool\n\nNumbers off vs ccusage / cc-switch / your Anthropic invoice? Run:\n\n```sh\nccs cost --days 1 --debug\n```\n\nIt prints every transcript file that contributed to the window, sorted\nby cost — with raw entry count → unique-after-dedupe count, % duplicated,\ndate-window misses, the four token buckets, and the model. Lets you\npinpoint exactly where the gap is in seconds.\n\n## Performance\n\n- **Render latency**: ~20 ms inline (mostly forking `git`); ~2 ms via the optional daemon. Well under Claude Code's 300 ms status-line timeout either way.\n- **Transcript parsing**: incremental — a per-session JSON cache stores the file offset and aggregated counters. First-run scan is the worst case; subsequent renders only read newly-appended bytes.\n- **Cross-session rollup**: `~/Library/Caches/dev.hanke.cc-status/rollup.json` holds per-day, per-model token totals + a per-message dedupe set. Loaded only when the active mode references `{cost_today}` / `{cost_week}` / `{cost}`.\n- **Fault isolation**: each segment is wrapped in `catch_unwind`; the git helper has a 150 ms hard timeout. A bad segment becomes `\"\"`; the rest of the line still renders.\n\n## Documentation\n\n- [中文使用说明](docs/USAGE.zh.md)\n- [Architecture](docs/ARCHITECTURE.md)\n- [Releasing](docs/RELEASING.md) — distribution setup (npm, brew, GitHub Releases)\n- [CLAUDE.md](CLAUDE.md) — project-level context for Claude Code agents\n\n## Roadmap\n\nDone in 0.3.x:\n\n- [x] Daemon mode (Unix socket) for sub-ms cold start\n- [x] Cost segments (`{cost_last}` / `{cost_session}` / `{cost_today}` / `{cost_week}` / `{cost}`)\n- [x] Per-model pricing with built-in Opus / Sonnet / Haiku rates and 1M-tier multiplier\n- [x] Cross-session cost dashboard (`ccs cost --days N`)\n- [x] `ccs cost --debug` per-file reconciliation\n- [x] Streaming `(message.id, requestId)` dedupe matching ccusage / cc-switch\n- [x] Local-time day buckets\n- [x] Auto-update (`ccs upgrade`) detecting npm / curl / brew / cargo install\n- [x] Shell completions (`ccs completions \u003cshell\u003e`)\n- [x] Fault-isolated segment rendering + git timeout\n- [x] `ccs setup` for one-shot `~/.claude/settings.json` wiring\n- [x] GitHub Pages site\n\nStill on the list:\n\n- [ ] Re-enable Windows builds (rollup file-rotation detection needs a robust signal there)\n- [ ] Per-session colors / titles for parallel CC instances\n- [ ] Pace-aware quota burn warning\n- [ ] Plugin segments (custom shell commands)\n- [ ] Homebrew tap published\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhankegui%2Fcc-status","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhankegui%2Fcc-status","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhankegui%2Fcc-status/lists"}