Em português: kostria.hypermind.space

Kostria

Kostria is a Python CLI that reads the usage logs Claude Code, Codex CLI, Gemini CLI and OpenCode already write to your disk, and shows what your AI spend is by project, account and model. No proxy, no SDK, no code changes. Analysis runs locally; the hosted board is optional.

Install

pip install kostria

Zero dependencies: Python 3.11+ and the standard library.

On Windows, pip install without administrator rights puts kostria.exe in a folder that is not on your PATH, so kostria is not recognized. The Python launcher works in every case:

py -m pip install kostria
py -m kostria login
py -m kostria scan

First run

kostria init      # optional: creates a .kostria.toml and detects your work folders
kostria scan      # cost summary in the terminal
kostria serve     # local dashboard at http://127.0.0.1:8787

scan does not need init. The first run reads your whole history and can take a few minutes (measured: 4.5 minutes for 6.7 GB of Claude Code logs); later runs use a cache. If you see "nenhum registro de uso encontrado" (no usage records found), the message lists where Kostria looked.

What the summary looks like:

$ kostria scan

custo total: $2,480.00   tokens: 1.2B   sessões: 89

by commit scope (illustrative):
   checkout-pix (PROJ-118)     $942.40   38%
   onboarding (PROJ-204)       $719.20   29%
   busca (PROJ-091)            $496.00   20%

AI coding tools get expensive fast, and the vendor dashboard shows cost per account, not per project or per area of work. Kostria answers:

• How much did each project consume?
• Where did usage concentrate? Project, then the technical area inferred from the commit. A ticket ID is only confirmed once you connect a tracker (GitHub Issues, Jira or Linear). The inferred area is not proof that a feature shipped.
• How do models compare? Cost and observed edits per model. It does not infer quality or productivity from those numbers alone.
• How much of the subscription did you use? Separates real usage from the fixed fee (Claude Pro/Max).
• Is an account idle? Flags accounts with no activity in the last 14 days.
• Will the budget blow up? Monthly projection plus an end-of-month forecast.
• What changed between two windows? Compare API-equivalent cost and tokens per calendar day, with price coverage, without mistaking a reference price for an invoice.
• Where did capacity run out? Record limits, blocks, and the account or provider you used to keep going, without adding up incompatible quotas.
• When to review a subscription? Enter the renewal date in the Wallet and pick an optional e-mail reminder, 1 to 30 days before.

Worktrees of the same repository show up as one project. Machine and agent configuration and temporary files stay in the measured total, but the dashboard shows them separately as usage with no confirmed project.

What leaves your machine, and what does not

• Analysis and reports run locally and work offline. By default, scan sends a one-time anonymous install ping (and tells you on screen) and checks PyPI to warn about updates. kostria scan --no-telemetry turns off both for that run. Work data only reaches the board after kostria login and a sync, whether manual, scheduled or opportunistic during scan/report.
• On a personal Pro workspace, sync sends the aggregate: project, day, cost, tokens, inferred area and ticket ID, totals per model/provider/tool, the measurement basis, an irreversible per-response identifier for deduplication, this machine's name, and your AI plan (amount paid and API equivalent) with the account masked (a***@domain). Never a file path, never session content, never the full e-mail.
• On Team/Enterprise, only the projects you choose locally are sent. Global totals, subscriptions and the account inventory stay out, because they could reveal personal data by subtraction. An AI account only enters the Team Wallet if you include it with kostria compartilhar --conta, and only that account is queried at Anthropic.
• On a Team, owners and admins see the per-day, per-project, per-model detail of each person; other members see their own detail and their teammates' totals.
• Running kostria login again on the same machine replaces its previous token (no double counting), and changing your selection reaches the machine's whole history.
• Do not want to send your plan? kostria sync --sem-assinatura.
• --anonymize replaces names with a stable hash, for reports you can share.
• Do not take our word for it. kostria sync --dry-run -v prints the exact JSON that would go up and sends nothing. Run it before your first sync.

$ kostria sync --dry-run
[dry-run] endpoint: https://kostria.hypermind.space/sync
[dry-run] 255 entries -> workspace 0000…
[dry-run] 3 assinatura(s): a***@empresa.com.br (claude_max_20x, $200.00/mes), …

Supported tools

Prices come from the official Anthropic and OpenAI tables, read in full every day. A new model enters the catalog as data, without a new CLI release, and the catalog reaches each machine on sync. Where the official table does not cover a model, OpenRouter is used as a secondary source, marked as such. A tier variant (-pro, -high) of a model with an official price is left unpriced instead of inheriting the base price. An unreadable source keeps the last intact version.

Plans: what each one reads

Checkout is in Brazilian reais (BRL). Prices above are what you are charged; there is no dollar price. See current pricing.

On Team you choose the seats, minimum 2. Tiers: 2 to 5 people R$ 39 each; 6 to 20 R$ 29; 21 to 50 R$ 19. Three seats cost R$ 117/month; ten, R$ 290/month. The board warns you if it measures more people than seats and does not adjust billing on its own.

The engine runs locally and the code is proprietary. You can start free with Claude Code; Pro and Team add the other collectors and the finer attribution. On Pro and Team, public GitHub repositories can validate tickets without a token. Private repositories need a read token, which Kostria stores encrypted.

Commands

kostria scan                          # terminal summary
kostria scan --since 30d --compare    # against the previous period
kostria scan --budget 3000            # budget alert
kostria scan --anonymize              # mask names (shareable)

kostria report                        # HTML (opens in the browser)
kostria report --format json -o dados.json
kostria report --format csv  -o custos.csv

kostria serve                         # local dashboard at 127.0.0.1:8787
kostria watch                         # live view in the terminal
kostria doctor                        # integrity checks on the numbers
kostria contas --json                 # local accounts and priced individual plans
kostria badge -o badge.svg            # local shields.io-style badge

kostria compartilhar                  # on Team: choose locally which projects may go up
kostria sync                          # sends only the authorized slice on Team
kostria agendar                       # recurring sync via the OS scheduler
kostria agendar --mostrar             # shows what would be installed, without installing

kostria contas lists the AI accounts on this machine, the detected plan and the public price of that plan with source and date, and tells you whether it read usage at Anthropic or why it did not. kostria sync --descobrir-contas, in a terminal, shows what changes and asks for confirmation: it sends the detected accounts to the Wallet (masked e-mail, plan, login state and % of use) and reads each Claude account's % of use from api.anthropic.com/api/oauth/usage with the token Claude Code already stores. It is read-only, at most every 5 minutes, and never renews or alters the login. Outside a terminal (cron, scripts) it only sends the accounts. Codex reports its own usage in the local logs. kostria contas --revogar undoes the authorization. If you authorized on a version older than 0.2.20, accounts keep being sent, but the Anthropic read only comes back after you confirm again.

On Team, the 0.2.35 authorization sends every account on the machine and says which account each session came from; in the Wallet, each person answers who pays for each one. The cost of an account the person pays for leaves the Team and stays only in their Personal view, even on a Team project. An authorization older than 0.2.35 sends no account on Team until confirmed again.

Projects that belong to the same product

A separate repository or lab is not necessarily a new product. When that relation does not show up in the paths or in Git, create ~/.config/kostria/project-aliases.toml (or under $XDG_CONFIG_HOME/kostria):

[aliases]
pose-lab = "starhash"

The key is the exact name the CLI detects; the value is the canonical project. The mapping applies to reports and to the next syncs from this machine. It does not change history already sent and does not guess which product a stray file belongs to: folders in /tmp, Downloads and cache with no proof of a repository stay under usage with no confirmed project, still counted in total cost and tokens.

The Wallet

The Wallet asks one question per account: who pays. Plan, login state (active, disconnected, idle for N days), usage for the week and the last 5 hours, and the warning for an account used on several machines all come from the machine. The renewal date has no local source (the weekly reset is not the renewal) and stays an optional field. Enterprise plans show as "under contract", with no public price and no zero added to the sum. A public price is not an invoice, and an API equivalent does not measure ROI.

Accounts with no payer, disconnected, or with high limits show first; the Attention filter gathers what to review. Monthly use compares accounts without mistaking the month in progress for a full month. Under Models, the main distribution follows period, person and project; tools and providers sit in the cumulative history, separately. On Team, each person's trend, variation and main project stay visible on mobile.

Syncing to the board

After kostria login, everyday commands (scan, report) can sync every 6 hours without redoing the scan. On a Team or Enterprise workspace, each person chooses on the site, under My projects, what goes to the Team: kostria compartilhar sends the names of new projects and opens that page. Until you choose, only the name goes up, visible only to you; the project's cost and tokens are not in the payload, not even as an anonymous total. Marking a project as personal deletes what had already gone up right away and keeps only a hash of the name. Selecting from the terminal (--permitir, --limpar) applies outside Team.

Turn off automatic sending with --sem-autosync (or autosync = false in kostria.toml). kostria agendar covers people who spend the day inside the agent and never type kostria.

The optional board

kostria.hypermind.space is a hosted board for personal and team views (English landing at /en). It is optional: the CLI and the local dashboard work without it. Nothing reaches it before kostria login, and kostria sync --dry-run -v shows exactly what would.

The optional public ranking

tokenranking.online is an opt-in public ranking. Joining and leaving happen on your account page on the site, where it states what becomes public; the terminal only opens that page and shows your status:

kostria ranking            # your status (needs `kostria login`)
kostria ranking entrar     # opens the join page (alias: join)
kostria ranking sair       # opens the leave page (alias: leave)

The ranking itself is open to anyone to read, no account needed.

How Kostria differs

Not a proxy (Helicone). Not quality tracing (Langfuse). Not cloud FinOps (Vantage). It reads the logs already on your disk, with no SDK, no proxy and not one line of your code changed.

License

Proprietary and free to use, including commercially inside your company: no sign-up, no seat counting, no expiry. What you may not do is redistribute, modify, or use the code to build a competitor (full text in LICENSE).

Up to version 0.2.3 the package shipped under MIT, and that grant is not revoked: it holds for those versions. The current license applies from 0.2.4 on.

Links

• Site and team board · English landing
• Plans and pricing
• Privacy
• Public ranking
• Support and security: hypermind.ia@gmail.com

Made in Viçosa, MG, Brazil by Pedro Henrique.