@jv-k/claude-gauge 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +106 -537
- package/dist/cli.js +15 -2
- package/dist/statusline.js +1 -1
- package/dist/wordmark.js +34 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,198 +1,57 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
1
|
+
<h1 align="center">
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jv-k/claude-gauge/main/docs/media/wordmark-dark.png">
|
|
4
|
+
<img src="https://raw.githubusercontent.com/jv-k/claude-gauge/main/docs/media/wordmark-light.png" alt="claude-gauge" width="360">
|
|
5
|
+
</picture>
|
|
6
|
+
</h1>
|
|
7
|
+
|
|
8
|
+
<div align="center">
|
|
9
|
+
<img src="https://raw.githubusercontent.com/jv-k/claude-gauge/main/docs/media/hero.png" alt="The bottom of a Claude Code session: the prompt, and under it the claude-gauge status line with context, 5-hour and weekly usage bars, then the time, session length, repository, branch, model and effort.">
|
|
10
|
+
<p>
|
|
11
|
+
<a href="https://www.npmjs.com/package/@jv-k/claude-gauge"><img src="https://img.shields.io/npm/v/%40jv-k%2Fclaude-gauge" alt="npm version"></a>
|
|
12
|
+
<a href="https://github.com/jv-k/claude-gauge/actions/workflows/test.yml"><img src="https://github.com/jv-k/claude-gauge/actions/workflows/test.yml/badge.svg" alt="Test status"></a>
|
|
13
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/licence-MIT-blue.svg" alt="MIT licence"></a>
|
|
14
|
+
</p>
|
|
15
|
+
<p>
|
|
16
|
+
<a href="#how-it-looks"><b>How it looks</b></a> ◦
|
|
17
|
+
<a href="#getting-started"><b>Getting started</b></a> ◦
|
|
18
|
+
<a href="https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md"><b>Full reference</b></a> ◦
|
|
19
|
+
<a href="#upgrading-from-claude-hud"><b>Upgrading from claude-hud</b></a>
|
|
20
|
+
</p>
|
|
21
|
+
</div>
|
|
22
|
+
|
|
23
|
+
**claude-gauge** is a compact status line and token line for [Claude Code](https://code.claude.com), in the terminal, the VS Code extension and the desktop app.
|
|
24
|
+
|
|
25
|
+
## How it looks
|
|
26
|
+
|
|
27
|
+
In the terminal, the status line sits under the prompt:
|
|
10
28
|
|
|
11
29
|
```text
|
|
12
30
|
ctx 43% ▓▓░░░ 86.0k │ 5h 9% ░░┃░░ → 14:10 │ 7d 41% ▓▓░┃░ → 3d
|
|
13
31
|
11:10 │ 1h12m │ jv-k/claude-gauge │ ⎇ main* ↑1 │ Opus 5.5 │ effort high
|
|
14
32
|
```
|
|
15
33
|
|
|
16
|
-
|
|
34
|
+
The token line shows at the end of each turn:
|
|
17
35
|
|
|
18
36
|
```text
|
|
19
|
-
|
|
37
|
+
11:10 │ 4 req │ out 3.4k (1.2k think) │ cache w6.5k r1.69M │ ctx 43% ▓▓░░░ 427k
|
|
20
38
|
```
|
|
21
39
|
|
|
22
|
-
|
|
40
|
+
In VS Code and the desktop app, Claude ends each reply with the same bars:
|
|
23
41
|
|
|
24
42
|
```text
|
|
25
|
-
5h 9%
|
|
43
|
+
ctx 43% ▓▓░░░ 86.0k │ 5h 9% ░░┃░░ → 14:10 │ 7d 41% ▓▓░┃░ → 3d
|
|
44
|
+
11:10 │ 1h12m │ jv-k/claude-gauge │ ⎇ main* ↑1 │ Opus 5.5 │ effort high
|
|
45
|
+
4 req │ out 3.4k (1.2k think) │ cache w6.5k r1.69M │ ctx 43% ▓▓░░░ 427k
|
|
26
46
|
```
|
|
27
47
|
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
Setup shows the status line with the defaults, and redraws it after each answer as you choose the rows, parts, bar size and theme:
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
## What the bars show
|
|
35
|
-
|
|
36
|
-
### Status line
|
|
37
|
-
|
|
38
|
-
The default rows hold these parts, in this order. The name in the first column is what `--show` takes.
|
|
39
|
-
|
|
40
|
-
| Part | Shows | Meaning |
|
|
41
|
-
| --- | --- | --- |
|
|
42
|
-
| `ctx` | `ctx 43% ▓▓░░░ 86.0k` | How much of the context window is in use, as a percentage, a bar and a token count, the same shape as the token line's `ctx`. Cyan up to 50%, yellow up to 75%, red above. |
|
|
43
|
-
| `5h` | `5h 9% ░░┃░░ → 14:10` | Your 5-hour usage, as a bar, and the time the window resets. |
|
|
44
|
-
| `7d` | `7d 41% ▓▓░┃░ → 3d` | Your weekly usage, and the days until it resets. On the day of the reset it shows the time instead. |
|
|
45
|
-
| `time` | `11:10` | The current local time, or `11:10 am` with `--12h`. |
|
|
46
|
-
| `duration` | `1h12m` | How long the session has run: `45s`, `12m`, `1h12m`, `2d3h`. |
|
|
47
|
-
| `repo` | `jv-k/claude-gauge` | The repository from the `origin` remote. Without one it shows the folder name. It links to the folder. See [Links](#links). |
|
|
48
|
-
| `branch` | `⎇ main* ↑1` | The current git branch. `*` follows it when the work tree has changes, untracked files included, and `↑n` and `↓n` show the commits it is ahead of and behind its upstream. Inside a linked worktree it names that too: `⎇ feat-x* (wt my-feature)`. On GitHub and GitLab it links to the branch's page. See [Links](#links). |
|
|
49
|
-
| `model` | `Opus 5.5` | The model. When requests do not go to the Anthropic API, the provider follows it: `Opus 5.5 (Bedrock)`. See **Provider** below. |
|
|
50
|
-
| `effort` | `effort high` | The reasoning effort, following `/effort` changes, when the model supports effort. |
|
|
51
|
-
|
|
52
|
-
**Context.** The percentage counts input only: fresh input, cache writes and cache reads. It does not count output. A high figure means that Claude Code will soon compact the conversation.
|
|
53
|
-
|
|
54
|
-
**Usage colours.** Each usage bar has 10 colour steps, from dark green at 0–10% to deep red above 90%. These colours, and the others on this page, are the `default` theme's. `--theme` picks another (see [Themes](#themes)).
|
|
55
|
-
|
|
56
|
-
**Pace marker.** The `┃` sits at the share of the window that has passed. If it is ahead of the filled cells, you are using less than an even pace. Its colour comes from the usage projected for the end of the window, calculated as used % × window length ÷ time elapsed:
|
|
57
|
-
|
|
58
|
-
| Projected usage | Colour |
|
|
59
|
-
| --- | --- |
|
|
60
|
-
| below 50% | green |
|
|
61
|
-
| 50% to 75% | teal |
|
|
62
|
-
| 75% to 90% | yellow |
|
|
63
|
-
| 90% to 100% | orange |
|
|
64
|
-
| 100% to 120% | red |
|
|
65
|
-
| above 120% | purple |
|
|
66
|
-
|
|
67
|
-
For the first 9 minutes of the 5-hour window, and for about the first 50 minutes of the week, the marker uses the bar's own colour, because the projection is not reliable that early.
|
|
68
|
-
|
|
69
|
-
**Git.** The `branch`, `git` and `files` parts share one `git status` call per render, made only when one of them is shown. If git takes more than a second, or prints more than a status line can use, `branch` shows the branch name alone, read from the repository's `HEAD` file without running git again, and `git` and `files` stay out of the row. Outside a git repository, and on a detached HEAD, `branch` stays out too.
|
|
70
|
-
|
|
71
|
-
**Reset times.** Reset times use the 24-hour clock and are rounded to the nearest minute.
|
|
72
|
-
|
|
73
|
-
**Provider.** The `model` part reads the provider from the variables that Claude Code sets, or that you set in your shell or in the `env` block of your settings: `Bedrock` for `CLAUDE_CODE_USE_BEDROCK` or `CLAUDE_CODE_USE_MANTLE`, `Vertex` for `CLAUDE_CODE_USE_VERTEX`, `Foundry` for `CLAUDE_CODE_USE_FOUNDRY`, `AWS` for `CLAUDE_CODE_USE_ANTHROPIC_AWS` (Claude Platform on AWS), and `Enterprise` when `ANTHROPIC_BASE_URL` names a host other than `api.anthropic.com`, such as a company gateway. A variable counts as set when it is `1`, `true`, `yes` or `on`. With none of them, the model shows alone.
|
|
74
|
-
|
|
75
|
-
**`~`.** A usage part shows `~`, as in `5h ~`, when Claude Code has not sent usage data yet. This happens before the first response of a session, and on plans that have no such limits. The usage parts need a claude.ai Pro or Max subscription.
|
|
76
|
-
|
|
77
|
-
### More status line parts
|
|
78
|
-
|
|
79
|
-
These parts show only when you name them in a `--show`. A part with nothing to report stays out of its row.
|
|
80
|
-
|
|
81
|
-
| Part | Shows | When |
|
|
82
|
-
| --- | --- | --- |
|
|
83
|
-
| `dir` | The folder Claude Code runs in: `my-project`. It links to the folder. See [Links](#links). | Always. |
|
|
84
|
-
| `cost` | The session's estimated cost at list price: `$1.23`. Behind a spend limit it takes that limit's usage colour. | Always. Resets on `/clear`. |
|
|
85
|
-
| `lines` | Lines of code added and removed this session: `+156 −23`. | Always. |
|
|
86
|
-
| `name` | The session's name, or its AI-generated title, cut to 30 characters with `…`. | When the session has one. |
|
|
87
|
-
| `thinking` | `think`, when extended thinking is on. | Only when on. |
|
|
88
|
-
| `fast` | `fast`, when fast mode is on. | Only when on. |
|
|
89
|
-
| `style` | The output style: `style explanatory`. | When it is not `default`. |
|
|
90
|
-
| `git` | The work tree's changes, as counts: `!2 +1 ✘1 ?3` for modified, staged, deleted and untracked files. A file staged and then changed or deleted again counts in both. An untracked folder counts once, as git lists it. | When the work tree has changes. |
|
|
91
|
-
| `files` | Up to 3 changed files, the most recently changed first: `statusline.ts README.md notes.txt`. A deleted file comes last, because it has no time. In a change set of more than 1000 files, it picks from the first 1000 that git lists. | When the work tree has changes. |
|
|
92
|
-
| `worktree` | The linked git worktree: `wt my-feature`. The `branch` part names it too: `⎇ feat-x (wt my-feature)`. | Inside a linked worktree. |
|
|
93
|
-
| `pr` | The branch's open pull request and its review state: `#1234 approved`. Green when approved, yellow when pending, red when changes are requested, grey as a draft. A GitLab merge request reads `!1234`. It links to the pull request. See [Links](#links). | While a PR is open. |
|
|
94
|
-
| `agent` | The agent: `agent security-reviewer`. | When Claude Code runs with `--agent`. |
|
|
95
|
-
| `cache` | The prompt cache's hit ratio and state: `cache 91% warm`. Green when most requests hit the cache, red when most miss. | After the session's first response. |
|
|
96
|
-
| `spend` | Your spend against the limit: `$314/$500`, or `spend 63%` until Claude Code has the dollar amounts. | Behind a Claude apps gateway with a spend limit. |
|
|
97
|
-
| `version` | The Claude Code version: `v2.1.90`. | Always. |
|
|
98
|
-
| `today` | What all your sessions have spent today, at list price: `today $4.12`. | Once a session has a cost, or the ledger has spend for today. |
|
|
99
|
-
| `week` | What all your sessions have spent this week, from Monday: `week $23.50`. | Once a session has a cost, or the ledger has spend for this week. |
|
|
100
|
-
| `tools` | The tool running now and what it works on, then the five tools used most this session, with counts: `◐ Edit src/a.ts ✓ Read ×12 ✓ Bash ×3`. A file inside the project shows relative to it, and a target longer than 30 characters is cut with `…`. Subagents' tools are not counted. | Once the session has called a tool. |
|
|
101
|
-
| `agents` | The subagents running now, then those that finished in the last minute, up to three, each with its type, model, description and the time it has run: `◐ Explore (Haiku 4.5) Map the reader 1m ✓ Plan (Sonnet 4.5) Plan the change 3m`. A subagent that failed or was stopped shows `✗`. The model shows once the transcript names it: at once when the call picks a model or the subagent runs in the background, else when it finishes. A description longer than 30 characters is cut with `…`. This is not the `agent` part, which names the agent Claude Code runs as. | While a subagent runs, and for a minute after it finishes. |
|
|
102
|
-
| `todos` | The todo Claude is working on, then how many of the session's todos are done: `◐ Writing the tests 2/5`. It reads the list Claude keeps with TodoWrite, or with the task tools (TaskCreate and TaskUpdate). With no todo in progress it shows the count alone, `todos 2/5`, with `✓` once all are done. A todo longer than 30 characters is cut with `…`. It counts only what this session writes to its todos and tasks. A change that a subagent or another session makes does not show. | Once the session has todos. |
|
|
103
|
-
| `skills` | The skills the session used, newest first, then the MCP servers it called: `skills tdd code-review mcp ✗ linear github`. A skill counts when Claude runs it with the Skill tool, or when you run it as a slash command; a built-in command such as `/clear` is not a skill. A server shows from its first call, by the name its tools carry (`mcp__github__search_issues` is `github`). A server whose latest call failed shows first, in red with `✗`, until a call to it works. A call that you reject or interrupt, or that a permission rule denies, does not count either way. It shows three skills and three servers, and every server marked `✗`. A name longer than 30 characters is cut with `…`. Subagents' skills and calls are not counted. To count the MCP servers set up rather than called, see `env`. | Once the session has used a skill or called an MCP server. |
|
|
104
|
-
| `compactions` | How many times the conversation has been compacted, by you with `/compact` or by Claude Code when the context fills: `compactions 2`. Many compactions in one session mean that it has lost detail from its early work. | After the first compaction. |
|
|
105
|
-
| `reply` | The time since Claude last replied: `reply 3m ago`. It counts from the last block of Claude's last response. Subagents' replies, and the error messages Claude Code writes in place of a reply, do not count. | After Claude's first reply. |
|
|
106
|
-
| `speed` | The output speed of Claude's last response, in tokens per second: `84 tok/s`, or `6.3 tok/s` below ten. It counts the response's output tokens over the time from the prompt or tool result that asked for it to the response's last block, so the wait for the first token counts too. | After a response with output tokens. |
|
|
107
|
-
| `env` | What Claude Code loads into the session: `env 2 md 4 rules 3 mcp 2 hooks`, for CLAUDE.md files, rules, MCP servers and hooks. A kind with none stays out. See [Environment and plan](#environment-and-plan). | When anything is loaded. |
|
|
108
|
-
| `plan` | Your claude.ai plan and the account you are signed in with: `Claude Max 20x (me@example.com)`. | When the config names them. |
|
|
109
|
-
| `models` | Your weekly usage for each model with a weekly limit of its own, shown as `7d` shows the week, with the model's name: `7d Opus 41% ▓▓░┃░ → 3d`. Several models show as several segments, sorted by their window's name in Claude Code's input. `--no-labels` drops `7d` and keeps the name. See [Per-model windows](#per-model-windows). | When Claude Code sends per-model weekly windows. |
|
|
110
|
-
| `limit` | A notice naming each window at 100%, with its reset: `limit reached: 5h → 14:10`, or `limit reached: 7d → 3d, 7d Opus → 3d` for more than one. It covers `5h`, `7d`, each per-model window and the spend limit. The 5-hour reset shows as a time, and the others as days, or as a time on the day of the reset. `--no-reset` drops the resets, and the window names stay with `--no-labels`. In deep red. | While a window is at 100%. |
|
|
111
|
-
| `ram` | The system's memory in use, as a percentage, a bar and the amount in gigabytes: `ram 66% ▓▓▓░░ 10.5G`. It takes the usage colours. See [Memory, text and command](#memory-text-and-command). | Always. |
|
|
112
|
-
| `text` | Fixed text that you give with `--text`, such as a label for the machine: `work laptop`. | With `--text`. |
|
|
113
|
-
| `command` | The first line of output of a shell command that you give with `--command`: `prod-eu`. See [Memory, text and command](#memory-text-and-command) for the rules it runs under. | With `--command`, when the command succeeds in time. |
|
|
114
|
-
|
|
115
|
-
**Cost ledger.** `today` and `week` add up the spend of every session, from a ledger that each terminal render keeps in `~/.claude/claude-gauge/.state/ledger.json` (under `$CLAUDE_CONFIG_DIR` when that is set). A render records what its session has spent since the session was last recorded, against the local day of that render, so a session that runs past midnight counts on both days. Each session writes to the ledger at most once every 10 seconds; the parts always include the current session's latest cost, so they never fall behind in the session you are in. Spend a session makes in its last 10 seconds is recorded when it next renders, so a session that ends then leaves that spend out. Several sessions can render at once without harm: a write locks the ledger and replaces the file whole. The ledger keeps 31 days.
|
|
116
|
-
|
|
117
|
-
**Transcript parts.** `tools`, `agents`, `todos`, `skills`, `compactions`, `reply` and `speed` read the session transcript. claude-gauge reads it only when a `--show` names such a part, and then reads only the lines added since the last render. It keeps its place in each transcript in `~/.claude/claude-gauge/.state/transcripts/`, or under `$CLAUDE_CONFIG_DIR` when that is set. A transcript that shrinks or is replaced is read again from the start.
|
|
118
|
-
|
|
119
|
-
#### Per-model windows
|
|
120
|
-
|
|
121
|
-
Claude Code's documented status line input has the 5-hour, weekly and spend windows. Some plans also have a weekly limit for one model, such as Opus, and Anthropic's usage figures name that window `seven_day_opus`. When Claude Code sends a window named `seven_day_<model>` in its `rate_limits`, `models` shows it and `limit` watches it. The name after `7d` is the part after `seven_day_`, capitalised, with underscores as spaces, so a new model needs no new release. A name can hold letters, digits, underscores, dots and hyphens. A window whose name holds anything else stays out. A window with no percentage stays out. Until Claude Code sends such a window, `models` shows nothing and stays out of its row.
|
|
122
|
-
|
|
123
|
-
#### Environment and plan
|
|
124
|
-
|
|
125
|
-
`env` and `plan` read the files Claude Code reads, on your machine, with no network call. The config folder is `~/.claude`, or `CLAUDE_CONFIG_DIR` when you set it.
|
|
126
|
-
|
|
127
|
-
- **CLAUDE.md files**: the user's `CLAUDE.md` in the config folder, the managed one an administrator installs, and `CLAUDE.md`, `.claude/CLAUDE.md` and `CLAUDE.local.md` in the folder Claude Code runs in and every folder above it. Files in subfolders load only when Claude works there, so they do not count.
|
|
128
|
-
- **Rules**: every `.md` file, at any depth, under `rules/` in the config folder and under `.claude/rules/` in the folder Claude Code runs in and every folder above it.
|
|
129
|
-
- **MCP servers**: the user and local servers in `.claude.json`, the project's `.mcp.json`, and the managed `managed-mcp.json`, each name once. Project servers that a settings file turns off with `disabledMcpjsonServers` do not count.
|
|
130
|
-
- **Hooks**: one per hook command in the user, project, local and managed settings files.
|
|
131
|
-
- **Plan**: the subscription in `.credentials.json` in the config folder: `max` on the 20x tier is `Claude Max 20x`, `pro` is `Claude Pro`. Only the plan fields are read from that file. Where that file does not exist, as on macOS, where Claude Code keeps the login in the Keychain, the plan comes from the account in `.claude.json` instead. claude-gauge never reads the Keychain.
|
|
132
|
-
- **Account**: the email address of the signed-in account, from `.claude.json`.
|
|
133
|
-
|
|
134
|
-
Plugin hooks and MCP servers are not counted.
|
|
135
|
-
|
|
136
|
-
#### Memory, text and command
|
|
137
|
-
|
|
138
|
-
`ram` reads the memory that each system's own monitor reports as in use, with no network call:
|
|
139
|
-
|
|
140
|
-
- **macOS**: app memory, wired memory and compressed memory, from `vm_stat`. Activity Monitor shows the same sum as Memory Used.
|
|
141
|
-
- **Linux**: the total less `MemAvailable`, from `/proc/meminfo`. Memory that the kernel uses as a cache and gives back on demand does not count as used.
|
|
142
|
-
- **Windows**: the total less the available memory, as Node.js reports them.
|
|
143
|
-
|
|
144
|
-
If the system figures cannot be read, `ram` uses the free and total memory that Node.js reports.
|
|
145
|
-
|
|
146
|
-
`text` shows the value of `--text` as you give it. claude-gauge removes any terminal control codes from it first.
|
|
147
|
-
|
|
148
|
-
`command` runs a shell command that you choose. These rules keep it safe and keep the status line fast:
|
|
149
|
-
|
|
150
|
-
- **It runs only when you ask twice.** `--command` must name a command, and a `--show` row must name the `command` part. Without both, nothing runs.
|
|
151
|
-
- **It runs as you wrote it.** claude-gauge passes the command to the system shell (`sh` on macOS and Linux, `cmd.exe` on Windows) with your permissions, in the folder Claude Code runs in, with no input. Claude Code renders the status line often, so use a quick command that only reads.
|
|
152
|
-
- **It has 500 ms.** After 500 ms, claude-gauge stops the command and the part shows nothing. A slow or hung command delays the status line by 500 ms at most. On macOS and Linux, claude-gauge also stops any job that the command started in the background, when the command ends or runs out of time. On Windows, such a job can keep running.
|
|
153
|
-
- **It shows one clean line.** The part shows the first line of output that has text in it. claude-gauge removes terminal control codes from that line, so the output cannot move the cursor, change colours or set the window title. Error output is discarded.
|
|
154
|
-
- **It fails quietly.** When the command exits with an error, runs out of time, or prints more than 64 KB, the part shows nothing and the other parts show as usual.
|
|
155
|
-
|
|
156
|
-
#### Links
|
|
48
|
+
## Getting started
|
|
157
49
|
|
|
158
|
-
|
|
50
|
+
You need Claude Code and Node.js 18 or later.
|
|
159
51
|
|
|
160
|
-
|
|
161
|
-
- **`branch`** links to the branch's page on GitHub or GitLab. The link shows only when the `origin` remote is on `github.com` or `gitlab.com` and the branch has an upstream on `origin`, because a branch without one may not be on the remote. The link goes to the upstream branch, which can have a different name from the local branch.
|
|
162
|
-
- **`pr`** links to the pull request, at the web address that Claude Code gives.
|
|
52
|
+
### Install the plugin
|
|
163
53
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
### Token line
|
|
167
|
-
|
|
168
|
-
| Part | Meaning |
|
|
169
|
-
| --- | --- |
|
|
170
|
-
| `12:10` | The local time the turn ended. |
|
|
171
|
-
| `4 req` | API requests made since your last prompt, subagents included. |
|
|
172
|
-
| `out 3.4k (1.2k think)` | Output tokens, and how many of them were thinking. |
|
|
173
|
-
| `cache w6.5k r1.69M` | Prompt-cache writes and reads. |
|
|
174
|
-
| `ctx 43% ▓▓░░░ 427k` | The context the last request carried, as a share of the window and as a bar. |
|
|
175
|
-
|
|
176
|
-
**Requests.** One request is one model call, so each tool round trip counts as one request. With `--latest`, the count leaves out the request that writes the final reply, because that request is still running. As a Stop hook, the count includes every request.
|
|
177
|
-
|
|
178
|
-
**Thinking.** Thinking tokens are part of the output figure. They are not added to it.
|
|
179
|
-
|
|
180
|
-
**Cache.** Cache writes (`w`) are new content stored for reuse, and they cost a little more than plain input. Cache reads (`r`) come to about the number of requests × the context size, so they can reach millions. Reads are cheap, so a large `r` is normal.
|
|
181
|
-
|
|
182
|
-
**Fresh input.** Uncached input counts toward `ctx` but is not shown on its own, because it is usually tiny.
|
|
183
|
-
|
|
184
|
-
**Context.** The `ctx` figure should match the status line's context percentage, when the token line uses the right window size (see [Token line options](#token-line-options)).
|
|
185
|
-
|
|
186
|
-
## Requirements
|
|
187
|
-
|
|
188
|
-
- Claude Code
|
|
189
|
-
- Node.js 18 or later, with npm for the npm route
|
|
190
|
-
|
|
191
|
-
## Install
|
|
192
|
-
|
|
193
|
-
### As a Claude Code plugin
|
|
194
|
-
|
|
195
|
-
In Claude Code, add this repository as a plugin marketplace, install the plugin, and run its setup:
|
|
54
|
+
In Claude Code, run these three commands:
|
|
196
55
|
|
|
197
56
|
```text
|
|
198
57
|
/plugin marketplace add jv-k/claude-gauge
|
|
@@ -200,213 +59,97 @@ In Claude Code, add this repository as a plugin marketplace, install the plugin,
|
|
|
200
59
|
/claude-gauge:setup
|
|
201
60
|
```
|
|
202
61
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
The plugin has three commands:
|
|
206
|
-
|
|
207
|
-
| Command | Effect |
|
|
208
|
-
| --- | --- |
|
|
209
|
-
| `/claude-gauge:setup` | Adds the status line and the token line. If your settings already run another status line, such as claude-hud, it asks before it replaces it, and saves it. |
|
|
210
|
-
| `/claude-gauge:configure` | Changes the switches of a bar, adds the missing one, or takes one out. |
|
|
211
|
-
| `/claude-gauge:uninstall` | Takes claude-gauge out of your settings and puts back the status line it replaced. |
|
|
62
|
+
If Claude Code does not find `/claude-gauge:setup`, run `/reload-plugins` first. Setup asks which bars you want. Then it backs up `~/.claude/settings.json` and adds the bars to it. Start a new session to see them.
|
|
212
63
|
|
|
213
|
-
|
|
64
|
+
### Or install from npm
|
|
214
65
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
In a terminal, run setup with npx:
|
|
66
|
+
In a terminal, run:
|
|
218
67
|
|
|
219
68
|
```sh
|
|
220
69
|
npx @jv-k/claude-gauge setup
|
|
221
70
|
```
|
|
222
71
|
|
|
223
|
-
Setup shows the status line
|
|
224
|
-
|
|
225
|
-
Setup copies the two scripts into `~/.claude/claude-gauge/runtime/` (under `$CLAUDE_CONFIG_DIR` when that is set) and points the settings there, so the bars keep working when npm clears its npx cache. To keep the `claude-gauge` command at hand instead of running it through npx, install it globally with `npm install -g @jv-k/claude-gauge`.
|
|
226
|
-
|
|
227
|
-
The `claude-gauge` command has four commands:
|
|
72
|
+
Setup shows the status line and asks which parts you want. It draws the status line again after each answer:
|
|
228
73
|
|
|
229
|
-
|
|
230
|
-
| --- | --- |
|
|
231
|
-
| `claude-gauge setup` | Adds the status line and the token line. |
|
|
232
|
-
| `claude-gauge configure` | Changes the switches of a bar that setup added, adds the missing one, or takes one out. |
|
|
233
|
-
| `claude-gauge uninstall` | Takes claude-gauge out of your settings and puts back the status line it replaced. |
|
|
234
|
-
| `claude-gauge update` | Copies the scripts of the version you run into `~/.claude/claude-gauge/runtime/`, and keeps your switches. |
|
|
74
|
+
|
|
235
75
|
|
|
236
|
-
|
|
76
|
+
### VS Code and the desktop app
|
|
237
77
|
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
| Switch | Effect |
|
|
241
|
-
| --- | --- |
|
|
242
|
-
| `--status-line <switches>` | Adds the status line, run with these switches. `""` gives the defaults. |
|
|
243
|
-
| `--no-status-line` | Leaves the status line out, or takes it out. |
|
|
244
|
-
| `--token-line <switches>` | Adds the token line, run with these switches. `""` gives the defaults. |
|
|
245
|
-
| `--no-token-line` | Leaves the token line out, or takes it out. |
|
|
246
|
-
| `--replace` | Replaces a status line that is not claude-gauge's. Without it, a command with bar switches stops rather than replace it. |
|
|
247
|
-
| `--yes` | With `setup` only: adds each bar that the switches above do not name, with the defaults. |
|
|
248
|
-
|
|
249
|
-
For example, both bars with the defaults, and then 10-cell bars on the status line:
|
|
250
|
-
|
|
251
|
-
```sh
|
|
252
|
-
npx @jv-k/claude-gauge setup --yes
|
|
253
|
-
npx @jv-k/claude-gauge configure --status-line "--segments 10"
|
|
254
|
-
```
|
|
78
|
+
The VS Code extension and the desktop app show no custom status line and no token line. To see the bars there, add one SessionStart hook for each bar. In those two apps, the hook tells Claude to end each reply with the bars. In the terminal, it does nothing. First install claude-gauge with the plugin or with npm, as above. Then add the hooks in one of two ways.
|
|
255
79
|
|
|
256
|
-
|
|
80
|
+
#### Ask Claude
|
|
257
81
|
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
Paste this into a Claude Code session:
|
|
82
|
+
Paste this prompt into a Claude Code session:
|
|
261
83
|
|
|
262
84
|
```text
|
|
263
|
-
|
|
85
|
+
Set up claude-gauge for the VS Code extension and the desktop app.
|
|
86
|
+
Read ~/.claude/settings.json, or $CLAUDE_CONFIG_DIR/settings.json when that variable is set.
|
|
87
|
+
Make a backup copy of the file first.
|
|
88
|
+
Find the statusLine command that runs claude-gauge's statusline.js, and the Stop hook that runs its tokenline.js.
|
|
89
|
+
Add two entries to hooks.SessionStart and keep every entry that is there already:
|
|
90
|
+
one runs the same statusline.js with --instruct, and one runs the same tokenline.js with --instruct.
|
|
91
|
+
Put each bar's existing switches after --instruct.
|
|
92
|
+
The status line already shows the time, so give the token line hook a --show without time, such as --show req,out,cache,ctx.
|
|
93
|
+
Test each new command with CLAUDE_CODE_ENTRYPOINT=claude-vscode. It must print an instruction.
|
|
94
|
+
Then tell me to start a new session.
|
|
264
95
|
```
|
|
265
96
|
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
### By hand
|
|
97
|
+
#### Add the hooks by hand
|
|
269
98
|
|
|
270
|
-
|
|
99
|
+
1. Open `~/.claude/settings.json` and find the `statusLine` command that setup wrote. Its folder is `~/.claude/claude-gauge/runtime/` after an npm install, or `~/.claude/claude-gauge/launcher/` after a plugin install.
|
|
100
|
+
2. Add these two entries to the `SessionStart` array under `hooks`, with the folder from step 1. Keep the entries that are there already.
|
|
271
101
|
|
|
272
|
-
```
|
|
273
|
-
|
|
274
|
-
|
|
102
|
+
```json
|
|
103
|
+
{ "hooks": [ { "type": "command", "command": "node ~/.claude/claude-gauge/runtime/statusline.js --instruct" } ] },
|
|
104
|
+
{ "hooks": [ { "type": "command", "command": "node ~/.claude/claude-gauge/runtime/tokenline.js --instruct --show req,out,cache,ctx" } ] }
|
|
105
|
+
```
|
|
275
106
|
|
|
276
|
-
|
|
107
|
+
3. Start a new session.
|
|
277
108
|
|
|
278
|
-
|
|
109
|
+
#### The result
|
|
279
110
|
|
|
280
|
-
|
|
281
|
-
{
|
|
282
|
-
"statusLine": {
|
|
283
|
-
"type": "command",
|
|
284
|
-
"command": "node ~/.claude/claude-gauge/dist/statusline.js"
|
|
285
|
-
}
|
|
286
|
-
}
|
|
287
|
-
```
|
|
111
|
+
Each reply then ends with the bars, as in [How it looks](#how-it-looks). The token line leaves out its time there, because the status line shows it. To change a bar in the replies, put its switches after `--instruct`, for example `--show 5h,7d`. On a 1M-context model, add `--window 1m` to both hooks. Each reply needs one or two more short tool calls. Uninstall also removes these hooks.
|
|
288
112
|
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
```json
|
|
292
|
-
{
|
|
293
|
-
"hooks": {
|
|
294
|
-
"Stop": [
|
|
295
|
-
{
|
|
296
|
-
"hooks": [
|
|
297
|
-
{ "type": "command", "command": "node ~/.claude/claude-gauge/dist/tokenline.js" }
|
|
298
|
-
]
|
|
299
|
-
}
|
|
300
|
-
]
|
|
301
|
-
}
|
|
302
|
-
}
|
|
303
|
-
```
|
|
304
|
-
|
|
305
|
-
Start a new Claude Code session to pick up the changes.
|
|
306
|
-
|
|
307
|
-
To install without git, download the two built files instead:
|
|
308
|
-
|
|
309
|
-
```sh
|
|
310
|
-
mkdir -p ~/.claude/claude-gauge/dist
|
|
311
|
-
curl -fsSL https://raw.githubusercontent.com/jv-k/claude-gauge/main/dist/statusline.js -o ~/.claude/claude-gauge/dist/statusline.js
|
|
312
|
-
curl -fsSL https://raw.githubusercontent.com/jv-k/claude-gauge/main/dist/tokenline.js -o ~/.claude/claude-gauge/dist/tokenline.js
|
|
313
|
-
```
|
|
113
|
+
### Change, update or remove the bars
|
|
314
114
|
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
-
|
|
320
|
-
- **Have Claude paste the bars into its replies.** A SessionStart hook asks it to, in those two hosts only.
|
|
321
|
-
|
|
322
|
-
For the second way, keep the settings entries above and add one hook per bar you want in the replies:
|
|
323
|
-
|
|
324
|
-
```json
|
|
325
|
-
"hooks": {
|
|
326
|
-
"SessionStart": [
|
|
327
|
-
{ "hooks": [ { "type": "command", "command": "node ~/.claude/claude-gauge/dist/statusline.js --instruct" } ] },
|
|
328
|
-
{ "hooks": [ { "type": "command", "command": "node ~/.claude/claude-gauge/dist/tokenline.js --instruct" } ] }
|
|
329
|
-
]
|
|
330
|
-
}
|
|
331
|
-
```
|
|
332
|
-
|
|
333
|
-
`--instruct` reads the host from the `CLAUDE_CODE_ENTRYPOINT` variable, which Claude Code sets and its hooks inherit. In the VS Code extension (`claude-vscode`) and the desktop app (`claude-desktop`, `claude-desktop-3p`) it prints an instruction into Claude's context: end every reply with the output of the same command with `--latest` in place of `--instruct`, run as the last tool call of the turn and pasted verbatim in one code block, never guessed and never reused from an earlier turn. In the terminal CLI (`cli`) it prints nothing. One settings file therefore serves every host, and the terminal, which shows the bars already, stays as it is. Any other or missing value also prints nothing: the variable is not documented, so a host under a new name gets a quiet session rather than a wrong one. `echo $CLAUDE_CODE_ENTRYPOINT` in Claude's shell shows the value.
|
|
334
|
-
|
|
335
|
-
The hook runs when a session starts, resumes, is cleared with `/clear`, or compacts, so the instruction survives all four. The reply in the VS Code panel then ends like this:
|
|
336
|
-
|
|
337
|
-
```text
|
|
338
|
-
ctx 43% ▓▓░░░ 86.0k │ 5h 9% ░░┃░░ → 14:10 │ 7d 41% ▓▓░┃░ → 3d
|
|
339
|
-
11:10 │ 1h12m │ jv-k/claude-gauge │ ⎇ main* ↑1 │ Opus 5.5 │ effort high
|
|
340
|
-
12:10 │ 4 req │ out 3.4k (1.2k think) │ cache w6.5k r1.69M │ ctx 43% ▓▓░░░ 427k
|
|
341
|
-
```
|
|
342
|
-
|
|
343
|
-
Each hook takes its bar's usual switches, such as `--show` and `--segments`, and passes them on to the command it names. On a 1M-context model, add `--window 1m` to both, for the reason in [Token line options](#token-line-options). Each reply costs one or two short tool calls more.
|
|
344
|
-
|
|
345
|
-
`--latest` finds the calling session by the `CLAUDE_CODE_SESSION_ID` variable, which Claude Code sets for the commands it runs. Without that variable, it takes the newest transcript of the current folder. It prints no colours, because a reply shows colour codes as junk.
|
|
346
|
-
|
|
347
|
-
**What the status line can rebuild.** A transcript holds less than the input Claude Code sends a status line, so with `--latest`:
|
|
348
|
-
|
|
349
|
-
- `ctx`, `model` and `effort` come from the session's last response. `duration` counts from the first entry in the transcript.
|
|
350
|
-
- `time`, `dir`, `repo`, `branch` and `worktree` come from the clock and from git, as in the terminal.
|
|
351
|
-
- `env` and `plan` come from the files on disk, and the provider after `model` from the environment, as in the terminal.
|
|
352
|
-
- `5h`, `7d`, `models` and `limit` come from the last time the status line ran in a terminal, in any session. Claude Code sends usage figures only to a status line, so each terminal render saves them in `~/.claude/claude-gauge/.state/usage.json`, per-model windows included. The figures are as recent as that render. Until a terminal render saves them, and after a window resets, `5h` and `7d` show `~`, and `models` and `limit` leave that window out.
|
|
353
|
-
- `today` and `week` come from the cost ledger that terminal renders keep. The figures are as recent as the last terminal render of each session.
|
|
354
|
-
- The other parts, such as `cost`, `lines`, `pr` and `cache`, have nothing to report, and stay out of their row.
|
|
355
|
-
|
|
356
|
-
## Options
|
|
357
|
-
|
|
358
|
-
Both scripts take switches on the command line, so you set them in the `command` of your settings and never edit the scripts. A switch takes its value after a space or an `=`: `--show 5h,7d` and `--show=5h,7d` are the same.
|
|
359
|
-
|
|
360
|
-
### Status line options
|
|
361
|
-
|
|
362
|
-
| Switch | Effect |
|
|
363
|
-
| --- | --- |
|
|
364
|
-
| `--show <parts>` | One row: the parts to show, in the order given, separated by commas. Parts: those in [Status line](#status-line) and [More status line parts](#more-status-line-parts). Repeat `--show` for more rows. Default: two rows, `ctx,5h,7d` and `time,duration,repo,branch,model,effort`. |
|
|
365
|
-
| `--segments <5\|10>` | Cells per bar. Default: 5. Any other value gives 5. |
|
|
366
|
-
| `--no-labels` | Drops the labels in front of values, such as `ctx`, `5h`, `7d` and `effort`. |
|
|
367
|
-
| `--no-bars` | Drops the bars, and with them the pace markers. |
|
|
368
|
-
| `--no-pace` | Drops the pace markers. |
|
|
369
|
-
| `--no-reset` | Drops the reset times. |
|
|
370
|
-
| `--12h` | Shows the `time` part and reset times on the 12-hour clock. Default: 24-hour. |
|
|
371
|
-
| `--compact` | Fits narrow terminals: `│` between parts with no spaces round it, and shorter labels: `c` for `ctx`, `eff` for `effort`, `sty` for `style`, `agt` for `agent`, `cch` for `cache`, `spd` for `spend`, `tdy` for `today`, `wk` for `week` and `cmp` for `compactions`. The other labels are short already. |
|
|
372
|
-
| `--no-links` | Drops the links on `dir`, `repo`, `branch` and `pr`. See [Links](#links). |
|
|
373
|
-
| `--right <parts>` | The parts to right-align, separated by commas. In each row that shows any of them, they move to the end of the row, in the row's order, and spaces fill the gap so the row ends at the terminal's right edge. Claude Code gives the terminal width in `COLUMNS`. When the width is unknown, as with `--latest`, the row is too long to leave a gap, or the row holds characters whose width varies by terminal, such as CJK text and emoji, the row is left as it is. Repeat `--right` to name more parts. |
|
|
374
|
-
| `--text <text>` | The text that the `text` part shows. Quote text that holds spaces: `--text 'work laptop'`. If you give `--text` more than once, the last one counts. |
|
|
375
|
-
| `--command <command>` | The shell command that the `command` part runs. Quote the command as one value: `--command 'kubectl config current-context'`. It runs only when a `--show` row names `command`. See [Memory, text and command](#memory-text-and-command) for its rules. |
|
|
376
|
-
| `--theme <name>` | The colour preset: `default`, `mono`, `high-contrast` or `pastel`. An unknown name gives `default`. See [Themes](#themes). |
|
|
377
|
-
| `--color <part>=<colour>` | One part's colour, over the theme's: a name such as `red` or `bright-red`, a 256-colour number from `0` to `255`, or a hex colour such as `#ff8800` or `#f80`. Separate more parts with commas, or repeat the switch. See [Colours and bar characters](#colours-and-bar-characters). |
|
|
378
|
-
| `--bar-filled <char>` | The character of a filled bar cell. Default: `▓`. |
|
|
379
|
-
| `--bar-empty <char>` | The character of an empty bar cell. Default: `░`. |
|
|
380
|
-
| `--latest` | Prints the rows for the calling session from its transcript, as plain text, instead of reading Claude Code's input. See [In VS Code and the desktop app](#in-vs-code-and-the-desktop-app). |
|
|
381
|
-
| `--window <size>` | With `--latest`: the context window size, for example `200k` or `1m`, as for the token line. |
|
|
382
|
-
| `--instruct` | As a SessionStart hook: in the VS Code extension and the desktop app, prints an instruction that has Claude end each reply with the `--latest` rows; in the terminal CLI, prints nothing. The other switches pass through to the command it names. See [In VS Code and the desktop app](#in-vs-code-and-the-desktop-app). |
|
|
115
|
+
| Plugin | npm | Effect |
|
|
116
|
+
| --- | --- | --- |
|
|
117
|
+
| `/claude-gauge:configure` | `npx @jv-k/claude-gauge configure` | Changes the parts and switches of the bars. |
|
|
118
|
+
| `/plugin`, then **Marketplaces** | `npx @jv-k/claude-gauge@latest update` | Updates claude-gauge and keeps your switches. |
|
|
119
|
+
| `/claude-gauge:uninstall` | `npx @jv-k/claude-gauge uninstall` | Removes claude-gauge and puts back the status line it replaced. |
|
|
383
120
|
|
|
384
|
-
|
|
121
|
+
## Upgrading from claude-hud
|
|
385
122
|
|
|
386
|
-
|
|
123
|
+
If you use [claude-hud](https://github.com/jarrodwatts/claude-hud), run setup as in [Getting started](#getting-started). Setup finds claude-hud's status line, shows it, and asks before it replaces it. It saves claude-hud's command, so uninstall puts claude-hud back. Keep the claude-hud plugin installed until you are sure, because that command needs it.
|
|
387
124
|
|
|
388
|
-
|
|
125
|
+
claude-gauge has no configuration file. Each claude-hud option becomes a part or a switch in the bar's command. The reference [maps each option](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md#upgrading-from-claude-hud) to claude-gauge.
|
|
389
126
|
|
|
390
|
-
|
|
391
|
-
| --- | --- |
|
|
392
|
-
| `default` | Usage from dark green to deep red, context in cyan, yellow and red, details in grey. |
|
|
393
|
-
| `mono` | No colour: every part in the terminal's own text colour. |
|
|
394
|
-
| `high-contrast` | The terminal's bright colours, with details in white rather than grey, for dim screens and low vision. |
|
|
395
|
-
| `pastel` | Soft 256-colour tones, on the same green-to-red usage scale. |
|
|
127
|
+
## What the bars show
|
|
396
128
|
|
|
397
|
-
The
|
|
129
|
+
The status line shows these parts by default:
|
|
398
130
|
|
|
399
|
-
|
|
131
|
+
| Part | Example | Shows |
|
|
132
|
+
| --- | --- | --- |
|
|
133
|
+
| `ctx` | `ctx 43% ▓▓░░░ 86.0k` | How much of the context window is in use. |
|
|
134
|
+
| `5h` | `5h 9% ░░┃░░ → 14:10` | Your 5-hour usage, and the time the window resets. |
|
|
135
|
+
| `7d` | `7d 41% ▓▓░┃░ → 3d` | Your weekly usage, and the days until it resets. |
|
|
136
|
+
| `time` | `11:10` | The local time. |
|
|
137
|
+
| `duration` | `1h12m` | How long the session has run. |
|
|
138
|
+
| `repo` | `jv-k/claude-gauge` | The repository, or the folder name. |
|
|
139
|
+
| `branch` | `⎇ main* ↑1` | The git branch. `*` means changes, and `↑1` means one commit ahead of the remote. |
|
|
140
|
+
| `model` | `Opus 5.5` | The model. |
|
|
141
|
+
| `effort` | `effort high` | The reasoning effort. |
|
|
400
142
|
|
|
401
|
-
|
|
143
|
+
The pace marker `┃` shows how much of the window has passed. Its colour shows where your usage goes at the current pace. Green stays well under the limit. Red and purple go over it.
|
|
402
144
|
|
|
403
|
-
|
|
145
|
+
Other parts show the tools and subagents in use, todos, git changes, pull requests, the cost per day and week, memory use and more.
|
|
404
146
|
|
|
405
|
-
|
|
147
|
+
> [!TIP]
|
|
148
|
+
> The reference describes [all 40 parts](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md#what-the-bars-show), with what each one shows and when.
|
|
406
149
|
|
|
407
|
-
|
|
150
|
+
## Customise
|
|
408
151
|
|
|
409
|
-
|
|
152
|
+
Each bar takes switches in its `command` in your settings. `configure` writes them for you. Two examples:
|
|
410
153
|
|
|
411
154
|
```text
|
|
412
155
|
--show 5h,7d
|
|
@@ -414,50 +157,6 @@ Only your usage, on one row:
|
|
|
414
157
|
5h 9% ░░┃░░ → 14:10 │ 7d 41% ▓▓░┃░ → 3d
|
|
415
158
|
```
|
|
416
159
|
|
|
417
|
-
Usage and context in 10-cell bars, without pace markers:
|
|
418
|
-
|
|
419
|
-
```text
|
|
420
|
-
--show ctx,5h,7d --segments 10 --no-pace
|
|
421
|
-
|
|
422
|
-
ctx 43% ▓▓▓▓░░░░░░ 86.0k │ 5h 9% ▓░░░░░░░░░ → 14:10 │ 7d 41% ▓▓▓▓░░░░░░ → 3d
|
|
423
|
-
```
|
|
424
|
-
|
|
425
|
-
As short as it gets: no labels, no bars, the 12-hour clock:
|
|
426
|
-
|
|
427
|
-
```text
|
|
428
|
-
--show ctx,5h,7d,model --no-labels --no-bars --12h
|
|
429
|
-
|
|
430
|
-
43% 86.0k │ 9% → 02:10 pm │ 41% → 3d │ Opus 5.5
|
|
431
|
-
```
|
|
432
|
-
|
|
433
|
-
Narrow terminals, with `--compact`:
|
|
434
|
-
|
|
435
|
-
```text
|
|
436
|
-
--show ctx,5h,7d --show repo,branch,model,effort --compact
|
|
437
|
-
|
|
438
|
-
c 43% ▓▓░░░ 86.0k│5h 9% ░░┃░░ → 14:10│7d 41% ▓▓░┃░ → 3d
|
|
439
|
-
jv-k/claude-gauge│⎇ main│Opus 5.5│eff high
|
|
440
|
-
```
|
|
441
|
-
|
|
442
|
-
The model and effort at the right edge of a 72-column terminal, with `--right`:
|
|
443
|
-
|
|
444
|
-
```text
|
|
445
|
-
--show ctx,5h,7d --show repo,branch,model,effort --right model,effort
|
|
446
|
-
|
|
447
|
-
ctx 43% ▓▓░░░ 86.0k │ 5h 9% ░░┃░░ → 14:10 │ 7d 41% ▓▓░┃░ → 3d
|
|
448
|
-
jv-k/claude-gauge │ ⎇ main Opus 5.5 │ effort high
|
|
449
|
-
```
|
|
450
|
-
|
|
451
|
-
Usage and context in the pastel theme, with bars of your own characters:
|
|
452
|
-
|
|
453
|
-
```text
|
|
454
|
-
--show ctx,5h,7d --theme pastel --bar-filled █ --bar-empty ·
|
|
455
|
-
|
|
456
|
-
ctx 43% ██··· 86.0k │ 5h 9% ··┃·· → 14:10 │ 7d 41% ██·┃· → 3d
|
|
457
|
-
```
|
|
458
|
-
|
|
459
|
-
Three rows for pull-request work:
|
|
460
|
-
|
|
461
160
|
```text
|
|
462
161
|
--show ctx,5h,7d --show repo,branch,pr,lines --show model,effort,cost,cache
|
|
463
162
|
|
|
@@ -466,154 +165,24 @@ jv-k/claude-gauge │ ⎇ main │ #12 approved │ +156 −23
|
|
|
466
165
|
Opus 5.5 │ effort high │ $1.23 │ cache 91% warm
|
|
467
166
|
```
|
|
468
167
|
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
Claude Code reruns a status line when something happens in the session, such as a new message. While a session sits idle, `duration` and the cache's warm or cold state can fall behind. To rerun the status line on a timer as well, add `refreshInterval`, in seconds, next to the command:
|
|
472
|
-
|
|
473
|
-
```json
|
|
474
|
-
"statusLine": {
|
|
475
|
-
"type": "command",
|
|
476
|
-
"command": "node ~/.claude/claude-gauge/dist/statusline.js",
|
|
477
|
-
"refreshInterval": 60
|
|
478
|
-
}
|
|
479
|
-
```
|
|
168
|
+
Each `--show` is one row.
|
|
480
169
|
|
|
481
|
-
|
|
170
|
+
> [!TIP]
|
|
171
|
+
> The reference lists [every switch](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md#options), the four [themes](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md#themes) and [more examples](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md#examples).
|
|
482
172
|
|
|
483
|
-
|
|
484
|
-
| --- | --- |
|
|
485
|
-
| `--show <parts>` | The parts to show, in the order given, separated by commas. Parts: `time`, `req`, `out`, `cache`, `ctx`. Default: all of them, in that order. |
|
|
486
|
-
| `--segments <5\|10>` | Cells in the context bar. Default: 5. Any other value gives 5. |
|
|
487
|
-
| `--window <size>` | The context window size, for example `200k` or `1m`. |
|
|
488
|
-
| `--latest` | Prints the line for the calling session, instead of reading a hook payload. See [In VS Code and the desktop app](#in-vs-code-and-the-desktop-app). |
|
|
489
|
-
| `--instruct` | As a SessionStart hook: in the VS Code extension and the desktop app, prints an instruction that has Claude end each reply with the `--latest` line; in the terminal CLI, prints nothing. The other switches pass through to the command it names. See [In VS Code and the desktop app](#in-vs-code-and-the-desktop-app). |
|
|
173
|
+
## Full reference
|
|
490
174
|
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
```json
|
|
494
|
-
"command": "node ~/.claude/claude-gauge/dist/tokenline.js --window 1m"
|
|
495
|
-
```
|
|
496
|
-
|
|
497
|
-
Unknown switches and part names are ignored, so a typo never breaks your status line or your turn. If `--show` names no known part, the line shows every part.
|
|
498
|
-
|
|
499
|
-
## Update
|
|
500
|
-
|
|
501
|
-
As a plugin, claude-gauge updates with `/plugin`, from the **Marketplaces** tab, or with `claude plugin update claude-gauge@claude-gauge` in your shell. The next new session runs the new version, with no setup. Auto-update is off for marketplaces other than Anthropic's, and the **Marketplaces** tab can turn it on.
|
|
502
|
-
|
|
503
|
-
From npm, run `update` from the newest version:
|
|
504
|
-
|
|
505
|
-
```sh
|
|
506
|
-
npx @jv-k/claude-gauge@latest update
|
|
507
|
-
```
|
|
508
|
-
|
|
509
|
-
It copies the new scripts over the old ones in `~/.claude/claude-gauge/runtime/` and keeps your switches, so the next render runs the new version. After a global install, run `npm install -g @jv-k/claude-gauge@latest`, then `claude-gauge update`.
|
|
510
|
-
|
|
511
|
-
From a clone:
|
|
512
|
-
|
|
513
|
-
```sh
|
|
514
|
-
git -C ~/.claude/claude-gauge pull
|
|
515
|
-
```
|
|
516
|
-
|
|
517
|
-
If your settings still name `~/.claude/claude-gauge/statusline.js` or `tokenline.js` from before the scripts moved into `dist/`, change each `command` to the `dist/` path shown in [By hand](#by-hand).
|
|
518
|
-
|
|
519
|
-
## Uninstall
|
|
520
|
-
|
|
521
|
-
As a plugin, run `/claude-gauge:uninstall`, then `/plugin uninstall claude-gauge@claude-gauge`. To remove the launcher and the saved usage figures too, delete `~/.claude/claude-gauge`.
|
|
522
|
-
|
|
523
|
-
From npm, run:
|
|
524
|
-
|
|
525
|
-
```sh
|
|
526
|
-
npx @jv-k/claude-gauge uninstall
|
|
527
|
-
```
|
|
528
|
-
|
|
529
|
-
It takes the status line, the token line and any `--instruct` hooks out of your settings, and puts back the status line that setup replaced. The scripts stay in `~/.claude/claude-gauge/runtime/`: delete `~/.claude/claude-gauge` to remove them, with the saved usage figures. After a global install, also run `npm uninstall -g @jv-k/claude-gauge`.
|
|
530
|
-
|
|
531
|
-
From a clone, remove the `statusLine`, `Stop` and `SessionStart` entries that name claude-gauge from `~/.claude/settings.json`. Then delete the folder:
|
|
532
|
-
|
|
533
|
-
```sh
|
|
534
|
-
rm -rf ~/.claude/claude-gauge
|
|
535
|
-
```
|
|
536
|
-
|
|
537
|
-
## Coming from claude-hud
|
|
538
|
-
|
|
539
|
-
claude-gauge has parts for claude-hud's main options, listed in the table below. It also has an npm route, a token line for each turn, theme presets, and an uninstall that puts your old status line back.
|
|
540
|
-
|
|
541
|
-
One setup command makes the switch. Install the plugin as in [As a Claude Code plugin](#as-a-claude-code-plugin), then run its setup:
|
|
542
|
-
|
|
543
|
-
```text
|
|
544
|
-
/claude-gauge:setup
|
|
545
|
-
```
|
|
546
|
-
|
|
547
|
-
Or, from a terminal:
|
|
548
|
-
|
|
549
|
-
```sh
|
|
550
|
-
npx @jv-k/claude-gauge setup
|
|
551
|
-
```
|
|
552
|
-
|
|
553
|
-
Setup finds claude-hud's status line in your settings, shows it to you, and asks before it replaces it. It saves claude-hud's command, so `/claude-gauge:uninstall` or `claude-gauge uninstall` puts it back. claude-hud's command runs a launcher that prints nothing once the claude-hud plugin is uninstalled, so keep claude-hud installed until you are sure that you will not go back.
|
|
554
|
-
|
|
555
|
-
Setup does not read claude-hud's `config.json`. claude-gauge has no configuration file: each choice is a part named in `--show`, or a switch, in the bar's `command` in your settings. Each repeated `--show` is one row, and the parts show in the order you name them. This table gives the claude-gauge part or switch for claude-hud's main options, as claude-hud's README listed them on 2026-10-09:
|
|
556
|
-
|
|
557
|
-
| claude-hud option | claude-gauge |
|
|
558
|
-
| --- | --- |
|
|
559
|
-
| `elementOrder`, `display.mergeGroups` | The parts in each `--show`, in order. Repeat `--show` for more rows. |
|
|
560
|
-
| `lineLayout`: `compact` | All the parts in one `--show`. `--compact` also takes the spaces out round `│` and shortens the labels. |
|
|
561
|
-
| `display.rightAlign` | `--right <parts>` |
|
|
562
|
-
| `display.showModel`, `display.showProvider` | `model`, with the provider after it when requests do not go to the Anthropic API. |
|
|
563
|
-
| `display.showEffortLevel` | `effort` |
|
|
564
|
-
| `display.showProject`, `pathLevels` | `repo` for owner/name, or `dir` for the folder name. |
|
|
565
|
-
| `display.showContextBar`, `display.contextValue` | `ctx`, which shows the percentage, a bar and the token count. `--no-bars` drops every bar. |
|
|
566
|
-
| `display.showUsage`, `display.usageBarEnabled` | `5h` and `7d`. `--no-bars` drops the bars. |
|
|
567
|
-
| `display.usagePace` | The pace marker `┃` on the `5h` and `7d` bars, on by default. `--no-pace` drops it. |
|
|
568
|
-
| `display.showModelScopedUsage` | `models`, and `limit` for a window at 100%. |
|
|
569
|
-
| `display.timeFormat` | `5h` always shows its reset as a time, and `7d` as days, after `→`. `--no-reset` drops the resets. |
|
|
570
|
-
| `display.hourCycle` | `--12h` for the 12-hour clock. The default is 24-hour. |
|
|
571
|
-
| `gitStatus.enabled`, `gitStatus.showDirty`, `gitStatus.showAheadBehind` | `branch`, which always shows `*` for changes and `↑n ↓n` against its upstream. |
|
|
572
|
-
| `gitStatus.showFileStats` | `git`: `!2 +1 ✘1 ?3` |
|
|
573
|
-
| `gitStatus.showWorktree` | `worktree`. `branch` names the worktree too. |
|
|
574
|
-
| `display.showTools` | `tools` |
|
|
575
|
-
| `display.showAgents` | `agents` |
|
|
576
|
-
| `display.showTodos` | `todos` |
|
|
577
|
-
| `display.showSkills`, `display.showMcp` | `skills`, which shows the skills and then the MCP servers. |
|
|
578
|
-
| `display.showConfigCounts` | `env` |
|
|
579
|
-
| `display.showAuth`, `display.showAuthUser` | `plan` |
|
|
580
|
-
| `display.showCost` | `cost` |
|
|
581
|
-
| `display.showDailyCost` | `today` |
|
|
582
|
-
| `display.showWeeklyCost` | `week`, which counts from Monday rather than from the start of the 7-day window. |
|
|
583
|
-
| `display.showDuration` | `duration` |
|
|
584
|
-
| `display.showSpeed` | `speed` |
|
|
585
|
-
| `display.showSessionName` | `name` |
|
|
586
|
-
| `display.showOutputStyle` | `style` |
|
|
587
|
-
| `display.showLastResponseAt` | `reply` |
|
|
588
|
-
| `display.showCompactions` | `compactions` |
|
|
589
|
-
| `display.showClaudeCodeVersion` | `version` |
|
|
590
|
-
| `display.showMemoryUsage` | `ram` |
|
|
591
|
-
| `display.showPromptCache`, `display.showCacheHitRate` | `cache`: the hit ratio and whether the cache is warm. |
|
|
592
|
-
| `display.customLine` | `text`, with `--text <text>`. |
|
|
593
|
-
| `--extra-cmd` | `command`, with `--command <command>`. See [Memory, text and command](#memory-text-and-command). |
|
|
594
|
-
| `colors.*` | `--theme <name>` for every part at once, and `--color <part>=<colour>` for one part. |
|
|
595
|
-
| `colors.barFilled`, `colors.barEmpty` | `--bar-filled <char>`, `--bar-empty <char>` |
|
|
596
|
-
| `refreshInterval` in `settings.json` | The same, next to claude-gauge's command. See [Keeping time-based parts fresh](#keeping-time-based-parts-fresh). |
|
|
597
|
-
|
|
598
|
-
Among claude-hud's other options, these have no claude-gauge equivalent: `language`, `jjStatus.*`, `display.showAddedDirs`, `display.modelOverride`, `display.modelFormat`, `display.effortFormat`, `display.usageValue`, `display.showResetLabel`, `display.showSessionTokens`, `display.showAdvisor`, the thresholds that hide a part until it reaches a value (`display.usageThreshold`, `display.sevenDayThreshold`, `display.environmentThreshold`), and the external usage files (`display.externalUsagePath`, `display.externalUsageWritePath`). claude-gauge's parts show whenever a `--show` names them and they have something to report.
|
|
599
|
-
|
|
600
|
-
## Development
|
|
601
|
-
|
|
602
|
-
[CONTRIBUTING.md](CONTRIBUTING.md) has the setup, the tests, the rules for a change, and the branch and commit conventions.
|
|
603
|
-
|
|
604
|
-
Both lines are TypeScript modules in `src/`, built to the self-contained Node.js files in `dist/` that the settings entries above run. The `claude-gauge` command in `src/cli.ts` builds to `dist/cli.js`. A clone of `main` works without a build, because the `dist` workflow commits the build to `main` after each merge. [Bun](https://bun.sh) runs the sources directly, with the same output as the build: `bun src/statusline.ts`.
|
|
605
|
-
|
|
606
|
-
To try the status line by hand, pipe it a sample of the JSON that Claude Code sends:
|
|
607
|
-
|
|
608
|
-
```sh
|
|
609
|
-
echo '{"model":{"display_name":"Opus"},"workspace":{"current_dir":"'"$PWD"'"},"context_window":{"used_percentage":25}}' | node dist/statusline.js
|
|
610
|
-
```
|
|
175
|
+
[docs/reference.md](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md) has everything this page leaves out:
|
|
611
176
|
|
|
612
|
-
|
|
177
|
+
- [Every status line part](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md#what-the-bars-show), and the [token line's parts](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md#token-line)
|
|
178
|
+
- [Every switch](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md#options), the [themes](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md#themes), [colours and bar characters](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md#colours-and-bar-characters), and [examples](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md#examples)
|
|
179
|
+
- [Other ways to install](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md#install): with a Claude prompt, or by hand from a clone
|
|
180
|
+
- [Update](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md#update) and [uninstall](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md#uninstall) for each install route
|
|
181
|
+
- [The claude-hud option map](https://github.com/jv-k/claude-gauge/blob/main/docs/reference.md#upgrading-from-claude-hud)
|
|
613
182
|
|
|
614
|
-
|
|
183
|
+
## Contributing
|
|
615
184
|
|
|
616
|
-
|
|
185
|
+
[CONTRIBUTING.md](CONTRIBUTING.md) gives the setup, the tests and the rules for a change. [RELEASING.md](RELEASING.md) gives the release steps.
|
|
617
186
|
|
|
618
187
|
## Star history
|
|
619
188
|
|
package/dist/cli.js
CHANGED
|
@@ -30,6 +30,7 @@ const settings_1 = require("./settings");
|
|
|
30
30
|
const settings_file_1 = require("./settings-file");
|
|
31
31
|
const wizard_1 = require("./wizard");
|
|
32
32
|
const statusline_1 = require("./statusline");
|
|
33
|
+
const wordmark_1 = require("./wordmark");
|
|
33
34
|
const USAGE = `Usage: claude-gauge <setup | configure | uninstall | update> [switches]
|
|
34
35
|
|
|
35
36
|
setup add the status line and the token line to Claude Code's settings
|
|
@@ -51,6 +52,12 @@ parts you want, and show the status line after each answer.
|
|
|
51
52
|
The bars' switches are in README.md, under Options. The settings file is
|
|
52
53
|
$CLAUDE_CONFIG_DIR/settings.json, else ~/.claude/settings.json.
|
|
53
54
|
`;
|
|
55
|
+
// The wordmark and a blank line, in colour when `stream` takes colour. The
|
|
56
|
+
// usage and the questions start with it. Scripts and the plugin's slash
|
|
57
|
+
// commands run the commands with switches, and those print no wordmark.
|
|
58
|
+
const banner = (stream) => `${(0, wordmark_1.wordmark)((0, wordmark_1.colorEnabled)(stream))}\n`;
|
|
59
|
+
// The usage, under the wordmark, for `stream`.
|
|
60
|
+
const usage = (stream) => banner(stream) + USAGE;
|
|
54
61
|
// A mistake in the command line: exit 2, with the usage.
|
|
55
62
|
class UsageError extends Error {
|
|
56
63
|
}
|
|
@@ -281,6 +288,7 @@ const starWithGh = () => (0, node_child_process_1.spawnSync)('gh', ['api', '--me
|
|
|
281
288
|
async function interactive(command, replace) {
|
|
282
289
|
const io = terminalIo();
|
|
283
290
|
try {
|
|
291
|
+
io.write(banner(process.stdout));
|
|
284
292
|
const file = settingsFile();
|
|
285
293
|
const { settings } = (0, settings_file_1.readSettings)(file);
|
|
286
294
|
const current = settings.statusLine;
|
|
@@ -358,9 +366,14 @@ function update() {
|
|
|
358
366
|
}
|
|
359
367
|
async function main(argv) {
|
|
360
368
|
try {
|
|
369
|
+
// A bare claude-gauge gets the usage alone, as a mistake: exit 2.
|
|
370
|
+
if (!argv.length) {
|
|
371
|
+
process.stderr.write(usage(process.stderr));
|
|
372
|
+
return 2;
|
|
373
|
+
}
|
|
361
374
|
const args = parseArgs(argv);
|
|
362
375
|
if (args.help) {
|
|
363
|
-
process.stdout.write(
|
|
376
|
+
process.stdout.write(usage(process.stdout));
|
|
364
377
|
return 0;
|
|
365
378
|
}
|
|
366
379
|
if (!args.command)
|
|
@@ -383,7 +396,7 @@ async function main(argv) {
|
|
|
383
396
|
}
|
|
384
397
|
catch (err) {
|
|
385
398
|
if (err instanceof UsageError) {
|
|
386
|
-
process.stderr.write(`claude-gauge: ${err.message}\n\n${
|
|
399
|
+
process.stderr.write(`claude-gauge: ${err.message}\n\n${usage(process.stderr)}`);
|
|
387
400
|
return 2;
|
|
388
401
|
}
|
|
389
402
|
process.stderr.write(`claude-gauge: ${err.message}\n`);
|
package/dist/statusline.js
CHANGED
|
@@ -49,7 +49,7 @@ const node_crypto_1 = require("node:crypto");
|
|
|
49
49
|
const node_url_1 = require("node:url");
|
|
50
50
|
// Every status line part, by the name --show takes. The default parts come
|
|
51
51
|
// first, in the order their rows show them; the order of the rest is the
|
|
52
|
-
//
|
|
52
|
+
// reference's (docs/reference.md).
|
|
53
53
|
const partRegistry = {
|
|
54
54
|
ctx: { description: 'context window in use: percentage, bar and token count', row: 0, build: ({ data, config, theme }) => contextPart(data, config, theme) },
|
|
55
55
|
'5h': { description: '5-hour usage, with pace marker and reset time', row: 0, build: ({ data, config, theme, nowMs }) => windowPart('5h', data, config, theme, nowMs) },
|
package/dist/wordmark.js
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
// The claude-gauge wordmark, which the CLI prints above its usage and at the
|
|
3
|
+
// start of the setup and configure questions. It is figlet's "future" font,
|
|
4
|
+
// as jv-k/deslopper draws its own, kept here as text so the CLI needs no
|
|
5
|
+
// figlet: three rows of one 3-cell chunk per character of "claude-gauge".
|
|
6
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
7
|
+
exports.wordmark = wordmark;
|
|
8
|
+
exports.colorEnabled = colorEnabled;
|
|
9
|
+
const WORDMARK = [
|
|
10
|
+
['┏━╸', '╻ ', '┏━┓', '╻ ╻', '╺┳┓', '┏━╸', ' ', '┏━╸', '┏━┓', '╻ ╻', '┏━╸', '┏━╸'],
|
|
11
|
+
['┃ ', '┃ ', '┣━┫', '┃ ┃', ' ┃┃', '┣╸ ', '╺━╸', '┃╺┓', '┣━┫', '┃ ┃', '┃╺┓', '┣╸ '],
|
|
12
|
+
['┗━╸', '┗━╸', '╹ ╹', '┗━┛', '╺┻┛', '┗━╸', ' ', '┗━┛', '╹ ╹', '┗━┛', '┗━┛', '┗━╸'],
|
|
13
|
+
];
|
|
14
|
+
// A 256-colour number for each chunk: deslopper's rainbow widened to the 11
|
|
15
|
+
// letters, with 27 for blue because 21 reads poorly on a dark background, and
|
|
16
|
+
// grey for the hyphen.
|
|
17
|
+
const COLORS = [196, 202, 208, 214, 226, 118, 244, 82, 39, 27, 93, 163];
|
|
18
|
+
const RESET = '\x1b[0m';
|
|
19
|
+
// Whether to colour what goes to `stream`, in deslopper's order: a non-empty
|
|
20
|
+
// NO_COLOR turns colour off, a FORCE_COLOR or CLICOLOR_FORCE that is neither
|
|
21
|
+
// empty nor 0 turns it on, and otherwise only a terminal gets colour.
|
|
22
|
+
function colorEnabled(stream, env = process.env) {
|
|
23
|
+
if (env.NO_COLOR)
|
|
24
|
+
return false;
|
|
25
|
+
if (['CLICOLOR_FORCE', 'FORCE_COLOR'].some((name) => env[name] && env[name] !== '0'))
|
|
26
|
+
return true;
|
|
27
|
+
return stream.isTTY === true;
|
|
28
|
+
}
|
|
29
|
+
// The wordmark's three rows, each ending in a newline. In colour each chunk
|
|
30
|
+
// starts with its colour code and each row ends with a reset.
|
|
31
|
+
function wordmark(color) {
|
|
32
|
+
const row = (chunks) => color ? chunks.map((chunk, i) => `\x1b[38;5;${COLORS[i]}m${chunk}`).join('') + RESET : chunks.join('');
|
|
33
|
+
return WORDMARK.map((chunks) => row(chunks) + '\n').join('');
|
|
34
|
+
}
|
package/package.json
CHANGED