limitcast 0.14.0 → 0.16.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/LICENSE +21 -95
- package/README.md +61 -48
- package/bin/limitcast.mjs +103 -212
- package/package.json +2 -2
- package/src/guard.mjs +10 -2
- package/src/insights.mjs +127 -0
- package/src/install.mjs +6 -14
- package/src/license.mjs +2 -1
- package/src/memory.mjs +122 -0
- package/src/notify.mjs +1 -2
- package/src/onboarding.mjs +46 -0
- package/src/pilot.mjs +92 -0
- package/src/results.mjs +31 -15
- package/src/trim.mjs +11 -5
- package/src/value.mjs +37 -11
package/LICENSE
CHANGED
|
@@ -1,95 +1,21 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
the features or functionality of the software.
|
|
23
|
-
|
|
24
|
-
You may not move, change, disable, or circumvent the license key functionality
|
|
25
|
-
in the software, and you may not remove or obscure any functionality in the
|
|
26
|
-
software that is protected by the license key.
|
|
27
|
-
|
|
28
|
-
You may not alter, remove, or obscure any licensing, copyright, or other notices
|
|
29
|
-
of the licensor in the software. Any use of the licensor’s trademarks is subject
|
|
30
|
-
to applicable law.
|
|
31
|
-
|
|
32
|
-
## Patents
|
|
33
|
-
|
|
34
|
-
The licensor grants you a license, under any patent claims the licensor can
|
|
35
|
-
license, or becomes able to license, to make, have made, use, sell, offer for
|
|
36
|
-
sale, import and have imported the software, in each case subject to the
|
|
37
|
-
limitations and conditions in this license. This license does not cover any
|
|
38
|
-
patent claims that you cause to be infringed by modifications or additions to
|
|
39
|
-
the software. If you or your company make any written claim that the software
|
|
40
|
-
infringes or contributes to infringement of any patent, your patent license for
|
|
41
|
-
the software granted under these terms ends immediately. If your company makes
|
|
42
|
-
such a claim, your patent license ends immediately for work on behalf of your
|
|
43
|
-
company.
|
|
44
|
-
|
|
45
|
-
## Notices
|
|
46
|
-
|
|
47
|
-
You must ensure that anyone who gets a copy of any part of the software from you
|
|
48
|
-
also gets a copy of these terms.
|
|
49
|
-
|
|
50
|
-
If you modify the software, you must include in any modified copies of the
|
|
51
|
-
software prominent notices stating that you have modified the software.
|
|
52
|
-
|
|
53
|
-
## No Other Rights
|
|
54
|
-
|
|
55
|
-
These terms do not imply any licenses other than those expressly granted in
|
|
56
|
-
these terms.
|
|
57
|
-
|
|
58
|
-
## Termination
|
|
59
|
-
|
|
60
|
-
If you use the software in violation of these terms, such use is not licensed,
|
|
61
|
-
and your licenses will automatically terminate. If the licensor provides you
|
|
62
|
-
with a notice of your violation, and you cease all violation of this license no
|
|
63
|
-
later than 30 days after you receive that notice, your licenses will be
|
|
64
|
-
reinstated retroactively. However, if you violate these terms after such
|
|
65
|
-
reinstatement, any additional violation of these terms will cause your licenses
|
|
66
|
-
to terminate automatically and permanently.
|
|
67
|
-
|
|
68
|
-
## No Liability
|
|
69
|
-
|
|
70
|
-
*As far as the law allows, the software comes as is, without any warranty or
|
|
71
|
-
condition, and the licensor will not be liable to you for any damages arising
|
|
72
|
-
out of these terms or the use or nature of the software, under any kind of
|
|
73
|
-
legal claim.*
|
|
74
|
-
|
|
75
|
-
## Definitions
|
|
76
|
-
|
|
77
|
-
The **licensor** is the entity offering these terms, and the **software** is the
|
|
78
|
-
software the licensor makes available under these terms, including any portion
|
|
79
|
-
of it.
|
|
80
|
-
|
|
81
|
-
**you** refers to the individual or entity agreeing to these terms.
|
|
82
|
-
|
|
83
|
-
**your company** is any legal entity, sole proprietorship, or other kind of
|
|
84
|
-
organization that you work for, plus all organizations that have control over,
|
|
85
|
-
are under the control of, or are under common control with that
|
|
86
|
-
organization. **control** means ownership of substantially all the assets of an
|
|
87
|
-
entity, or the power to direct its management and policies by vote, contract, or
|
|
88
|
-
otherwise. Control can be direct or indirect.
|
|
89
|
-
|
|
90
|
-
**your licenses** are all the licenses granted to you for the software under
|
|
91
|
-
these terms.
|
|
92
|
-
|
|
93
|
-
**use** means anything you do with the software requiring one of your licenses.
|
|
94
|
-
|
|
95
|
-
**trademark** means trademarks, service marks, and similar rights.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Sam Stull
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,30 +1,30 @@
|
|
|
1
1
|
# limitcast
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Get more work from your AI coding plan. Forecast usage limits, control subagent burn, and trim unused starting context across Claude Code, Codex and Grok. Runs locally, with keep-lists, backups and undo.
|
|
4
4
|
|
|
5
5
|

|
|
6
6
|
|
|
7
7
|
```
|
|
8
8
|
$ limitcast trim
|
|
9
|
-
|
|
9
|
+
Your recorded Claude Code sessions start at 102.7k tokens before your first message.
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## Estimated removable context: ~6.2k tokens per session (6% of your starting context)
|
|
12
12
|
- Disable 9 MCP servers you haven't used in 14 days (~0.9k): postman, context7, ...
|
|
13
13
|
- Hide 66 skills from the model (~5.3k): dataviz, block-kit, ...
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
- **Trim advisor:** measures your latest session's starting context from its transcript (SessionStart hook output, MCP server instructions and tool names, skills, agents, instruction files). Free shows the total and how much of it you haven't used;
|
|
17
|
-
- **Subagent guard
|
|
18
|
-
- **Subagent receipts and budgets
|
|
19
|
-
- **Cold-cache warning
|
|
20
|
-
- **Large tool-output notice (
|
|
21
|
-
- **Limit-change alert
|
|
16
|
+
- **Trim advisor:** measures your latest session's starting context from its transcript (SessionStart hook output, MCP server instructions and tool names, skills, agents, instruction files). Free shows the total and how much of it you haven't used; Names each item and what it costs, and `trim --apply` makes the cuts for you (reversible). `trim --codex` does the same for Codex (AGENTS.md, MCP servers).
|
|
17
|
+
- **Subagent guard** for Claude Code and Codex: blocks a new subagent when that tool's own window is on pace to run out before it resets, and while a Claude window is tight runs new subagents on Sonnet instead of your main model. Free installs get a preview that never acts and shows what it would have done.
|
|
18
|
+
- **Subagent receipts and budgets:** when a subagent finishes you see what it cost: "that Explore subagent used ≈2.1% of your 5-hour window (34 calls)". Before a new one starts you see what that kind has cost you so far: "Explore subagents have cost you a median ≈1.2% (max ≈3.6%) of a 5-hour window over 7 runs" (once there are 3 priced runs, and only when a typical run is over 1% of a window or the window is NEAR). `limitcast budget subagents 15` holds new subagents once they have used 15% of the current window.
|
|
19
|
+
- **Cold-cache warning:** after a long pause (60 min, `LIMITCAST_CACHE_MINUTES`) the prompt cache has expired and your next message re-sends the whole context as new tokens. limitcast holds that first message once and tells you what it will cost; send it again to go ahead, or `/compact` first.
|
|
20
|
+
- **Large tool-output notice (with `install --alerts`):** when one tool result is very large (about 20k tokens or more; `LIMITCAST_TOOL_TOKENS` changes that), you see it once per tool per session with what to ask for next time: "that HubSpot get_crm_objects result was ≈25k tokens. Next time: ask for fewer fields and a smaller limit". It is shown to you, never to the model, and `limitcast report --why` lists the same advice for the sources that cost you most.
|
|
21
|
+
- **Limit-change alert:** limitcast re-measures how many tokens move your meter by 1% every day and notifies you when that shifts by 15% or more, so you know when the limit itself changed.
|
|
22
22
|
- **Daily allowance (free):** today's even share of each weekly window, so you can pace the week: `7d 41% · today 6% left`.
|
|
23
|
-
- **
|
|
24
|
-
- **
|
|
25
|
-
- **Burn report
|
|
23
|
+
- **More controls:** desktop notifications (`limitcast notify on`), also to your phone (`notify ntfy <topic>`) or a Slack/Discord webhook (`notify webhook <url>`), run a job after the reset (`limitcast after-reset -- …`), a pointer to your other account when this one is near its limit, a `/compact` nudge in long sessions, and an HTML dashboard (`limitcast results --html`).
|
|
24
|
+
- **Capacity report:** `limitcast results` separates recorded consumption by provider, applied protection decisions and historical previews, and estimated Claude context tokens not re-sent relative to a recorded baseline. Calls crossing a week boundary are counted in the period they happened. It also shows lifetime context estimates, forecast replay and next steps. Unknown evidence stays unavailable; controls are not converted into invented saved tokens.
|
|
25
|
+
- **Burn report:** Claude Code, Codex and Grok tokens by day, project, model and session.
|
|
26
26
|
- **Runout forecast (free):** burn rate and the clock time each window runs out.
|
|
27
|
-
- **Local only.** Reads the limit readings Claude Code passes to your status line and the logs Claude Code, Codex and Grok already write. No logins, and your usage data never leaves your machine.
|
|
27
|
+
- **Local only.** Reads the limit readings Claude Code passes to your status line and the logs Claude Code, Codex and Grok already write. No logins, and your usage data never leaves your machine. No license validation or payment-service connection is required. If you turn on phone or webhook notifications (off by default), each notification's text goes to the service you chose (ntfy.sh or your webhook) and nothing else.
|
|
28
28
|
|
|
29
29
|
| | Claude Code | Codex | Grok |
|
|
30
30
|
|---|---|---|---|
|
|
@@ -35,19 +35,23 @@ Every Claude Code session starts at 102.7k tokens before your first message.
|
|
|
35
35
|
|
|
36
36
|
Requires Node 20+ on macOS or Linux.
|
|
37
37
|
|
|
38
|
+
## Upgrading to 0.15.0
|
|
39
|
+
|
|
40
|
+
All features are now free. A guard previously installed in preview mode will enforce its forecast and enabled budgets after this update. It only holds new spawns; existing agents continue. Use `LIMITCAST_ALLOW=1` to override, or `limitcast uninstall` to remove the integration. Existing budgets, notification preferences, keep-lists and license files are left untouched. No activation or trial is needed.
|
|
41
|
+
|
|
38
42
|
## Install
|
|
39
43
|
|
|
40
44
|
```sh
|
|
41
|
-
npm install -g limitcast # or: brew trust samstull9007/limitcast && brew install samstull9007/limitcast/limitcast
|
|
45
|
+
npm install -g https://github.com/SamStull9007/limitcast/releases/download/v0.16.0/limitcast-0.16.0.tgz # or: brew trust samstull9007/limitcast && brew install samstull9007/limitcast/limitcast
|
|
46
|
+
limitcast onboard # read-only: setup checks and a first useful result
|
|
42
47
|
limitcast install # free: status-line recorder
|
|
43
|
-
limitcast trial # Pro free for 7 days, no card (or: limitcast activate <key>)
|
|
44
48
|
limitcast install --guard # also the subagent guard (free: preview only)
|
|
45
49
|
limitcast doctor
|
|
46
50
|
```
|
|
47
51
|
|
|
48
|
-
In Claude Code you can also add the plugin, for `/limitcast:status`, `/limitcast:results` and `/limitcast:
|
|
52
|
+
In Claude Code you can also add the plugin, for `/limitcast:status`, `/limitcast:results`, `/limitcast:trim`, `/limitcast:memory-audit` and `/limitcast:memory-split`: `/plugin marketplace add SamStull9007/limitcast`, then `/plugin install limitcast@limitcast`. The status-line recorder still comes from `limitcast install`.
|
|
49
53
|
|
|
50
|
-
`install` backs up `~/.claude/settings.json` and wraps your existing status line: it looks exactly the same, and the limitcast line (for example `limitcast: 5h 14% · 7d 18% · today 9% left`) goes on the line under it. `--guard` adds the subagent guard (
|
|
54
|
+
`install` backs up `~/.claude/settings.json` and wraps your existing status line: it looks exactly the same, and the limitcast line (for example `limitcast: 5h 14% · 7d 18% · today 9% left`) goes on the line under it. `--guard` adds the subagent guard (all features are free). Restart Claude Code to load it. `limitcast uninstall` puts everything back.
|
|
51
55
|
|
|
52
56
|
**Codex:** forecasts and reports need no setup (`~/.codex/sessions`, or `$CODEX_HOME/sessions`). With `--guard`, `install` also appends the guard to `~/.codex/hooks.json`, after your existing hooks so the ones you've already trusted keep their trust. Codex runs a new hook only once you approve it: start Codex and accept it. `limitcast doctor` shows whether it's trusted.
|
|
53
57
|
|
|
@@ -57,48 +61,57 @@ In Claude Code you can also add the plugin, for `/limitcast:status`, `/limitcast
|
|
|
57
61
|
|
|
58
62
|
| Command | |
|
|
59
63
|
|---|---|
|
|
60
|
-
| `limitcast
|
|
61
|
-
| `limitcast
|
|
62
|
-
| `limitcast trim --
|
|
63
|
-
| `limitcast
|
|
64
|
-
| `limitcast notify
|
|
65
|
-
| `limitcast
|
|
66
|
-
| `limitcast budget
|
|
67
|
-
| `limitcast
|
|
68
|
-
| `limitcast
|
|
69
|
-
| `limitcast
|
|
70
|
-
| `limitcast
|
|
71
|
-
| `limitcast
|
|
64
|
+
| `limitcast onboard` | Read-only guided setup: local tools, readiness, free feature availability, personal context finding, keep/undo/override controls and next commands. Never changes settings |
|
|
65
|
+
| `limitcast status [--json]` | Used, burn rate, runout time and reset for each window, and today's share of each weekly one. When a window is on pace to run out, one line names the one that binds first and where else there is room ("You'll hit Claude 7d first (Thu 14:00). Grok 5h still has $38."). also lists your other Claude accounts |
|
|
66
|
+
| `limitcast trim --codex [--apply / --undo]` | Codex: AGENTS.md size and MCP servers in `~/.codex/config.toml` you haven't used. names them and turns them off (`enabled = false`; `--undo` restores the file exactly) |
|
|
67
|
+
| `limitcast trim --grok [--apply / --undo]` | Grok: system prompt and tool-definition size, and MCP servers in `~/.grok/config.toml` you haven't used. names them and turns them off (`enabled = false`; `--undo` restores the file exactly) |
|
|
68
|
+
| `limitcast notify on/off/test` | A desktop notification when a Claude window turns NEAR, AT_RISK or HIT, and when it resets after a HIT. On macOS they come from a tiny limitcast notifier app, listed as "limitcast" in System Settings → Notifications |
|
|
69
|
+
| `limitcast notify ntfy <topic or https URL>` / `notify webhook <https URL>` | Also send every notification to your phone through [ntfy](https://ntfy.sh) (install the app, subscribe to the topic) or to a Slack or Discord incoming webhook. `off` removes it. Sent in the background, so no hook waits on the network |
|
|
70
|
+
| `limitcast budget subagents <percent>` / `off` | Once subagents have used that share of the current 5-hour window, the guard holds new ones until it resets. Priced from your own readings (needs about a day of use first) |
|
|
71
|
+
| `limitcast budget today on` / `off` | The `today N% left` pace of a weekly window becomes an action. With `notify on` you get one notification a day at 80% of today's share. With `budget today on` the guard also holds new subagents once today's share is used up, until local midnight. Off by default; a window already at 100% is left to the tool; `LIMITCAST_ALLOW=1` overrides. Applied holds appear in `results` |
|
|
72
|
+
| `limitcast subagent-model <type> <sonnet\|opus\|haiku\|claude-id\|grok-id>` / `off` | Run new subagents of that type (for example `Explore` or `explore`) on that model, unless the spawn names a model itself. Grok ids also write `[subagents.models]` in `~/.grok/config.toml` (restart Grok). Without arguments it lists what is pinned and the types you ran in the last 30 days. Needs `install --guard`; `results` counts the subagents it moved |
|
|
73
|
+
| `limitcast plan [--days N]`, `limitcast plan set <pro\|max5\|max20>` / `off` | Does your Claude plan fit how much you use? From a long-lived record of the peak of every 5-hour and weekly window (kept 120 days; it starts when you install this version) it says whether you reached your limits often enough to look at the next plan, or used so little that a smaller one would have fit, with the monthly price difference, and shows what your Claude Code tokens would cost at API list prices. Tell it your plan first with `plan set`. Plan prices (Pro $20, Max 5x $100, Max 20x $200) and the 5x / 20x multipliers are from claude.com/pricing (2026-10-26; the Max 20x price was not on that page: change any price in `prices.json`, `{"plans": {"max20": 200}}`). It assumes weekly limits scale like the 5-hour limit, and it cannot see extra-usage spend |
|
|
74
|
+
| `limitcast budget grok <usd>` / `off` / `7d <usd>` | Dollar cap for Grok's aligned 5-hour window (optional 7-day cap). Turns Grok spend into a % so `status` can forecast runout and the guard can block `spawn_subagent` |
|
|
75
|
+
| `limitcast after-reset [--src claude/codex] [--window 5h/7d] [--detach] -- <cmd>` | Wait for the window to reset, then run the command |
|
|
76
|
+
| `limitcast results --html [--out FILE]` | Results, current windows and the burn report on one page, opened in your browser |
|
|
72
77
|
| `limitcast install [--guard] [--alerts]` / `uninstall` | Wire into Claude Code / restore your settings |
|
|
73
|
-
| `limitcast doctor [--fix]` | Check the setup, data freshness,
|
|
74
|
-
| `limitcast
|
|
75
|
-
| `limitcast report [--days N] [--out FILE]` |
|
|
76
|
-
| `limitcast report --why [--days N]` |
|
|
77
|
-
| `limitcast report --jobs [--days N]` |
|
|
78
|
-
| `limitcast trim [--days N] [--share]` | Measured starting context of your latest session and how much you haven't used in N days (default 7).
|
|
79
|
-
| `limitcast saved` |
|
|
80
|
-
| `limitcast trim --apply` / `--undo` |
|
|
78
|
+
| `limitcast doctor [--fix]` | Check the setup, data freshness, this project's auto-memory index (see `memory`), and that Claude Code, Codex and Grok logs are still in a format limitcast reads. Also runs daily in the background and flags problems in the status line (the memory line only shows when you run `doctor` yourself). `--fix` re-installs with the current Node (after a Node upgrade) |
|
|
79
|
+
| `limitcast memory [dir]` | Check this project's auto-memory folder (`~/.claude/projects/<project>/memory`): how much of `MEMORY.md` fits in what Claude Code loads each session (the first 200 lines or 25 KB; anything past that is never read), broken links, topic files nothing links to, and files over 150 lines. Read-only. In Claude Code, `/limitcast:memory-audit` takes it from there (stale, contradictory and unlinked notes) and `/limitcast:memory-split` splits an oversized file into a short hub plus topic files |
|
|
80
|
+
| `limitcast report [--days N] [--out FILE]` | Tokens by tool, day, project, model and session; subagent share; and the API-equivalent cost: what the tokens would cost at the API's list prices (Claude and Grok models; a subscription is not billed this way). Prices are in the code as of 2026-10-26; add or change a model in `~/.local/state/limitcast/prices.json` (`{"models": {"claude-opus-4-1": {"input": 15, "output": 75}}}`, dollars per million tokens) |
|
|
81
|
+
| `limitcast report --why [--days N]` | Where your new tokens went: subagents, session starts, cache rebuilds after idle, tool results by tool, model output, and the largest single steps (Claude Code only) |
|
|
82
|
+
| `limitcast report --jobs [--days N]` | The scheduled (headless) jobs that spend the most tokens just starting: runs, average start, share of all new tokens, and how to launch a job leaner (Claude Code only) |
|
|
83
|
+
| `limitcast trim [--days N] [--share]` | Measured starting context of your latest session and how much you haven't used in N days (default 7). names each item. `--share`: totals only, no names, safe to post |
|
|
84
|
+
| `limitcast saved` | How much the part of your starting context you control has dropped since limitcast first measured it, times your sessions since |
|
|
85
|
+
| `limitcast trim --apply` / `--undo` | Hide the unused skills from the model and turn off the unused MCP servers for that project, through Claude Code's own settings. Backed up; `--undo` reverses exactly what it changed |
|
|
81
86
|
| `limitcast trim keep <name>[,<name>]` | Servers or skills no `trim --apply` (Claude, Codex or Grok) ever turns off or hides, e.g. `trim keep ego-browser`. `--remove <name>` drops one; no name lists them. Free to set; `trim` shows what it would keep |
|
|
82
|
-
| `limitcast results [--days N] [--share]` |
|
|
83
|
-
| `install --alerts` |
|
|
84
|
-
| `limitcast
|
|
85
|
-
| `limitcast deactivate` | Free this computer so the key can be used on another one |
|
|
86
|
-
| `limitcast license` | Show the license and re-check it with Polar now |
|
|
87
|
+
| `limitcast results [--days N] [--share]` | Capacity report plus forecast evidence: each limit window that reached 100% and how far ahead limitcast warned, and what the guard blocked and whether that window then ran out. adds baseline context estimates. `--share`: voluntary totals only; nothing uploads automatically |
|
|
88
|
+
| `install --alerts` | A SessionStart hook that tells you (never the model) when your starting context grew ~1k+ tokens, and what grew, plus a one-line weekly summary of what limitcast did |
|
|
89
|
+
| `limitcast license` | Show the free MIT license status; no network call |
|
|
87
90
|
|
|
88
|
-
### Subagent guard
|
|
91
|
+
### Subagent guard
|
|
89
92
|
|
|
90
|
-
|
|
93
|
+
The guard is free for everyone and acts when installed with `--guard`. Blocks a new subagent only when the spawning tool's window is on pace to run out before it resets, within 30 minutes (`LIMITCAST_GUARD_MINUTES`). A window already at 100% is left to Claude Code, so extra usage keeps working. `LIMITCAST_ALLOW=1` overrides. If the guard itself fails, it allows the call.
|
|
91
94
|
|
|
92
|
-
`install --guard` also adds two more hooks. A SubagentStop hook prices each finished subagent from its own transcript and
|
|
95
|
+
`install --guard` also adds two more hooks. A SubagentStop hook prices each finished subagent from its own transcript and shows you the receipt (never the model); `limitcast budget` and `results` use the same record. A UserPromptSubmit hook holds the first message after the prompt cache expired, once per pause, when the session re-sends 100k+ tokens; messages from background agents and `/compact` or `/clear` are never held. Installed `--guard` before 0.11? Run `limitcast doctor --fix` to add them.
|
|
93
96
|
|
|
94
97
|
## How the forecast works
|
|
95
98
|
|
|
96
99
|
Each limit reading is saved to `~/.local/state/limitcast/samples.jsonl` when it changes (kept 8 days). The burn rate is the least-squares slope of percent used over the last hour of the current window, and the runout time is where that line reaches 100%. Windows of a day or more (the weekly one) use the average pace over the last full day, idle time included, unless the last hour's pace runs them out within the hour. **AT_RISK** means that happens before the reset; **NEAR** means 95% or more is used. Claude sessions of the same account share one history (matched by window reset times, and usage that only rises), so two accounts used in parallel never mix.
|
|
97
100
|
|
|
98
|
-
##
|
|
101
|
+
## Free and open source
|
|
102
|
+
|
|
103
|
+
All features are free. No account, subscription, card, license key, trial or device limit. Install the current version and enable only the controls you want. Earlier `trial`, `activate` and `deactivate` commands remain harmless compatibility messages and do not contact a billing service.
|
|
104
|
+
|
|
105
|
+
Created by **Sam Stull**. The project and its history remain available as a portfolio and community tool. Feedback and contributions are welcome through [GitHub](https://github.com/SamStull9007/limitcast).
|
|
106
|
+
|
|
107
|
+
## Measuring recurring value
|
|
108
|
+
|
|
109
|
+
`results` uses exact activity timestamps for its rolling period and UTC calendar dates for active-day counts. New input/cache writes, cached reads and model output are separate. Context reductions are estimated at characters / 4 against the first recorded baseline; different projects or manual configuration changes can affect that baseline. This is not measured causal savings or a lower subscription bill. Legacy records without call timestamps remain readable but are excluded from period estimates until their transcripts can be rescanned. Codex/Grok context savings remain unavailable. A previous-period estimate requires two complete observed periods.
|
|
110
|
+
|
|
111
|
+
Protection events retain the tier at decision time. Host operation IDs deduplicate retries when supplied; older/unidentified events remain labeled attempts. Forecast history is replayed from readings and does not prove that a notification was delivered. Controls cannot establish how many interruptions were prevented.
|
|
99
112
|
|
|
100
|
-
|
|
113
|
+
For a small consenting pilot, see [the pilot protocol](docs/pilot.md) and [dated market assessment](docs/market-positioning.md). From a repository checkout, `node scripts/pilot-metrics.mjs participants.json` aggregates operator-recorded activation, eligible day-7/day-30 retention and verified renewals locally; it does not recruit people or collect telemetry.
|
|
101
114
|
|
|
102
115
|
## License
|
|
103
116
|
|
|
104
|
-
[
|
|
117
|
+
[MIT License](LICENSE). Copyright (c) 2026 Sam Stull. Use, modify and redistribute the software, including commercially, with the required copyright and permission notices.
|