A Linux-first Claude Code Status Line Powered by Python

What This Package Provides

I’ve released a Python package on GitHub (ceshine/claude-statusline-for-linux) that provides a two-line status line layout for the Claude Code CLI. The package is highly extensible and customizable, so feel free to fork the repository and adapt it to your own preferences!

The package currently provides the following information:

• Line 1: Session Overview
  • Model name: the active Claude model (e.g., “Sonnet 4.6”)
  • Context window usage: a 16-segment visual bar plus a percentage, color-coded green/yellow/red as usage grows; switches to a prominent warning at ≥90%
  • Session cost: cumulative USD cost for the current Claude Code session
  • Per-call token breakdown: token counts from the latest API call, broken down into four categories:
    • Input tokens (i)
    • Output tokens (o)
    • Cache creation tokens (cw)
    • Cache read tokens (cr)
• Line 2: Workspace & Limits
  • Working directory: the base name of the current project directory
  • Git status: branch name plus counts of staged (+), unstaged (~), and untracked (?) files; hidden when not in a Git repository
  • 5-hour rate limit usage: percentage of the 5-hour API quota consumed, with a countdown to reset
  • 7-day rate limit usage: percentage of the 7-day API quota consumed, with a countdown to reset
  • Vim mode: current Vim keybinding mode (NORMAL, INSERT, etc.); hidden when vim mode is inactive

(Note: According to Claude Code’s documentation, the rate limit information is only available after the first API call.)

Differences from the Original Bash Script

This package is heavily based on the Bash script published by Tzeng Yuxio in tzengyuxio/claude-statusline.

The main purposes of this rewrite are:

1. Providing Linux-first support: The Bash script mainly supports macOS (e.g., keychain access, dark/light mode detection, and the BSD-style stat command). I need a Linux-first version.
2. Moving to the Python ecosystem: a. It is much friendlier to developers who are more fluent in Python than in Bash. b. Third-party Python packages are easily accessible. While this package currently does not rely on any third-party packages, it can be easily extended to provide advanced functionality. c. Easy installation is made possible by uv/uvx: simply add uvx --from git+https://github.com/ceshine/claude-statusline-for-linux.git claude_statusline to .claude/settings.json (details below). There is no need for an additional installation script. It is also easier to update.

This package also includes two minor fixes:

1. The --no-optional-locks flag has been added to the git status command, so it no longer has the potential to leave a residual .git/index.lock file when interrupted.
2. Rate limit usage now comes directly from Claude Code, removing the need for an additional background API call and the associated cache management workflow.

Note: There is a Claude Code plugin named claude-hud that provides a much more powerful status-line implementation. However, it is too complicated for my needs, and I am not familiar with TypeScript.

Setup and Updates

Prerequisite:

• uv installed so the uvx command is available. See the uv documentation.
• Git installed and available on PATH (used to render branch and status info).
• A Nerd Font installed for the glyph icons used in the statusline (otherwise icons may render as empty boxes).

Intallation:

Add the following lines in ~/.claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "uvx --from git+https://github.com/ceshine/claude-statusline-for-linux.git claude-statusline"
  }
}

Update:

Run the following command to update the package to the latest version:

uvx --refresh --from git+https://github.com/ceshine/claude-statusline-for-linux.git claude-statusline -v

Side Notes

My Experience with Coding Agents

I recently circled back to Claude Code after experimenting with the Gemini CLI, the Codex CLI, the OpenCode CLI, and the Zed Agent. It is currently my favorite coding agent in terms of usability and correctness. The Codex CLI comes in a close second, with better UI latency and token efficiency.

I mainly use coding agents as a pair-programming partner, so the ability to give feedback, explain concepts clearly, and collaboratively work on ideas and plans is essential for me. I don’t like outsourcing my thinking to the agent. Instead, I expect my ability to write code to become better and better as I use the agent. Claude Code’s explanatory output style is the best out-of-the-box solution for this purpose.

Gemini CLI was decent until the AntiGravity quota was widely abused, which made the free tier utterly unusable and discouraged me from buying a subscription for a poorly run product. Things have improved since late March after a crackdown on the abuse, although the communication around it was poor, and its reputation has been tarnished.

I’ve never gotten OpenCode to work at a level that I’m satisfied with. The cheaper models are not powerful enough for more complicated tasks and often cost me more time to review and fix the generated code. API calls to premium models are too expensive and offer no significant advantages over the official harnesses (Claude Code, Codex, etc.) for me. However, it’s good to have an open-source alternative. Some of its features are, in my opinion, well implemented (e.g., Plan mode and the skill tool). It is just not the right fit for me economically.

Tracking Token Usage

Tracking token usage has become an important part of my workflow. I want to know whether my token usage warrants a subscription. If the usage is low enough, I can always switch to the usage-based APIs.

I noticed that the output token counts provided by the ccusage tool are often significantly undercounted. Additionally, the @ccusage/codex tool appears to have included some duplicates when calculating tokens, which is easily verifiable by looking at the token counts provided by the Codex CLI at the end of a session. Therefore, I created a project to track token usage for the coding agents that I’ve been using. The code is open source and available on GitHub (ceshine/ca-token-usage-monitors). Please note that this tool is mainly for my personal use, so it may not be up to date for all agents, and the documentation may be lacking in some areas.

AI Use Disclosure

I relied heavily on the Claude Code CLI (Sonnet 4.6) to translate the Bash script into Python and refactor the code into a Python package. I manually reviewed all the code and found no serious security issues. Codex CLI was also used to provide an additional layer of review. However, I’m happy to be corrected. Please open an issue if you find any problems.

I used AI tools to help me write the feature list in the Introduction section and revise this post (primarily for grammar and word choice). I wrote most of the content myself; it was not generated using prompts.