Skip to content
Back to search

better-statusline

MarketplaceWorks with Claude CodeGitHub

A status line for Claude Code: the session's figures as dot-matrix rings, and the music you are playing beside them

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/autumn1337--better-statusline/badge.svg)](/listings/autumn1337--better-statusline)

HTML

<a href="/listings/autumn1337--better-statusline"><img src="/api/listings/autumn1337--better-statusline/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

From the marketplace this repository carries:

claude plugin marketplace add Autumn1337/better-statusline
claude plugin install better-statusline@better-statusline

To take a new version later:

claude plugin marketplace update better-statusline
claude plugin update better-statusline@better-statusline

Or install from npm and load it for one session:

npm install -g better-statusline
claude --plugin-dir "$(npm root -g)/better-statusline"

To update the npm installation, run `npm install -g better-statusline@latest`.

To load from a clone for one session:

git clone https://github.com/Autumn1337/better-statusline
claude --plugin-dir ./better-statusline

To load a clone in every session, name its parent folder in `CLAUDE_CODE_PLUGIN_DIRS`, in the `env` block of `~/.claude/settings.json`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 18 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "better-statusline",
  3. "owner": {
  4. "name": "Ewen Gao"
  5. },
  6. "metadata": {
  7. "description": "better-statusline, a status line for Claude Code by Ewen Gao",
  8. "version": "0.7.1"
  9. },
  10. "plugins": [
  11. {
  12. "name": "better-statusline",
  13. "source": "./",
  14. "description": "The status line above the prompt: the session's status and the music playing, one design",
  15. "version": "0.7.1"
  16. }
  17. ]
  18. }
README.md · README · 187 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="https://raw.githubusercontent.com/Autumn1337/better-statusline/main/docs/poster.jpg" width="100%" alt="better-statusline, by Ewen Gao: the band above the prompt, a music card beside the rings of context, cache and the limits">
  3. </p>
  4. <h1 align="center">better-statusline</h1>
  5. <p align="center">
  6. A status line for <a href="https://claude.com/claude-code">Claude Code</a>, drawn above the prompt:<br>
  7. the session's figures as dot-matrix rings, and the music you are playing beside them.
  8. </p>
  9. <p align="center">
  10. <img src="https://img.shields.io/badge/Claude_Code-2.1.289+-d97757?style=flat-square&labelColor=242137" alt="Claude Code 2.1.289 or later">
  11. <img src="https://img.shields.io/badge/version-0.7.1-b1b9f9?style=flat-square&labelColor=242137" alt="Version 0.7.1">
  12. <img src="https://img.shields.io/badge/license-MIT-91c882?style=flat-square&labelColor=242137" alt="MIT license">
  13. </p>
  14. <p align="center">
  15. <a href="#the-film">The film</a> ·
  16. <a href="#what-it-shows">What it shows</a> ·
  17. <a href="#install">Install</a> ·
  18. <a href="#options">Options</a>
  19. </p>
  20. ## The film
  21. <p align="center">
  22. <img src="https://raw.githubusercontent.com/Autumn1337/better-statusline/main/docs/film.webp" width="100%" alt="The film: a dot becomes a braille cell, a circle is snapped to dots, the rings fill, the music card takes its colour from its cover, and the whole band folds and turns from dark to light">
  23. </p>
  24. <p align="center">
  25. <sub>
  26. Fifty-two seconds. All of it is drawn in code: the picture, the two covers and the score.<br>
  27. With sound:
  28. <a href="https://github.com/Autumn1337/better-statusline/releases/download/v0.7.1/better-statusline-1080p.mp4">1080p</a> ·
  29. <a href="https://github.com/Autumn1337/better-statusline/releases/download/v0.7.1/better-statusline-4k.mp4">4K</a>
  30. </sub>
  31. </p>
  32. ## What it shows
  33. ![The band as it stands: the music card, then the header over the rings of context, cache, 5-hour and weekly, and the bars of spend](https://raw.githubusercontent.com/Autumn1337/better-statusline/main/docs/band.png)
  34. ### Drawn in dots
  35. <p align="center">
  36. <img src="https://raw.githubusercontent.com/Autumn1337/better-statusline/main/docs/stills/01-eight-dots.jpg" width="49%" alt="A braille cell: eight dots, two across and four down">
  37. <img src="https://raw.githubusercontent.com/Autumn1337/better-statusline/main/docs/stills/02-true-circle.jpg" width="49%" alt="A circle laid over the terminal's grid of dots, each point of it snapped to the nearest dot">
  38. </p>
  39. A braille cell is eight dots. Every drawing here is made of them: a ring is a true circle, found on the screen and snapped dot by dot to the terminal's grid.
  40. ### Rings
  41. <p align="center">
  42. <img src="https://raw.githubusercontent.com/Autumn1337/better-statusline/main/docs/stills/03-context.jpg" width="49%" alt="The context ring: 26%, 259k of 1M">
  43. <img src="https://raw.githubusercontent.com/Autumn1337/better-statusline/main/docs/stills/04-cache.jpg" width="49%" alt="The cache ring: four minutes left of an hour">
  44. </p>
  45. <p align="center">
  46. <img src="https://raw.githubusercontent.com/Autumn1337/better-statusline/main/docs/stills/05-limits.jpg" width="49%" alt="The 5-hour and weekly rings, the weekly one yellow past its pace">
  47. <img src="https://raw.githubusercontent.com/Autumn1337/better-statusline/main/docs/stills/06-rings.jpg" width="49%" alt="The four rings in a row: context, cache, 5-hour, weekly">
  48. </p>
  49. Each ring is lit clockwise from its top, with its figure at its heart.
  50. - **Context**: how full the window is.
  51. - **Cache**: the minutes left before the prompt cache goes cold, counted from the last response. An hour on a subscription inside its limits, five minutes otherwise.
  52. - **5-hour and weekly**: how much of each limit is spent, and when it starts over. The arc turns yellow once you spend faster than the window passes.
  53. Above them, a header names the model and its effort, the folder, the git branch with its staged and modified files, the lines the session added and removed, and the subagents at work.
  54. ### Spend
  55. <p align="center">
  56. <img src="https://raw.githubusercontent.com/Autumn1337/better-statusline/main/docs/stills/07-spend.jpg" width="49%" alt="Bars of dots, one for each turn, beside the session's total and its tokens in and out">
  57. </p>
  58. One bar for each recent turn, beside the session's total. The bars grow by the square root of the cost, so one dear turn leaves the rest standing.
  59. ### Music
  60. <p align="center">
  61. <img src="https://raw.githubusercontent.com/Autumn1337/better-statusline/main/docs/stills/08-colour.jpg" width="49%" alt="The cover's pixels sorted by hue round a wheel, the fullest slice chosen as the card's accent">
  62. <img src="https://raw.githubusercontent.com/Autumn1337/better-statusline/main/docs/stills/09-card.jpg" width="49%" alt="The music card: the cover in its glow, the title, artist and album, the line and the controls, in the cover's own colour">
  63. </p>
  64. On macOS a card shows what Spotify or Apple Music is playing, in an accent read out of the cover. It takes the mouse: play, pause, skip, seek along the line, shuffle, repeat, and the volume at the right end of the controls.
  65. ### The band
  66. <p align="center">
  67. <img src="https://raw.githubusercontent.com/Autumn1337/better-statusline/main/docs/stills/10-terminal.jpg" width="49%" alt="The whole band in a terminal window, above the prompt">
  68. <img src="https://raw.githubusercontent.com/Autumn1337/better-statusline/main/docs/stills/11-themes.jpg" width="49%" alt="The band turning from dark to light">
  69. </p>
  70. `/fold` folds the whole band into one row, and opens it again. The colours are Claude Code's own theme, so the band follows it from dark to light.
  71. ## Requirements
  72. | For | You need |
  73. | --- | --- |
  74. | The status | Claude Code 2.1.289 or later, and `git` |
  75. | The music card | macOS with Spotify or Apple Music |
  76. | Cover pictures | kitty 0.28 or later, or Ghostty; not through tmux, screen or ssh |
  77. | Rings that are round at your font size | `python3`, and a terminal that reports its pixel size |
  78. | Nerd Font icons | Ghostty, kitty or WezTerm, or your own Nerd Font |
  79. Each missing piece takes only its own part away: without a player the band is the status alone, without pictures the card has no cover, without a Nerd Font the icons are plain Unicode.
  80. The plugin is built on Claude Code's function hooks, an early-access API that still changes between releases. It is developed on macOS in Ghostty. The other terminals are handled by what each one reports, and are untested.
  81. ## Install
  82. From the marketplace this repository carries:
  83. ```sh
  84. claude plugin marketplace add Autumn1337/better-statusline
  85. claude plugin install better-statusline@better-statusline
  86. ```
  87. To take a new version later:
  88. ```sh
  89. claude plugin marketplace update better-statusline
  90. claude plugin update better-statusline@better-statusline
  91. ```
  92. Or install from npm and load it for one session:
  93. ```sh
  94. npm install -g better-statusline
  95. claude --plugin-dir "$(npm root -g)/better-statusline"
  96. ```
  97. To update the npm installation, run `npm install -g better-statusline@latest`.
  98. To load from a clone for one session:
  99. ```sh
  100. git clone https://github.com/Autumn1337/better-statusline
  101. claude --plugin-dir ./better-statusline
  102. ```
  103. To load a clone in every session, name its parent folder in `CLAUDE_CODE_PLUGIN_DIRS`, in the `env` block of `~/.claude/settings.json`.
  104. ## Options
  105. Both are rows in `/config`.
  106. | Option | Values | `auto` means |
  107. | --- | --- | --- |
  108. | `icons` | `auto`, `nerd`, `unicode` | Nerd Font icons in the terminals that carry them, Unicode in the rest |
  109. | `motion` | `auto`, `full`, `reduced` | Follow macOS's Reduce Motion; move in full elsewhere |
  110. ## What it costs
  111. At rest the band costs nothing you can measure. Each frame it draws is a redraw of the terminal's, so while music plays the meter's sway takes 3 to 4% of one core in every open session. `motion: reduced` holds it still.
  112. ## How it is built
  113. ```
  114. hooks/register.tsx every hook, and all that reaches the engine
  115. hooks/*.ts what the hooks compute: the status, the music, the terminal
  116. ui/*.tsx the three surface modules: the status, the card, the one-line player
  117. ui/dots.ts the dot drawings: rings, bars, lanes
  118. bridge/ the scripts that reach the Mac: the players, the cover, the cell size
  119. types/index.d.ts the state the plugin keeps
  120. ```
  121. The players reach the plugin through one contract: `bridge/now-playing.js` prints a line of JSON, a `MusicPlayer` as `types/index.d.ts` declares it, each time what plays changes. A bridge for another system, MPRIS on Linux say, needs only to print the same lines.
  122. ## Development
  123. `claude --plugin-dir .` loads the plugin from its folder, reloads it on every save, and lays the engine's types under `.claude-plugin/types/`. Then:
  124. ```sh
  125. claude plugin validate .
  126. tsc -p .
  127. ```
  128. ## License
  129. MIT © Ewen Gao
  130. <p align="center">
  131. <img src="https://raw.githubusercontent.com/Autumn1337/better-statusline/main/docs/stills/12-name.jpg" width="49%" alt="better-statusline, Ewen Gao">
  132. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.