Skip to content
Back to search

budgetline

MarketplaceWorks with Claude CodeGitHubIncomplete

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/nibforge--budgetline/badge.svg)](/listings/nibforge--budgetline)

HTML

<a href="/listings/nibforge--budgetline"><img src="/api/listings/nibforge--budgetline/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.

Requires **Node.js 20 or later on your `PATH`** (the plugin's hooks and commands run `node`).

As a Claude Code plugin

Inside Claude Code:

/plugin marketplace add nibforge/budgetline
/plugin install budgetline@budgetline

Then, in a terminal, add the usage-limit status line (a plugin cannot set it; this prints the `settings.json` entry and installs it after asking you):

npx budgetline setup-statusline --write

Plugin commands:

- `/budgetline:estimate <task description>` (or `/estimate` when no other plugin uses the name): estimates only; it does not start the task. - `/budgetline:budget <tokens> [--warn <tokens>|80%]` sets a budget for the session you are in (`60k`, `1.5M` work too); `/budgetline:budget clear` removes it.

The plugin does not put a `budgetline` command on your `PATH`. In a terminal use `npx budgetline …` (or `npm install -g budgetline`). The examples below write `budgetline …` for short.

With npx (no plugin)

npx budgetline history
npx budgetline estimate "add input validation to src/api/users.ts"

Commands

budgetline history  [--project <text>] [--since <YYYY-MM-DD>] [--limit N] [--json] [--show-prompts] [--show-titles]
budgetline session  [--id <session id prefix>] [--json]
budgetline estimate "<task description>" [--cwd <dir>] [--session <id>] [--json]
budgetline statusline install | uninstall | status
budgetline setup-statusline [--write [--yes]]
budgetline hook enable | disable | status
budgetline guard enable [--budget N] [--warn N|80%] [--context P] [--window N|auto] | disable | status
budgetline guard session --budget N [--warn N|80%] [--session <id>] | --clear

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
  1. {
  2. "name": "budgetline",
  3. "owner": {
  4. "name": "budgetline contributors"
  5. },
  6. "plugins": [
  7. {
  8. "name": "budgetline",
  9. "source": "./",
  10. "version": "0.3.1",
  11. "description": "See where your Claude Code budget goes — and stop hitting your limits."
  12. }
  13. ],
  14. "metadata": {
  15. "description": "budgetline: see where your Claude Code budget goes — and stop hitting your limits."
  16. }
  17. }
README.md · README · 248 lines
  1. # budgetline
  2. **See where your Claude Code budget goes — and stop hitting your limits.**
  3. `budgetline` reads your local Claude Code history (nothing leaves your machine) and shows
  4. what has been expensive and why, keeps your usage-limit % in sight, warns you before a
  5. costly prompt or a session that has grown too long, and estimates new tasks with an honest
  6. range that measures its own accuracy.
  7. ![budgetline history and the status line](https://raw.githubusercontent.com/nibforge/budgetline/main/docs/demo.gif)
  8. ## What it does
  9. 1. **`budgetline history`: where the budget goes.** Tokens (input, cache writes, cache
  10. reads, output) and cost per session, plus **What's expensive**: your top tasks and the
  11. patterns behind the spend (long loops, sessions carrying a big context, subagents,
  12. cache rewrites), each with its share of your spend and a tip.
  13. 2. **Usage-limit % in your status line (optional).** `5h: 23% · 7d: 41% · $1.25 API value this session · Equiv 484k`.
  14. It wraps an existing status line instead of replacing it.
  15. 3. **A note on the first prompt of a session (opt-in).** If the task you start a session
  16. with looks expensive, a hook adds one line with its typical estimate. Follow-up messages
  17. never get a note. It never blocks. Details in [Prompt note](#prompt-note).
  18. 4. **Guard (opt-in): a session token budget and a context-full warning.** Delivered to
  19. Claude itself, so they also work during long autonomous runs. Over budget, Claude is told
  20. to finish the current step and propose a fresh session. It never blocks.
  21. 5. **`budgetline estimate "<task>"`: an estimate, not a promise.** Cost first, as a
  22. low / typical / high range from similar past tasks, the 3 closest past tasks so you can
  23. judge the match, and savings tips. Every estimate is checked against the task you
  24. actually run next, and **Accuracy so far** reports how often the range was right.
  25. ## Install
  26. Requires **Node.js 20 or later on your `PATH`** (the plugin's hooks and commands run `node`).
  27. ### As a Claude Code plugin
  28. Inside Claude Code:
  29. ```text
  30. /plugin marketplace add nibforge/budgetline
  31. /plugin install budgetline@budgetline
  32. ```
  33. Then, in a terminal, add the usage-limit status line (a plugin cannot set it; this prints
  34. the `settings.json` entry and installs it after asking you):
  35. ```sh
  36. npx budgetline setup-statusline --write
  37. ```
  38. Plugin commands:
  39. - `/budgetline:estimate <task description>` (or `/estimate` when no other plugin uses the
  40. name): estimates only; it does not start the task.
  41. - `/budgetline:budget <tokens> [--warn <tokens>|80%]` sets a budget for the session you are
  42. in (`60k`, `1.5M` work too); `/budgetline:budget clear` removes it.
  43. The plugin does not put a `budgetline` command on your `PATH`. In a terminal use
  44. `npx budgetline …` (or `npm install -g budgetline`). The examples below write
  45. `budgetline …` for short.
  46. ### With npx (no plugin)
  47. ```sh
  48. npx budgetline history
  49. npx budgetline estimate "add input validation to src/api/users.ts"
  50. ```
  51. ### Commands
  52. ```text
  53. budgetline history [--project <text>] [--since <YYYY-MM-DD>] [--limit N] [--json] [--show-prompts] [--show-titles]
  54. budgetline session [--id <session id prefix>] [--json]
  55. budgetline estimate "<task description>" [--cwd <dir>] [--session <id>] [--json]
  56. budgetline statusline install | uninstall | status
  57. budgetline setup-statusline [--write [--yes]]
  58. budgetline hook enable | disable | status
  59. budgetline guard enable [--budget N] [--warn N|80%] [--context P] [--window N|auto] | disable | status
  60. budgetline guard session --budget N [--warn N|80%] [--session <id>] | --clear
  61. ```
  62. ## Reading the numbers
  63. ### Equiv: one number for what you spend
  64. Claude Code bills four kinds of tokens at different prices. **Equiv** (equivalent tokens)
  65. weights each by its price relative to a plain input token, so one number tracks what you
  66. actually spend:
  67. | Token | Weight |
  68. |---|---|
  69. | Input | 1 |
  70. | Cache write | 1.25 (5 min) or 2 (1 h) |
  71. | Cache read | 0.1 |
  72. | Output | 5 |
  73. ### Why Cache R dominates
  74. The counter beside the spinner counts the output of the current turn. But **every request
  75. re-sends the whole conversation**: your prompt, the history, the tool results, the system
  76. prompt, CLAUDE.md and tool definitions. Prompt caching makes those re-reads cheap (0.1 each),
  77. but they happen on every turn and every tool round. In a long session the **Cache R** column
  78. is millions of tokens, and it is usually most of the Equiv. That is why a task that "looked
  79. like 200k tokens" scrolling by often costs about ten times more, and why long sessions and
  80. big contexts are the first things `history` points at.
  81. ### The $ figure on a Pro/Max plan
  82. The $ is the session cost Claude Code itself reports. On a plan you do not pay per token, so
  83. it is **API-equivalent value**: what the same work would cost on the API. What limits you
  84. is the **usage-limit %**, so once the status line has seen it, every view shows the % first.
  85. Without limit data (pay-as-you-go API), the $ is your real cost and comes first.
  86. ## Prompt note
  87. Off by default. `budgetline hook enable` turns it on; **`budgetline hook disable` turns it
  88. off** (`budgetline hook status` shows which). With the plugin, run them as
  89. `npx budgetline hook …`.
  90. - **Only the first prompt of a session** is estimated: the first one this hook sees for that
  91. session id, while the transcript has no reply yet. Enabling the hook mid-session or
  92. resuming a session does not count as a start, and follow-up messages never get a note.
  93. - It appears only when the typical estimate is above `hookThreshold` (500k equivalent
  94. tokens by default, in `config.json`).
  95. - It uses your similar past tasks as they are, **without the bias correction** that
  96. `estimate` applies: that correction was measured on whole sessions, not on one message.
  97. - With few or very different similar tasks it says so (`low confidence`) and gives the
  98. rough figure only, without calling the task big. `/budgetline:estimate <task>` shows the
  99. full range and savings tips.
  100. ## Guard
  101. ![The guard warning Claude about the session budget](https://raw.githubusercontent.com/nibforge/budgetline/main/docs/demo-guard.gif)
  102. Opt-in, off by default. Two independent warnings, delivered **to Claude itself** and shown
  103. to you:
  104. - **Session budget**, in Equiv. At the warning threshold Claude gets one line
  105. (`budgetline: session at 165k/200k tokens`). Over the budget, Claude is told not to start
  106. new work, to finish the current step, summarize the state and propose a fresh session with
  107. a continuation prompt.
  108. - **Context full**: the latest request against the model's window (70% by default). Claude
  109. is told that answer quality may degrade and to tell you so.
  110. ```sh
  111. budgetline guard enable # budget from your history (p75 of last 30 sessions; 2M fallback), warning at 80%
  112. budgetline guard enable --budget 2000000 --warn 80% --context 70 --window auto
  113. budgetline guard status
  114. budgetline guard disable
  115. budgetline guard session --budget 1200000 # this session only (from inside Claude Code)
  116. budgetline guard session --clear
  117. ```
  118. With the plugin, `/budgetline:budget 1.2M` sets the budget of the session you typed it in.
  119. A target written in your prompt is only text: the guard knows nothing about it until you
  120. set it this way. Each warning fires once per threshold; the over-budget instruction repeats.
  121. The guard runs on the plugin's `UserPromptSubmit` and `PostToolBatch` hooks, reads only what
  122. was appended to the transcripts since the last call, and stays silent if anything goes
  123. wrong. After `/clear` Claude Code starts a new session, so the counters start from zero.
  124. ## Usage-limit % (status line)
  125. Claude Code only shows your usage-limit percentages to the status line; they are not stored
  126. anywhere. `budgetline setup-statusline --write` installs a small wrapper that records one
  127. sample and then runs your original status line with the same input, so what you see does not
  128. change. With no status line of your own, it shows `5h: 23% · 7d: 41% · $1.25 API value this session · Equiv 484k`
  129. (with the guard on, `Equiv 484k/2M · ctx 37%`).
  130. ```sh
  131. budgetline setup-statusline # shows the entry; --write installs it (asks first)
  132. budgetline statusline status # samples collected and calibration
  133. budgetline statusline uninstall # puts your settings back exactly as they were
  134. ```
  135. The entry runs a launcher in the data folder that finds the current plugin install each
  136. time, so nothing needs redoing after an update. After about 10 samples and $1 of usage,
  137. `estimate` shows a 5-hour limit %. Several sessions at once make this less accurate, and the
  138. output says so.
  139. ## How the estimate works
  140. 1. A past **task** is one prompt plus all the responses until your next prompt (subagents
  141. included).
  142. 2. Tokens are combined into Equiv. Costs come from the real per-session cost Claude Code
  143. records; there is no bundled price table.
  144. 3. Tasks are classified as questions or changes, and only the same kind is compared.
  145. Similar tasks are found by keyword overlap (TF-IDF), same project ranked higher. The range
  146. is the 25th / 50th / 90th percentile of their spend. With fewer than 5 similar tasks, your
  147. overall distribution is used and flagged as low confidence.
  148. 4. Once 3 estimates have been checked against the task you ran next, new estimates are
  149. corrected by the measured bias, and say so.
  150. 5. **Base cost vs task cost.** Every call carries a fixed context (system prompt, tools,
  151. CLAUDE.md, plugins, skills, memory), measured from the first response of your recent
  152. sessions. The estimate shows it apart and suggests trimming it past 40k tokens.
  153. ## Privacy
  154. - **Nothing leaves your machine.** No server, no telemetry, no network calls.
  155. - It reads `~/.claude/projects` (or `$CLAUDE_CONFIG_DIR/projects`) read-only.
  156. - **Your prompt text is never shown or stored** unless you pass `--show-prompts`. Sessions
  157. are identified by a short id and the title Claude Code gave them.
  158. - Local data lives in `~/.budgetline` (or `$BUDGETLINE_DATA`), readable by you only (0700)
  159. on macOS and Linux: a per-task metrics index (keyword stems, no prompt text), status line
  160. samples (dropped after 30 days), past estimates (no task text), settings in `config.json`,
  161. the guard's per-session state and a backup of your `settings.json` if you installed the
  162. status line. Delete the folder to remove everything.
  163. - Upgrading from the old name (pre-budget): the first run moves `~/.pre-budget` to
  164. `~/.budgetline` when the new one does not exist yet.
  165. ## Verify it yourself
  166. Every view shows the same figures for a session. The $ is Claude Code's own
  167. `cost.total_cost_usd` (from the status line, or the `cost-state` line in the transcript);
  168. `budgetline` never prices a session itself when that figure exists, and when it has to
  169. estimate, the figure starts with `~`. `budgetline session` prints the current session in the
  170. status line's exact format, so you can compare them side by side.
  171. **On a plan with extra usage:** note your balance, work in one session on extra usage, run
  172. `budgetline session` and check that your balance went down by that $.
  173. **On the API:** use a fresh key or a quiet day, work in one session, run `budgetline session`
  174. and compare with the usage page of the Anthropic Console for that day.
  175. If your bill differs, the difference comes from Claude Code's figure, not from `budgetline`.
  176. ## Limitations
  177. - Estimates come from your own history. A new kind of task has no good comparison, and the
  178. output says so.
  179. - Keyword similarity is good at "same area of the code" and "same kind of work", not at
  180. judging how hard a task is.
  181. - Transcript formats are internal to Claude Code and can change; unknown lines are skipped.
  182. - **History only goes back as far as Claude Code keeps transcripts: 30 days by default.**
  183. To keep more, set `cleanupPeriodDays` in `~/.claude/settings.json`, e.g.
  184. `{"cleanupPeriodDays": 90}`. See the [settings reference](https://code.claude.com/docs/en/settings-reference#cleanupperioddays).
  185. - The usage-limit % needs the status line wrapper, and several sessions at once blur it.
  186. - On Windows, your original status line command runs through `cmd.exe`; one written for
  187. Git Bash may behave differently.
  188. ## Contributing
  189. Bug reports and pull requests are welcome; see [CONTRIBUTING](.github/CONTRIBUTING.md).
  190. `npm install`, then `npm run verify` (lint, types, tests and build). Change only `src/`
  191. and `tests/`: the maintainer rebuilds and commits `dist/cli.js`.
  192. ## License
  193. MIT, see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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