---
name: budzet
description: "Pokazuje ile limitu Claude Code zostalo i ile kosztuje biezaca sesja, w procentach limitu tygodniowego. Pozwala ustawic budzet na sesje i pilnuje go przez cala rozmowe. Use when the user says \"budżet\", \"ile mi zostało limitu\", \"ile zjadła ta sesja\", \"ustaw budżet sesji\", \"ile mam limitu\", \"sprawdź zużycie\", \"/budzet\", \"ile kosztuje ta rozmowa\", \"kalibruj budżet\"."
---

# Budżet sesji

Licznik zużycia limitu w **procentach limitu tygodniowego** — jednostce, którą pokazuje sam Claude Code.

## ZANIM COKOLWIEK ZROBISZ: sprawdź Pythona

Wtyczka jest napisana w Pythonie. Przy **pierwszym** użyciu w danej rozmowie uruchom:

```bash
python3 <katalog wtyczki>/skills/budzet/bin/budzet.py sprawdz
```

Na Windows zamiast `python3` wpisz `py -3`.

**Jeśli polecenie nie znajduje Pythona**, nie próbuj instalować go samodzielnie i nie kombinuj z obejściami. Przerwij i przeprowadź użytkownika przez instalację. Powiedz mu własnymi słowami mniej więcej to:

> Ta wtyczka pokazuje, ile limitu Claude Code zostało do resetu, ile kosztowała ta rozmowa i pozwala ustawić budżet na sesję — wtedy skracam odpowiedzi, zamiast przepalać limit. Żeby liczyć, potrzebuje Pythona, którego nie masz jeszcze na tym komputerze. To jednorazowa instalacja, ok. 3 minuty.

Potem podaj kroki dla jego systemu:

**Windows**
1. Wejdź na `https://www.python.org/downloads/` i pobierz instalator.
2. W pierwszym oknie instalatora **zaznacz „Add python.exe to PATH"** — bez tego nic nie zadziała.
3. Kliknij „Install Now", poczekaj, zamknij okno.
4. **Zamknij i otwórz Claude Code od nowa** — inaczej nie zobaczy nowego programu.

**macOS**
1. Otwórz Terminal.
2. Wklej `xcode-select --install` i potwierdź (albo zainstaluj z `https://www.python.org/downloads/`).
3. Uruchom Claude Code od nowa.

**Linux**
1. `sudo apt install python3` (Debian/Ubuntu) albo odpowiednik dla Twojej dystrybucji.
2. Uruchom Claude Code od nowa.

Po restarcie uruchom `sprawdz` jeszcze raz i pokaż wynik. Dopiero wtedy przechodź dalej.

Dopóki Pythona nie ma, licznik po prostu milczy — nic się nie psuje, żadna rozmowa nie jest blokowana.

## Pierwsze uruchomienie — czego się spodziewać

Zaraz po instalacji wtyczka **nie pokaże procentów**, tylko liczby tokenów („ta sesja 1,4 mln tokenów"). Tak ma być.

Powiedz o tym użytkownikowi od razu, zwykłymi słowami — inaczej uzna, że wtyczka jest zepsuta. Sens jest taki: żeby przeliczyć tokeny na procenty, wtyczka musi wiedzieć, ile tokenów zjada 1% limitu na tym koncie. Ta liczba jest inna dla różnych kont, więc wtyczka nie zgaduje — mierzy ją z pracy użytkownika. Dzieje się to samo, w tle. Procenty pojawią się, gdy zużycie tygodniowe wzrośnie o kolejne 3 punkty; przy codziennej pracy to dzień albo dwa.

Czego **nie** mów: „kurs tokeny → procent", „kalibracja", „stała zaszyta w kodzie", „inny plan taryfowy". To słownik autora wtyczki, nie użytkownika.

Czego **nie** każ robić: użytkownik nie musi wpisywać `/usage`, niczego odświeżać, uruchamiać kalibracji ani czekać na konkretny moment. Wtyczka zbiera dane sama przy zwykłej pracy.

## Co użytkownik może wpisać

Pokaż mu tę listę przy pierwszym kontakcie i za każdym razem, gdy pyta, co wtyczka potrafi:

| wpisuje | dostaje |
|---|---|
| `/budzet` | stan limitu i ustawienie budżetu na tę rozmowę |
| `/budzet 1` | od razu ustawia budżet tej rozmowy na 1% limitu (dowolna liczba, też ułamkowa: `/budzet 0.5`) |
| „ile mi zostało limitu" | ile procent limitu do końca tygodnia |
| „ile kosztowała ta rozmowa" | koszt bieżącej sesji |
| „ustaw budżet sesji na 1%" | od tej chwili pilnujesz budżetu i skracasz odpowiedzi, gdy się kończy |
| „zdejmij budżet" | koniec pilnowania |

Zdania działają w dowolnym brzmieniu — to nie są sztywne formuły.

## Skąd biorą się liczby

| liczba | źródło | dokładność |
|---|---|---|
| „zostało X% do resetu" | API Anthropic `/api/oauth/usage` (zapas: `~/.claude.json` → `cachedUsageUtilization`) | odczyt, nie szacunek — co do 1% |
| „ta sesja kosztowała Y%" | transkrypty `~/.claude/projects/**/*.jsonl` | dodawanie dokładne, przeliczenie na % przybliżone |
| „ta tura jest 3× droższa niż typowa" | te same transkrypty | dokładne — porównanie w tych samych jednostkach |

Jedyne przybliżenie w całym narzędziu to **kurs tokeny → procent**. Kalibruje się sam: dwa kolejne odczyty prawdziwego procentu dają parę przyrostową (przyrost procentu, tokeny między odczytami), a kurs to mediana z ostatnich ośmiu par. Gdy licznik i prawdziwy procent się rozjeżdżają — **wygrywa plik**.

Żadna stała nie jest zaszyta w kodzie. Kurs zależy od planu i aktywnych promocji, więc liczy się z danych tego, kto używa wtyczki. Do pierwszej pary narzędzie nie pokazuje procentów, tylko liczby względne.

Zmiana planu albo koniec promocji zeruje kalibrację — wtyczka odkłada stare pary do archiwum i liczy kurs od nowa. Plan sprawdza zapytaniem do Anthropica (`/api/oauth/profile`), nie z kopii w `~/.claude.json`: ta kopia potrafi zamarznąć na starej nazwie planu (29.08.2026 plik mówił `max_20x`, serwer `max_5x`). Gdy serwer nie odpowie, zostaje kopia z pliku — brak odpowiedzi to brak danych, nie zmiana planu.

## Polecenia

```bash
BIN=<katalog wtyczki>/skills/budzet/bin/budzet.py

python3 $BIN sprawdz                                   # autodiagnoza: co działa, czego brakuje
python3 $BIN status   --sid "$SID" --transcript "$T"   # limit, kalibracja, skala sesji, ta sesja
python3 $BIN ustaw 2.5 --sid "$SID"                    # budżet tej sesji: 2,5% limitu
python3 $BIN ustaw     --sid "$SID"                    # budżet = koszt typowej sesji (mediana)
python3 $BIN skasuj    --sid "$SID"                    # zdejmij budżet
python3 $BIN odswiez                                   # pobierz świeży odczyt limitu z API
python3 $BIN kalibruj                                  # dopisz parę pomiarową, przelicz kurs
python3 $BIN dokladnosc                                # zmierz własny błąd (walidacja krocząca)
python3 $BIN historia                                  # pary pomiarowe
python3 $BIN zdjecia                                   # dziennik odczytów limitu
```

Na Windows zamiast `python3` użyj `py -3`.

`dokladnosc` jest testem narzędzia na sobie samym: dla każdej pary przewiduje procent kursem policzonym wyłącznie z par **wcześniejszych** i porównuje z prawdziwym odczytem. Poniżej 10 porównań wynik jest oznaczany jako wstępny.

`SID` i ścieżkę transkryptu podaje hook automatycznie. Przy ręcznym wywołaniu skrypt sam bierze identyfikator ze zmiennej `CLAUDE_CODE_SESSION_ID`, a transkrypt wylicza z niego (`{sid}.jsonl`).

### Kilka otwartych okien Claude Code

Każde okno ma własną sesję i własny budżet — plik `~/.claude/state/budzet/budzet-<sid>.json`. Licznik wywołany w oknie zawsze pokazuje stan **tego** okna, bo identyfikator przychodzi ze zmiennej środowiskowej.

Plik `~/.claude/state/budzet/biezaca.json` jest jeden na cały system i nadpisuje go hook każdej sesji przy każdym prompcie — służy wyłącznie jako zapas dla wywołań spoza Claude Code (zwykły terminal, zadanie cykliczne). Tam podawaj `--sid` jawnie, inaczej trafisz w okno, w którym użytkownik pisał ostatnio.

## Jak reagować na linię budżetu

Hook wstrzykuje w każdej turze linię `[BUDZET: …]`. Traktuj ją jak twardą regułę:

| stan | zachowanie |
|---|---|
| budżet ustawiony, poniżej 70% | **TRYB OSZCZĘDNY od pierwszej tury** — sam wynik, bez preambuły, bez rekapitulacji, bez tabel poglądowych i nieproszonych przykładów |
| **KOŃCZY SIĘ** (≥70%) | krótsze odpowiedzi, bez tabel poglądowych i przykładów |
| **NA WYCZERPANIU** (≥90%) | bez agentów, procesów wieloagentowych i researchu; sam wynik |
| **PRZEKROCZONY** (≥100%) | jedno zdanie odpowiedzi; zaproponuj `/clear` albo podniesienie budżetu |
| sygnał drogiej tury | powiedz użytkownikowi wprost, że rozmowa zdrożała i `/clear` się opłaca, jeśli temat się zmienił |

Gdy budżet nie jest ustawiony, linia pokazuje tylko stan limitu i koszt sesji — bez nakazów.

## Przebieg `/budzet`

**Z liczbą** (`/budzet 1`, `/budzet 0.5`) — ustaw od razu przez `ustaw <liczba>`, potwierdź jedną linią. Nie pytaj o nic, użytkownik już zdecydował.

**Bez liczby** (`/budzet`):
1. Uruchom `status`. Pokaż użytkownikowi: ile zostało do resetu, jego skalę sesji (najtańsza / typowa / droga / najdroższa) i koszt bieżącej sesji.
2. Zapytaj o budżet na tę sesję, proponując medianę jako domyślną.
3. Ustaw przez `ustaw`. Potwierdź jedną linią.

## Ograniczenia — mów o nich wprost

To jest **szacunek zużycia, nie licznik**. Trzy ograniczenia są wbudowane w konstrukcję i nie znikną po żadnej kalibracji. Mów o nich wprost, zanim ktoś oprze na tych liczbach decyzję.

**1. Licznik widzi tylko pracę w konsoli, na tym komputerze.**
Praca przez przeglądarkę, aplikację, zadania w chmurze albo drugi komputer nie trafia do transkryptów — a trafia do limitu. Skutek: koszt sesji jest zaniżony, a kurs kalibracji zbudowany na zimnym starcie zaniżony razem z nim. Prawdziwy procent tygodniowy pochodzi z Claude Code i te braki uwzględnia, więc paski limitu są wiarygodne — zawodzi liczba „ta sesja X%".
Zmierzone 01.08.2026: kurs z zimnego startu 10,61 mln tokenów na 1%, kurs z pierwszej pary przyrostowej **12,54 mln** — 15% różnicy w tę stronę.

**2. Wagi tokenów to hipoteza przepisana z cennika interfejsu programistycznego, nie pomiar.**
`input 1.0 · cache_write 1.25 · cache_read 0.1 · output 5.0`. Nie wiadomo, czy limit subskrypcji nalicza tak samo (pewność 70%). Dopóki pracujesz podobnie, błąd wsiąka w kurs i nie widać go wcale. Wyjdzie przy zmianie charakteru pracy: tydzień długich rozmów z dużym czytaniem z pamięci podręcznej kontra tydzień krótkich zadań z dużym generowaniem dadzą ten sam wynik na liczniku i różny na limicie.

**3. Źródło prawdy ma rozdzielczość 1 punktu procentowego.**
To około 12,5 mln tokenów ważonych, czyli 6-7 typowych sesji. Pojedyncza sesja jest **mniejsza niż rozdzielczość źródła** — nie da się jej zmierzyć bezpośrednio, tylko przeliczyć kursem. Stąd próg minimalnej różnicy 3 punktów: para zbudowana z przyrostu 1 punktu dała kurs 3,52 mln zamiast 12,54 (zmierzone 01.08.2026).

**Co z tego wynika w praktyce:** wtyczka rzetelnie odpowiada na „ile zostało limitu" i „czy ta sesja jest droga na tle moich innych sesji". Nie odpowiada precyzyjnie na „dokładnie ile zjadłem". Budżet sesji działa jak hamulec, nie jak miarka — „zostało 0,30%" może realnie znaczyć 0,25% albo 0,37%.

Pozostałe:
- Modele innych dostawców są pomijane — nie obciążają tego limitu.
- Gdy żadne źródło nie ma odczytu, narzędzie nie zgaduje: pokazuje tylko porównania względne.
- Odczyt limitu wtyczka pobiera sama. Claude Code trzyma ostatni odczyt w `~/.claude.json`, ale od wersji 2.1.238 przestał go odświeżać — 21.08.2026 pole stało cały dzień, mimo kilku `/usage`. Kalibracja żywi się różnicą dwóch odczytów, więc zamrożone pole zatrzymuje licznik. Od tej daty wtyczka pyta o limit tym samym adresem co CLI (`GET /api/oauth/usage`, token OAuth z pęku kluczy systemu, a poza macOS z pliku `~/.claude/.credentials.json`), w tle, nie częściej niż raz na 15 minut, i zapisuje do `state/budzet/odczyt-limitu.json`. `~/.claude.json` zostaje nietknięty; przy odczycie wygrywa świeższe źródło. Ręcznie: `python3 $BIN odswiez` — błąd oznacza wygasły token, wtedy `/login`.