KurulumInstall Reach seviyeleriReach levels
L0 v0.3.0 source

limit-watch

Subscription kullanım limitlerini ekranda tutan bir Claude Code Mod'u. Bir Claude subscription'ı 5 saatlik ve 7 günlük bir limit taşır, bir Claude gateway ise bir spend limit ekleyebilir. Claude Code bunları yalnız bir limit dolmaya yakınken bir uyarıda gösterir. limit-watch bunları session boyunca gösterir, her reset'e kadar geri sayar, bugünkü hızın bir limiti ne zaman dolduracağını tahmin eder ve bir limit %80 ile %95'i geçtiğinde bir uyarı yazar.

Ne gösterir

Prompt'un altında bir status line, her turdan sonra ve her 60 saniyede bir güncellenir:

limit-watch: 5h 9%, reset in 2h 36m · 7d 15%, reset in 5d 10h · measuring the pace

Son kısım şunlardan biridir:

  • 5h hits 100% in ~1h 40m: bugünkü hızda bu limit reset'inden önce dolar. Birden fazla limit doluyorsa ilki adlandırılır.
  • no limit fills before its reset: her limit, bugünkü hız onu doldurmadan önce reset olur.
  • measuring the pace: hiçbir limitin henüz yeterince uzun bir aralıkta örneği yok.
  • 5h limit reached: bir limit %100'de.

Bir API key session'ı hiçbir limit bildirmez. Status line o zaman no usage limits reported yet der. Yeni bir session da Claude bir kere cevap verene kadar bunu gösterir.

sidebar içinde bir section, sidebar açıkken o status line'ın yerine: aynı parçalar, limit başına bir satır (%80 altında yeşil, %80'den itibaren sarı, %95'ten itibaren kırmızı, pane'deki bar ile aynı adımlar) ve altlarında hız satırı; bu satır bir limit zaten dolduğunda kırmızı, bir limit reset'inden önce dolduğunda sarı, hiçbiri dolmadığında yeşil ve hız hâlâ ölçülürken soluk olur. Status line o sırada temizlenir. Sidebar kapalıyken ya da o mod kurulu değilken status line yukarıdaki gibi kalır.

/limit-watch ile açılıp kapanan bir pane, limit başına bir blok ile:

5-hour limit · 9% used
██████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
resets 22:40, in 2h 36m
pace +4.2%/h over the last 38m

Bar pane'in genişliğini doldurur. %80 altında yeşil, %80'den itibaren sarı ve %95'ten itibaren kırmızıdır. Hız ölçülürken hız satırı ne kadar daha örnek gerektiğini söyler.

Transcript'te bir uyarı, bir limit %80'i geçtiğinde ve %95'i geçtiğinde yeniden:

limit-watch: 5-hour limit passed 80% (now 82%), resets 22:40 (in 1h 5m)

Her uyarı limit cycle'ı başına bir kere gelir. Aynı cycle'daki yeni bir session onu tekrarlamaz. Limit reset olduktan sonra uyarılar yeniden gelir.

Sayılar nasıl oluşur

  • $.session.usage() her limiti { kind, percentUsed, resetsAt } olarak verir, son API cevabından okunur. limit-watch bunu session başlangıcında, her ana döngü turundan sonra, interaktif bir session'da her 60 saniyede bir ve /limit-watch pane'i açtığında okur.
  • Her okuma bir örnektir ({ at, percent }) ve $.store içinde tutulur, böylece bir restart hızı korur.
  • Hız, yakın bir aralığın ilk ve son örneği arasındaki yüzde değişimidir, saat başına. Aralık 5 saatlik limit için son bir saat, 7 günlük ve spend limitleri için son 24 saattir; böylece hız bugün nasıl çalıştığınızı izler, cycle'ın başında nasıl çalıştığınızı değil.
  • Bir hız yalnız örnekleri en az 10 dakika (5 saatlik limit) ya da 2 saat (7 günlük ve spend limitleri) yayıldığında gösterilir. Daha kısa bir aralık, yüzdenin tek bir adımının ikiye katlayabileceği bir hız verir.
  • Status line'ın son kısmı %100'e kalan süre için (100 - percent) / pace kullanır. O süreden önce reset olan bir limit dolan sayılmaz.
  • Yeni bir cycle, resetsAt 5 dakikadan fazla kaydığında başlar; resetsAt taşımayan bir limit içinse yüzde yarım puandan fazla düştüğünde. Yeni bir cycle o limitin örneklerini ve uyarılarını temizler.
  • Bilinmeyen biçimde saklanmış bir değer tek bir log satırıyla bildirilir ve örnekler baştan başlar.

Kurulum

claude plugin marketplace add KilimcininKorOglu/claude-code-mods
claude plugin install limit-watch@kilimcininkoroglu-mods

Function hook'lar early access. Flag olmadan hiçbir şey yüklenmez:

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude

Tek bir session için yerel bir checkout'tan yükleyin:

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir plugins/limit-watch

Flag'i kalıcı yapmak için ~/.claude/settings.json dosyasına ekleyin:

{ "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1" } }

Kurulumdan sonra

  1. Claude Code'u yeniden başlatın.
  2. Bir Claude subscription ile giriş yapın (/login). Bir API key üzerindeki session hiçbir limit bildirmez ve status line no usage limits reported yet olarak kalır.
  3. Bir prompt gönderin. Limitler son API cevabından gelir, yani status line ilk cevaptan sonra dolar. Pane'i /limit-watch ile açın.

Nereye uzanır

Claude Code 2.1.278 üzerinde claude plugin validate ile doğrulandı:

❯ ./register.tsx hooks: session.start, turn.complete, command.run{command=limits}, ui.render{component=Pane}
❯ ./register.tsx calls: $.clock.every, $.clock.now, $.command.register, $.session.usage (via sample), $.sidebar.set (via toSidebar), $.store.get, $.store.set (via sample), $.ui.close, $.ui.invalidate (via sample), $.ui.log, $.ui.open, $.ui.panes, $.ui.resolve, $.ui.status (via sample)

Reach L0, çizer ve hatırlar.

1. Okur:     $.session.usage'ın rate-limit window'larını (kind, kullanılan yüzde, reset zamanı); dört hook'unun event payload'larını
2. Çalıştırır: hiçbir şey; interaktif bir session'da bir 60 saniyelik timer
3. Gönderir: makineden hiçbir şey çıkmaz
4. Saklar:   her limitin örneklerini ve uyarılmış seviyelerini $.store içinde, limit başına en fazla 1500 örnek
5. Düşman girdi: tek dış girdi kullanım rakamlarıdır; bilinmeyen biçimde saklanmış bir değer bildirilir ve değiştirilir, hiçbir zaman güvenilmez

Sınırlar

  • Yeni bir session, Claude bir kere cevap verene kadar okuma taşımaz, çünkü rakamlar son API cevabından gelir.
  • 7 günlük limit ancak 2 saatlik örnekten sonra hız gösterir.
  • Bir spend limit %100'ü geçebilir. Bar dolu yerde durur; yüzde durmaz.
  • /limit-watch tek bir pane'i açıp kapar. İkinci çalıştırma onu kapatır.

Geliştirme

make install     # eslint, typescript-eslint, typescript
make lint        # complexity limiti 10, üstünde build'i düşürür
make typecheck   # /plugin-types ile üretilen .claude/types/ gerekir
make validate
make test        # claude plugin test

limit-watch

A Claude Code Mod that keeps the subscription usage limits on screen. A Claude subscription has a 5-hour limit and a 7-day limit, and a Claude gateway can add a spend limit. Claude Code shows them only in a notice when a limit is almost full. limit-watch shows them for the whole session, counts down to each reset, forecasts when the current pace fills a limit, and logs a warning when a limit passes 80% and 95%.

What it shows

A status line under the prompt, updated after every turn and every 60 seconds:

limit-watch: 5h 9%, reset in 2h 36m · 7d 15%, reset in 5d 10h · measuring the pace

The last part is one of these:

  • 5h hits 100% in ~1h 40m: at the current pace this limit fills before its reset. When more than one limit fills, the first one is named.
  • no limit fills before its reset: every limit resets before the current pace fills it.
  • measuring the pace: no limit has samples over a long enough span yet.
  • 5h limit reached: a limit is at 100%.

An API key session reports no limits. The status line then reads no usage limits reported yet. A new session also shows this until Claude answers once.

A section in the sidebar instead of that status line while the sidebar is open: the same parts, one line per limit (green under 80%, yellow from 80%, red from 95%, the same steps as the pane's bar) and the pace line under them, itself red when a limit is already reached, yellow when one fills before its reset, green when none does and faint while the pace is still measured. The status line is cleared then. With the sidebar closed, or without that mod installed, the status line stays as above.

A pane, opened and closed with /limit-watch, with one block per limit:

5-hour limit · 9% used
██████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
resets 22:40, in 2h 36m
pace +4.2%/h over the last 38m

The bar fills the width of the pane. It is green below 80%, yellow from 80% and red from 95%. While the pace is measured, the pace line says how much more sampling it needs.

A warning in the transcript when a limit passes 80% and again when it passes 95%:

limit-watch: 5-hour limit passed 80% (now 82%), resets 22:40 (in 1h 5m)

Each warning comes once per limit cycle. A new session in the same cycle does not repeat it. After the limit resets, the warnings come again.

How the numbers are made

  • $.session.usage() gives each limit as { kind, percentUsed, resetsAt }, read from the last API response. limit-watch reads it at session start, after every main-loop turn, every 60 seconds in an interactive session, and when /limit-watch opens the pane.
  • Every reading is one sample { at, percent }, kept in $.store so that a restart keeps the pace.
  • The pace is the change in percent between the first and the last sample of a recent span, per hour. The span is the last hour for the 5-hour limit and the last 24 hours for the 7-day and spend limits, so the pace follows how you work now and not how you worked earlier in the cycle.
  • A pace is shown only when its samples span at least 10 minutes (5-hour limit) or 2 hours (7-day and spend limits). A shorter span gives a pace that one step of the percentage can double.
  • The status line tail uses (100 - percent) / pace as the time to 100%. A limit that resets before that time does not count as filling.
  • A new cycle starts when resetsAt moves by more than 5 minutes, or, for a limit without resetsAt, when the percentage falls by more than half a point. A new cycle clears the samples and the warnings of that limit.
  • A stored value of an unknown shape is reported with one log line, and the samples start over.

Install

claude plugin marketplace add KilimcininKorOglu/claude-code-mods
claude plugin install limit-watch@kilimcininkoroglu-mods

Function hooks are early access. Nothing loads without the flag:

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude

Load it from a local checkout for one session:

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir plugins/limit-watch

To keep the flag on, add this to ~/.claude/settings.json:

{ "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1" } }

After installing

  1. Restart Claude Code.
  2. Sign in with a Claude subscription (/login). A session on an API key reports no limits, and the status line stays at no usage limits reported yet.
  3. Send one prompt. The limits come from the last API response, so the status line fills after the first answer. Open the pane with /limit-watch.

What it can reach

Validated with claude plugin validate on Claude Code 2.1.278:

❯ ./register.tsx hooks: session.start, turn.complete, command.run{command=limits}, ui.render{component=Pane}
❯ ./register.tsx calls: $.clock.every, $.clock.now, $.command.register, $.session.usage (via sample), $.sidebar.set (via toSidebar), $.store.get, $.store.set (via sample), $.ui.close, $.ui.invalidate (via sample), $.ui.log, $.ui.open, $.ui.panes, $.ui.resolve, $.ui.status (via sample)

Reach L0, draws and remembers.

1. Reads:    the rate-limit windows of $.session.usage (kind, percent used, reset time); the event payloads of its four hooks
2. Runs:     nothing; one 60 second timer in an interactive session
3. Sends:    nothing leaves the machine
4. Persists: the samples and the warned levels of each limit in $.store, at most 1500 samples per limit
5. Hostile input: the only outside input is the usage figures; a stored value of an unknown shape is reported and replaced, never trusted

Limits

  • A new session has no reading until Claude answers once, because the figures come from the last API response.
  • The 7-day limit shows a pace only after 2 hours of samples.
  • A spend limit can pass 100%. The bar stops at full; the percentage does not.
  • /limit-watch toggles one pane. The second run closes it.

Development

make install     # eslint, typescript-eslint, typescript
make lint        # complexity limit 10, fails the build above it
make typecheck   # needs .claude/types/ from /plugin-types
make validate
make test        # claude plugin test