ccstatusline-zh: a Chinese localisation of the Claude Code status line

A fork whose only job is translation

ccstatusline-zh is a Chinese localisation fork of ccstatusline, the status line formatter for the Claude Code CLI. The upstream project renders model information, the Git branch, token usage and other live metrics in the terminal, and it supports more than eighty customisable widgets, Powerline themes and an interactive TUI configuration screen. The fork changes the interface language and, as the difference table puts it, nothing else.

That claim is specific enough to check. The comparison table in the README lists the interface language as English for the upstream and Chinese for the fork, the configuration as compatible because both read the same settings.json, and the feature set as identical with no functional difference. The synchronisation column records the upstream revision the fork is aligned to, which at the time of writing is v2.2.32 at main@bed8501, checked on 2026-10-19, while the Chinese package itself is at 2.2.34.

The mechanism that makes this work is a rule about identifiers. The widget type IDs written into settings.json, such as "model" and "git-branch", stay in English, and the README is explicit that this is so a configuration file remains fully compatible with the upstream version. Everything a user reads is translated: the names and descriptions of 92 widgets with their category labels, every menu item, help text, prompt and dialog in the TUI, the names of layout components such as separators and flex separators, the minimalist mode, the fuzzy search widget picker, the Powerline theme colour continuation, the context window widget, the Git file status family, the GitLab support, the reset timer timezone picker, the confirm dialog and the category filter.

There is one deliberate exception to the translation, and it is a good one. The Claude service status widget is translated for display, but the pure value mode keeps the upstream status values such as ok and minor so that scripts reading the output still work.

The upstream sync is a manual merge with a recorded baseline

The way this fork tracks upstream is the part to understand before you install it, because it determines how quickly you get new features and how much work happens behind the scenes.

Each release names the upstream commit it synchronises to. The current baseline is bed850187783904a9affcaba1dd80e967622e70b, and the README says future synchronisations use that commit as the baseline, with the Chinese package version incrementing independently of the upstream version number. That is the key operational fact: v2.2.34 of the Chinese package is not upstream v2.2.34, and the two numbering lines will not line up.

The release notes are unusually detailed, and they double as a changelog for the upstream project. Reading them is the fastest way to see what changed in ccstatusline itself. Recent entries cover the consumption limit usage and amount widgets, a link to the Claude service status page, compatibility with 8-bit ANSI colours and safe terminal sequences, live preview in the editor and a cursor display fix, and updates to Vitest 5 and the dependencies. Earlier ones cover the Claude service status widget with 48 hours of outage history, unified hide conditions with automatic migration of older configurations, per widget and per numeric type display precision, streaming reads of large transcript files, a display option for the case where there are no Git conflicts, and fixes for usage locks and Git temporary file recovery.

The release cadence is quick, with v2.2.32, v2.2.33 and v2.2.34 published on 2026-10-08, 2026-10-12 and 2026-10-19, each of them described as a synchronisation with the upstream. The last push to the repository was on 2026-10-19.

What a status line can show

The feature list is worth skimming, because the widget catalogue is the actual product and the localisation covers all of it.

There are 92 customisable widgets covering the model, Git, tokens, context, session, cost and speed, with the Git family broken into fine-grained components for pull requests, CI, conflicts, staged files, origin, upstream and the working tree. On top of that sit the presentation features: an interactive TUI configuration screen, several built-in Powerline themes with customisable separators and theme colours that continue across lines, a minimalist mode that strips labels from every widget in one action, a fuzzy search widget picker with substring, initial letter and fuzzy matching and live highlighting, the signed-in Claude account email, multi-line status bar layouts, live preview while configuring, per widget foreground and background colours, custom shell command output or static text or single character symbols, and OSC 8 terminal hyperlinks on things like the Git branch, the pull request and the repository root.

The platform support is stated plainly: macOS, Linux and Windows, and the Windows path is treated as a first class case rather than an afterthought, with a hidden helper process window fix and an npm shim execution fix appearing in the changelog.

The output is not static decoration. The widget set includes cache hit rate, cache read and cache write counters, a compaction counter that switched to reading the compact_boundary marker instead of inferring from a context percentage, a weekly usage figure per model family, overage ratios against a monthly allowance, a session cost rate, and a reset timer that can show an absolute timestamp or a weekday.

Installing it and pointing Claude Code at it

Installation is a global npm install:

npm install -g ccstatusline-zh

or, with Bun:

bun install -g ccstatusline-zh

Then Claude Code has to be told to use it. The status line is configured in the settings file, which is at ~/.claude/settings.json, and the block is short:

{
  "statusLine": {
    "type": "command",
    "command": "ccstatusline-zh",
    "padding": 0,
    "refreshInterval": 10
  }
}

If you would rather not install globally, the command value can be a runner invocation instead:

{
  "statusLine": {
    "type": "command",
    "command": "npx -y ccstatusline-zh@latest",
    "padding": 0
  }
}

Two constraints on that block. The refreshInterval field only takes effect on Claude Code 2.1.97 or newer, and the TUI offers a range of one to sixty seconds, leaving the field out entirely if you do not set it. The other supported command values are the bunx runner and the plain ccstatusline-zh executable used for a self-managed or global installation.

On Windows the settings file lives at %USERPROFILE%\.claude\settings.json instead.

There is one troubleshooting note worth keeping. If the status line is empty in one folder but fine in another, the documentation points at workspace trust, because Claude Code will not run the status command in a directory it has not been told to trust. The upstream guidance is in the usage document in the docs directory of the repository.

The TUI is where the configuration actually happens

Running the setup command opens the interactive configuration screen:

ccstatusline-zh setup

From there you can add, remove and reorder widgets, set colours and styles, pick a Powerline theme, and see the result live as you change it. A separate section of the documentation describes the editing keys, and two of them change how the bar looks at a glance.

Pressing h in the widget editor opens the hide conditions for that widget, and space toggles them with Enter saving. A widget can be hidden when there is no Git repository, when there is no usage data, or when a numeric value is zero, and existing hide options migrate automatically, and decorative text or symbols can be made to follow the hidden state of the widget they are merged into. This is the feature that keeps a status bar with dozens of widgets from turning into noise, and it is the reason the widget count of 92 is not as unwieldy as it sounds.

Numeric formatting is a second lever. Pressing the dot key cycles a numeric widget between fixed decimals, a compact form and integers, and a global override menu opened with n sets the precision for tokens, speed, percentages, memory and cost separately. The global setting takes precedence over the widget setting, and settings.json can also carry a decimals value between zero and six.

For manual testing without running Claude Code, the repository ships an example payload that can be piped straight into the tool, since the status data arrives on standard input as JSON.

Pin the install, because the bar redraws constantly

One configuration choice has an outsized effect on how the status line feels, and the README explains it.

Since version 2.2.14 the TUI offers a pinned global installation option, which installs the current version globally and locks it, so that the status command does not follow the latest tag. The reasoning given is that a pinned installation saves the package resolution on every status bar redraw, and the upstream measurement on Windows is that bunx with the latest tag re-resolves the version tag every time, which is slower than a fixed version. If redraw latency is visible, the pinned install is the option to pick.

The choice is made in the TUI during installation, and it is reflected in the settings file, because the pinned install writes the plain ccstatusline-zh command rather than a runner invocation.

The same area covers installation management in general, with a menu for managing the installation and checking for updates, detection of updates published to the npm registry, and an error screen that appears when a pinned installation and the requested version do not match. The last of those is a small but thoughtful touch: a configuration that pins a version and an install that has drifted apart produce a clear message rather than a silently different build.

Behind the interface, the package is a Node ES module with a single binary entry point pointing at dist/ccstatusline.js, built with bun and a target version of 14, and the repository carries a typedoc setup, a vitest configuration, an eslint configuration, a patches directory and a scripts directory with the version replacement step that runs after the build.

The cost of running a fork

The honest downside of this project is structural rather than technical, and it is worth stating before anyone adopts it.

A fork carries the work of merging upstream changes and re-applying the translation on top. The README is refreshingly transparent about the mechanism, with a long per-version list of what was merged and where the baseline sits, but the reality is that every upstream release requires a maintainer to do that merge, and the Chinese package version only moves when someone does it. A feature that lands upstream today is unavailable in the fork until the next synchronisation, and the fork's own release notes are effectively a changelog of that delay.

The alternative is straightforward: use the upstream ccstatusline directly. The upstream project is the one with the newest features, the newest fixes and the widest issue tracker, and the interface is English. Whether that is a good trade depends on how much you read the status bar and how much you value a Chinese interface, and for many people the answer is simply that they do not mind English in a status line.

The other alternative, for a team that wants Chinese without the merge burden, is to run the upstream and translate only the strings they care about, which is only practical for people comfortable with patching a TypeScript project.

Two smaller notes. The licence is MIT, and the repository carries both a NOTICE file and an AUTHORS file, so the provenance of the fork is documented. And the package is published with only the dist directory in the files list, so installing it does not pull the sources or the screenshots.

Editorial conclusion

ccstatusline-zh suits a Chinese speaking developer who wants the Claude Code status bar in their own language and does not mind that upstream features arrive a sync cycle late, and it is the wrong tool for anyone who is comfortable with the English interface, since the upstream project carries the same features. Verify first that the config you already use works unchanged, because the widget identifiers stay in English and the same settings.json is shared, and check the sync baseline commit in the README before upgrading, since the Chinese package version numbers on its own and does not track the upstream numbers.

Frequently asked questions

Official sources

1. huangguang1999/ccstatusline-zh on GitHub
2. Issues
3. License: MIT
4. README
5. Releases