Skip to content
Back to search

yet-another-statusline

MarketplaceWorks with Claude CodeGitHub

Claude Code statusline showing info at a glance: tokens, context, model, subagents, burn rate, skills, plugins, OpenSpec specs, task lists, and more

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/tmck-code--yet-another-statusline/badge.svg)](/listings/tmck-code--yet-another-statusline)

HTML

<a href="/listings/tmck-code--yet-another-statusline"><img src="/api/listings/tmck-code--yet-another-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.

These steps run a script from the network that findsafeskills does not scan.

Requires Python 3.10+, and a [Nerd Font](https://www.nerdfonts.com/font-downloads) to render the icons.

curl -fsSL https://raw.githubusercontent.com/tmck-code/yet-another-statusline/main/ops/install.sh | bash

Alongside `statusLine.command`, the installer also wires a `UserPromptSubmit` hook (`yas-prompt-hook.py`) that records per-session prompt timestamps, enabling **accurate turn-scoped subagent display**. It is upserted idempotently — foreign hooks are preserved, stale paths are rewritten on upgrade — and removed on uninstall.

Or install manually:

claude plugin marketplace add tmck-code/yet-another-statusline
claude plugin install yas@yet-another-statusline
claude -p "/yas:init"

If you need to install non-interactively (e.g. in CI/docker)

curl -fsSL https://raw.githubusercontent.com/tmck-code/yet-another-statusline/main/ops/install.sh | YAS_NO_TTY=1 bash
# install with specific python version e.g. 3.15
curl -fsSL https://raw.githubusercontent.com/tmck-code/yet-another-statusline/main/ops/install.sh | YAS_NO_TTY=1 YAS_PYTHON=3.15 bash

Upgrading — the `yas/` layout move

Everything YAS writes except `yas.toml` now lives under a single `$CLAUDE_CONFIG_DIR/yas/` subtree (`yas/cache/` and `yas/state/`). The migration runs automatically — eagerly when you re-run `ops/install.sh`, lazily on the first render otherwise — and is a one-off; afterwards the check costs one `stat()`.

Day-total token counts and the last-prompt handshake are **moved** and survive the upgrade. Rate-limit history, render timings, the transcript parse cache and `mon`'s per-session payloads are **regenerated rather than moved**, so expect a brief cold start after the first upgrade: the `t/m` rate and sparkline, the render-time figure and `mon`'s session list start out empty and refill within one render tick to about five minutes, depending on the item.

Reconfigure later — `/yas:config`

Run `/yas:config` any time to re-run the wizard against the already-installed plugin — switch theme/glyph mode, toggle labels, change the soft limit, or move to Python **3.15**. It re-wires `settings.json` without re-registering the marketplace or reinstalling the plugin.

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 · 17 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "yet-another-statusline",
  4. "description": "Claude Code statusline showing info at a glance: tokens, context, model, subagents, burn rate, skills, plugins, OpenSpec specs, task lists, and more",
  5. "owner": {
  6. "name": "tmck-code",
  7. "url": "https://github.com/tmck-code"
  8. },
  9. "plugins": [
  10. {
  11. "name": "yas",
  12. "description": "Claude Code statusline showing info at a glance: tokens, context, model, subagents, burn rate, skills, plugins, OpenSpec specs, task lists, and more",
  13. "source": "./",
  14. "category": "productivity"
  15. }
  16. ]
  17. }
README.md · README · 343 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # YAS! (Yet Another Statusline)
  2. 🌈 Check out the official landing page here: [YAS! Yet Another Statusline](https://tmck-code.github.io/pages/yas.html)
  3. <img width="1834" height="979" alt="image" src="https://github.com/user-attachments/assets/9c3137b4-dd01-478e-b3bb-6b9d39570104" />
  4. _Most common form is displaying the first few rows, which include the loaded plugins & skills. Extra sections appear below them as needed_
  5. ## Install/Update
  6. Requires Python 3.10+, and a [Nerd Font](https://www.nerdfonts.com/font-downloads) to render the icons.
  7. ```bash
  8. curl -fsSL https://raw.githubusercontent.com/tmck-code/yet-another-statusline/main/ops/install.sh | bash
  9. ```
  10. YAS also runs a `UserPromptSubmit` hook (`yas-prompt-hook.py`) that records
  11. per-session prompt timestamps, enabling **accurate turn-scoped subagent display**.
  12. A plugin install registers it through the plugin's own `hooks/hooks.json`, so the
  13. installer keeps it out of `settings.json` (and removes a copy an older installer
  14. wrote there). For a git-clone install, or with the plugin disabled, the installer
  15. upserts it into `settings.json` instead: foreign hooks are preserved, stale paths
  16. are rewritten on upgrade, and it is removed on uninstall.
  17. Or install manually:
  18. ```bash
  19. claude plugin marketplace add tmck-code/yet-another-statusline#main
  20. claude plugin install yas@yet-another-statusline
  21. claude -p "/yas:init"
  22. ```
  23. If you need to install non-interactively (e.g. in CI/docker)
  24. ```bash
  25. curl -fsSL https://raw.githubusercontent.com/tmck-code/yet-another-statusline/main/ops/install.sh | YAS_NO_TTY=1 bash
  26. # install with specific python version e.g. 3.15
  27. curl -fsSL https://raw.githubusercontent.com/tmck-code/yet-another-statusline/main/ops/install.sh | YAS_NO_TTY=1 YAS_PYTHON=3.15 bash
  28. ```
  29. ### Upgrading — the `yas/` layout move
  30. Everything YAS writes except `yas.toml` now lives under a single
  31. `$CLAUDE_CONFIG_DIR/yas/` subtree (`yas/cache/` and `yas/state/`). The migration
  32. runs automatically — eagerly when you re-run `ops/install.sh`, lazily on the
  33. first render otherwise — and is a one-off; afterwards the check costs one
  34. `stat()`.
  35. Day-total token counts and the last-prompt handshake are **moved** and survive
  36. the upgrade. Rate-limit history, render timings, the transcript parse cache and
  37. `mon`'s per-session payloads are **regenerated rather than moved**, so expect a
  38. brief cold start after the first upgrade: the `t/m` rate and sparkline, the
  39. render-time figure and `mon`'s session list start out empty and refill within
  40. one render tick to about five minutes, depending on the item.
  41. ### Reconfigure later — `/yas:config`
  42. Run `/yas:config` any time to re-run the wizard against the already-installed
  43. plugin — switch theme/glyph mode, toggle labels, change the soft limit, or move
  44. to Python **3.15**. It re-wires `settings.json` without re-registering the
  45. marketplace or reinstalling the plugin.
  46. ## Demo
  47. A dummy session to demonstrate the layout:
  48. <img width="3084" height="1250" alt="yas-0 2 5" src="https://github.com/user-attachments/assets/94d318c7-d7b4-4ad0-a06c-90f303d7f9a7" />
  49. ## Widths
  50. The statusline also renders differently according to available width
  51. | mode | width | screenshot |
  52. |------|-------|------------|
  53. | "medium" | <=80 pixels | <img width="839" height="122" alt="image" src="https://github.com/user-attachments/assets/56519acc-a65c-446a-a938-5a14f093c817" /> |
  54. | "narrow" | <=55 pixels | <img width="537" height="120" alt="image" src="https://github.com/user-attachments/assets/7254cbb7-ea37-4f41-8adc-506cf6b48033" /> |
  55. ---
  56. ## Configuration
  57. Every configurable knob resolves through one fixed precedence chain (highest wins):
  58. ```
  59. CLI flag → canonical YAS_* env var → legacy-alias env var → yas.toml → built-in default
  60. ```
  61. The first source in that chain that is **present and valid** wins; an absent or
  62. invalid source falls through to the next (an empty-string env var counts as
  63. absent). Canonical `YAS_*` env vars always win over their deprecated legacy
  64. aliases when both are set — the aliases keep working but are deprecated.
  65. ### Knobs
  66. | Knob | Env var | Legacy alias | `yas.toml` key | Default |
  67. |------|---------|--------------|----------------|---------|
  68. | `max_width` | `YAS_MAX_WIDTH` | — | `[layout].max_width` | `140` |
  69. | `full_width` | `YAS_FULL_WIDTH` | — | `[layout].full_width` | `false` |
  70. | `soft_limit` | `YAS_SOFT_LIMIT` | — | `[tokens].soft_limit` | `150000` |
  71. | `token_window` | `YAS_TOKEN_WINDOW` | `STATUSLINE_TOKEN_WINDOW` | `[tokens].token_window` | `60` |
  72. | `theme` | `YAS_THEME` (also `--theme` CLI) | `CLAUDE_STATUSLINE_THEME` | `[appearance].theme` | `claude-dark` |
  73. | `bg_shift` | `YAS_BG_SHIFT` (also `--bg-shift` CLI) | — | `[appearance].bg_shift` | `warm` |
  74. | `glyph_mode` | `YAS_GLYPH_MODE` (also `--glyph-mode` CLI) | — | `[appearance.glyphs].mode` | `nerdfont` |
  75. | `single_width` | `YAS_GLYPH_SINGLE_WIDTH` (also `--glyph-single-width` CLI) | — | `[appearance.glyphs].single_width` | `false` |
  76. | `show_icons` | `YAS_SHOW_ICONS` | — | `[appearance.glyphs].show_icons` | `true` |
  77. | `context_state` | `YAS_CONTEXT_STATE` | — | `[context].state` | `false` |
  78. | `context_labels` | `YAS_CONTEXT_LABELS` | — | `[context].labels` | `Smart,Coasting,Foggy,Cooked,Dumb` |
  79. | `context_thresholds` | `YAS_CONTEXT_THRESHOLDS` | — | `[context].thresholds` | `25,50,70,90` |
  80. | `show_render_time` | `YAS_SHOW_RENDER_TIME` | — | `[layout].show_render_time` | `false` |
  81. | `show_git_status` | `YAS_SHOW_GIT_STATUS` | — | `[layout].show_git_status` | `true` |
  82. | `show_tool_uses` | `YAS_SHOW_TOOL_USES` | — | `[layout].show_tool_uses` | `false` |
  83. | `show_tokens_over_time` | `YAS_SHOW_TOKENS_OVER_TIME` | — | `[layout].show_tokens_over_time` | `false` |
  84. | `labels` | `YAS_LABELS` | — | `[layout].labels` | `false` |
  85. | `justify` | `YAS_JUSTIFY` | — | `[layout].justify` | `false` |
  86. | `show_day_stats` | `YAS_SHOW_DAY_STATS` | — | `[tokens].show_day_stats` | `true` |
  87. | `openspec_scan_depth` | `YAS_OPENSPEC_SCAN_DEPTH` | — | `[openspec].scan_depth` | `1` |
  88. #### Valid values
  89. - **`theme`** — 15 built-in themes; unknown or unset falls back to `claude-dark`:
  90. - **Dark:** `claude-dark`, `catppuccin-mocha`, `dracula`, `gruvbox-dark`, `nord`, `one-dark`, `solarized-dark`, `tokyo-night`, `palenight`
  91. - **Light:** `claude-light`, `catppuccin-latte`, `dracula-light`, `gruvbox-light`, `one-light`, `solarized-light`
  92. - **`bg_shift`** — `warm` or `cool`.
  93. - **`glyph_mode`** — all four modes preserve column geometry; an unknown value falls back to `nerdfont`:
  94. - `nerdfont` — default; full fidelity, needs a Nerd Font.
  95. - `ascii` — every non-ASCII glyph → width-1 ASCII; maximum compatibility.
  96. - `unicode` — only Nerd Font PUA icons → non-PUA Unicode; keeps box/block/arrow glyphs.
  97. - `github` — GitHub-paste-safe: folds every glyph a browser renders double-wide (the box-drawing frame, block/sparkline ramp, and EAW-ambiguous punctuation/icons) to a width-1, EAW-narrow/ASCII stand-in, so a render stays column-aligned when pasted into a GitHub markdown code block.
  98. #### Behaviour notes
  99. - **`single_width`** — orthogonal boolean that folds double-width dynamic content (wide emoji, CJK in branch names/paths) to width-1; combinable with any `glyph_mode`. The statusline's own glyphs are already width-1, so column geometry is preserved.
  100. - **`show_icons`** — when `false`, drops essentially every icon/glyph the statusline draws, including the top-left home/folder glyph. The exceptions — glyphs that still render — are the task-plan checkboxes, the subagent status markers, and the box/border and workflow structural glyphs (frame, sparkline blocks, separators, row markers). Text and numbers still render; only the glyph beside each is omitted, and column/border alignment is preserved. `true` by default, preserving current behaviour.
  101. - **`full_width`** — when `true`, makes the box fill the terminal and ignore `max_width`.
  102. - **`show_render_time`** — when `true`, annotates the bottom-right border with the previous run's wall-clock render time (e.g. `…47.2ms──╯`). Off by default; each run shows the prior run's timing, so it is blank on a session's first render.
  103. - **`show_git_status`** — when `false`, skips `git status` entirely and shows no modified/untracked/deleted/renamed counts next to the branch (the branch name still shows). On by default. When on, counts are cached for 5 s per repo, shared across sessions, and invalidated early when `.git/index`, `HEAD` or the branch ref changes.
  104. - **`show_tool_uses`** — when `true`, adds a row (wide layout only) under the tokens/cost band, listing per-tool `tool_use` counts.
  105. - **`show_tokens_over_time`** — when `true`, adds a full-width "tokens over time" row (wide layout only) under the tokens/cost band, showing the `t/m` rate and live sparkline. The trailing column of the tokens/cost row always shows skills + plugins; the sparkline is opt-in via this row.
  106. - **`labels`** — when `true`, paints small superscript field captions into the border/separator rows (wide layout only). **Note:** this is a different knob from `[context].labels`, which is the five-word state list — see [Context state word](#context-state-word). The two share a key name but live in different sections and take different types.
  107. - **`justify`** — when `true`, aligns fields into columns instead of packing them left (wide layout only).
  108. - **`show_day_stats`** — when `true` (the default), shows today's cumulative token and cost totals alongside the session's, as `session/day` pairs. **Note:** this key lives under **`[tokens]`**, not `[layout]`, unlike the other display toggles.
  109. - **`openspec_scan_depth`** — how many repo-levels below `cwd` the OpenSpec downward scan descends looking for nested `openspec/` roots (monorepo-of-repos layout). `1` (the default) finds a repo directly below `cwd`; `2` also finds one nested a level deeper; `0` disables the downward scan entirely (only an `openspec/` found by walking *upward* from `cwd` is used). Unlike the other numeric knobs, `0` is a legal value here.
  110. - **CLI flags** — `--theme NAME` / `--bg-shift DIR` also accept the `--theme=NAME` / `--bg-shift=DIR` form. Pass them in the `statusLine.command` of your `~/.claude/settings.json`.
  111. - **Legacy theme file** — `~/.claude/statusline-theme` is **no longer read**. If you re-run the installer while the file is non-empty and `yas.toml` does not already set a theme, the installer folds its value into `yas.toml` once, and the migration then deletes the file. Otherwise set the theme by hand:
  112. ```toml
  113. [appearance]
  114. theme = "claude-dark"
  115. ```
  116. ### Context state word
  117. `context_state` adds a morphing word to the context line that names how full the
  118. context window is — `Smart → Coasting → Foggy → Cooked → Dumb` — so you can read
  119. the state at a glance instead of doing percentage math. It is **off by default**;
  120. enable it with `YAS_CONTEXT_STATE=1` or `[context].state = true`.
  121. The word is tinted with the same threshold colour as the context bar and sits
  122. just before it; in a narrow box it sheds first (the bar and percentage stay).
  123. - `context_labels` — exactly 5 comma-separated words (`Smart,Coasting,Foggy,Cooked,Dumb` by default).
  124. - `context_thresholds` — exactly 4 strictly-ascending integers in `1..99` (`25,50,70,90` by default), the start percentage of bands 2–5.
  125. The percentage driving the word is YAS's **soft-limit fill ratio** (the same
  126. basis as the context bar), so the word and the bar always agree — the word turns
  127. `Dumb` exactly as the bar fills toward the compaction `soft_limit`.
  128. > Credit: the state-word idea and its default labels/thresholds are ported from
  129. > [**Dumbometer**](https://github.com/MaximoCorrea1/dumbometer) by Maximo Correa
  130. > Rosas (MIT). See [`NOTICE`](NOTICE). Dumbometer maps the word to the *full
  131. > context window*; YAS maps it to the soft-limit fill ratio for bar consistency.
  132. ### `yas.toml`
  133. `yas.toml` lives in `CLAUDE_CONFIG_DIR` (defaults to `~/.claude/`). It is **not**
  134. auto-created — its absence simply means all-defaults — and `/yas:init` never
  135. writes it. See [`yas.example.toml`](yas.example.toml) for a fully-commented
  136. template; copy it to `~/.claude/yas.toml` and uncomment what you want.
  137. ```toml
  138. [layout]
  139. max_width = 140
  140. [tokens]
  141. soft_limit = 150000
  142. token_window = 60
  143. [appearance]
  144. theme = "claude-dark"
  145. bg_shift = "warm"
  146. [appearance.glyphs]
  147. mode = "nerdfont"
  148. single_width = false
  149. show_icons = true
  150. [context]
  151. state = false
  152. labels = ["Smart", "Coasting", "Foggy", "Cooked", "Dumb"]
  153. thresholds = [25, 50, 70, 90]
  154. [openspec]
  155. scan_depth = 1
  156. ```
  157. > **`yas.toml` requires Python 3.11+** — it is parsed with the stdlib `tomllib`.
  158. > On Python 3.10 the file is silently skipped; **environment variables work on
  159. > every Python version**.
  160. Bad config never crashes the statusline. A malformed `yas.toml` is ignored
  161. wholesale, and a single bad / out-of-range / wrong-type value drops only that
  162. one knob back to its default. When any `yas.toml` value is rejected, a compact
  163. warning row — `⚠ yas.toml: N values ignored (...)` — appears at the bottom of
  164. the box listing the rejected knob names. Detailed per-value reasons go to stderr
  165. only when `YAS_DEBUG` is set.
  166. ### Per-model `soft_limit` overrides
  167. Beyond the global `[tokens].soft_limit`, you can declare per-model overrides as
  168. an inline array under `[tokens]`:
  169. ```toml
  170. [tokens]
  171. model = [
  172. { match = "opus", soft_limit = 200000 }, # the whole Opus family
  173. { match = "opus-4-8[1m]", soft_limit = 1000000 }, # 1M-context variant (longer match wins)
  174. ]
  175. ```
  176. - `match` is a **case-insensitive plain substring** (no glob/regex), tested
  177. against the model's id and display name.
  178. - When multiple entries match, the **longest** `match` wins; ties break by array
  179. order (first wins). If no entry matches, the global `soft_limit` is used. So to
  180. single out a variant from its family, give the variant the **longer, more
  181. specific** `match` (above, `opus-4-8[1m]` outranks `opus` for the 1M model).
  182. - **A matching per-model override beats the global `soft_limit` from _any_
  183. source — including the `YAS_SOFT_LIMIT` environment variable.** This is the
  184. one documented exception to the "env beats `yas.toml`" rule: specificity beats
  185. source precedence (there is intentionally no per-model env var). It lets you
  186. raise the compaction-risk threshold for a 1M-context model variant distinctly
  187. from the rest of its family.
  188. ### Other environment variables
  189. | var | default | description |
  190. |-----|---------|-------------|
  191. | `CLAUDE_CONFIG_DIR` | `~/.claude` | base dir for `yas.toml` and the `yas/` state/cache subtree (logs, width file, session payloads) |
  192. | `YAS_DEBUG` | _(unset)_ | when set, prints detailed per-value config-rejection reasons to stderr |
  193. | `COLUMNS` | _(unset)_ | terminal-width fallback when tmux / width-file detection fail |
  194. ### Terminal width
  195. Width is detected by the first source that returns a positive value:
  196. 1. `tmux display-message -p '#{pane_width}'`
  197. 2. `~/.claude/yas/state/signals/terminal-width` file (written by `ops/alacritty.py`, which honours `CLAUDE_CONFIG_DIR`)
  198. 3. `COLUMNS` env var
  199. 4. `shutil.get_terminal_size()` / `/dev/tty` ioctl
  200. ---
  201. ## Uninstalling
  202. Remove the statusline config and uninstall the plugin in one step:
  203. ```bash
  204. curl -fsSL https://raw.githubusercontent.com/tmck-code/yet-another-statusline/main/ops/install.sh | bash -s -- --uninstall --full
  205. ```
  206. Or uninstall manually:
  207. ```bash
  208. claude -p "/yas:uninstall"
  209. claude plugin uninstall yas@yet-another-statusline
  210. ```
  211. `claude plugin uninstall` only deletes the plugin cache — it leaves `statusLine.command`
  212. in `~/.claude/settings.json` pointing at the now-missing script, so the statusline keeps
  213. trying to run. Run the uninstall script (or `/yas:uninstall`) **first** to remove that
  214. config, then uninstall the plugin. Reload Claude Code afterwards.
  215. ---
  216. ## Commands
  217. ```bash
  218. make test # run pytest suite
  219. make demo # animated demo at current terminal width
  220. make statusline/test # same as demo — use during development
  221. make demo/img # render snapshots into demo/
  222. make mon/run # launch multi-session monitor TUI
  223. ```
  224. ## Contributing
  225. Enable the git pre-commit hooks (runs `ruff` / `mypy` / `pytest` on staged Python before each commit):
  226. ```bash
  227. make hooks
  228. ```
  229. ### Installing via git clone
  230. Edits to the checkout take effect immediately — no reinstall step.
  231. ```bash
  232. git clone https://github.com/tmck-code/yet-another-statusline
  233. cd yet-another-statusline
  234. ```
  235. Wire `statusLine.command` in `~/.claude/settings.json` to point at the checkout:
  236. ```json
  237. "statusLine": {
  238. "async": true,
  239. "command": "python3 \"/path/to/yet-another-statusline/claude/statusline_command.py\"",
  240. "type": "command"
  241. }
  242. ```
  243. > **Note:** if you also have the plugin installed, `claude plugin install` will overwrite
  244. > `statusLine.command` back to the plugin cache path. Either uninstall the plugin or bump
  245. > the version in `.claude-plugin/plugin.json` before reinstalling to keep your local path.
  246. For accurate turn-scoped subagent display, also wire the `UserPromptSubmit` hook
  247. (`hooks/yas-prompt-hook.py`) so per-session prompt timestamps are recorded:
  248. ```json
  249. "hooks": {
  250. "UserPromptSubmit": [
  251. { "matcher": "", "hooks": [
  252. { "type": "command", "command": "python3 \"/path/to/yet-another-statusline/hooks/yas-prompt-hook.py\"" }
  253. ] }
  254. ]
  255. }
  256. ```
  257. > The `curl … | bash` installer wires this hook for you (upserted idempotently —
  258. > foreign hooks preserved, stale paths rewritten on upgrade — and removed on
  259. > uninstall); it is only a manual step for a git-clone install. Without it, the
  260. > statusline falls back to a time-window heuristic for which subagents to show.
  261. This prompts before setting `core.hooksPath`. CI runs the same checks on every push, so the hook is fast local feedback rather than the gate.

Ratings and comments

Sign in to rate this skill.

Sign in

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