Know what your AI is costing you — in real time.
Saropa Claude Guard tracks Claude API costs by tailing local JSONL log files, showing live spend in the VS Code status bar and enforcing daily/monthly budgets. Works with Claude Code and any tool that writes to ~/.claude/projects/.
Have feedback or ideas? Share them by opening an issue on GitHub!
Who is this for?
- Developers who use Claude-powered coding tools and want visibility into API spend
- Anyone who has been surprised by an unexpectedly large AI bill
- Teams that need budget guardrails on AI usage
Overview
- Claude API costs are invisible by default — this extension makes them visible, trackable, and enforceable.
- Zero config: install and start coding, costs are tracked automatically from local log files.
- Status bar shows live session and daily totals. Budget warnings trigger when you approach limits.
Features
Click to expand full feature list
Real-Time Cost Tracking
- Auto-discovery: Finds Claude log files automatically (
~/.claude/projects/)
- Live status bar: Shows current session cost, updated in real time
- Accurate dedup: Same requestId appears multiple times in logs with cumulative tokens — the extension calculates deltas to avoid double-counting
- Model-aware pricing: Knows the cost of each Claude model (Opus, Sonnet, Haiku) including cache read/write rates
- Tool usage tracking: Counts tool invocations (Read, Bash, Grep, Write, etc.) grouped by category — File Ops, Edits, Commands, Web, Agents
Budget Enforcement
- Daily soft cap: Configurable daily limit (default $2.00) with status bar warnings at 80% and 100%
- Monthly hard cap: Configurable monthly limit (default $50.00) with escalating alerts
- Linked budgets: Lock icon links monthly to daily × 30 by default — prevents nonsensical configs
- Persistent tracking: Costs survive VS Code restarts
Dashboard Panel
- Tabbed webview: Session, Today, Week, Month, and All Time cost views with charts and data tables
- Settings tab: Live budget configuration with at-a-glance cost summary strip
- Resources tab: Searchable catalog of online AI alternatives with quality/speed ratings and filter pills
- Guide tab: Claude Code hooks setup guide with copy-to-clipboard code blocks
- About tab: Saropa company info, project catalogue, and social links
Cost Interceptors
- Heavy context alert: Warns when input tokens exceed a configurable threshold (default 30,000)
- Fluff filter: Detects low-value exchanges where Claude's output is very short but request cost is non-trivial
- Low-ROI detection: Flags high-input-cost messages with minimal output
- Silent guard: Suppresses non-critical alerts when you have an active text editor open
Rate Limit Protection
- 5-hour burst window: Tracks weighted token usage matching Anthropic's Layer A burst limit with plan-specific thresholds (Pro, Max 5x, Max 20x)
- 7-day sustain gauge: Monitors rolling 7-day weighted token usage to prevent multi-day account bans
- Weighted quotas: Accounts for model tier (Opus 15×, Haiku 0.1×) and output token penalty (3×)
- Cooldown timer: Configurable cooldown between messages to prevent API rate-limit bans
- Velocity warning: Alerts when messages exceed burst limit within time window
Context Visualizer
- Context weight bar: Secondary status bar item showing ASCII progress bar of context weight vs model limit
- Zone coloring: Green/yellow/red zones as context usage increases
Pause Monitoring
- Toggle pause: Temporarily disable cost tracking without uninstalling — via command palette or settings tab button
- Status bar indicator: Pause icon with warning background when monitoring is paused
- Persists across sessions: Pause state survives VS Code restarts
Pricing Engine
- Built-in model pricing: Up-to-date prices for all Claude models
- Cache awareness: Distinguishes standard input, cache read, and cache write pricing
- User overrides: Custom pricing via
saropaClaudeGuard.pricing.overrides for enterprise contracts or proxy providers
Online Alternatives
- Curated catalog: 50+ online AI tools across 8 categories (Chat, Coding, Visual, Audio, Video, Research, Local Models, Productivity)
- Smart search: Real-time filtering across name, description, category, origin, and platform
- Quality ratings: Quality and speed ratings with filter pills (Quality 4.5+, Speed 4+, Free)
- Favorites and preferences: Pin favorites, hide tools you don't use, override standard entries
- Budget notifications: "Show Online Alternatives" button appears on daily warning and monthly critical alerts
Log Parsing
- JSONL streaming: Tails log files efficiently — reads only new bytes, never the whole file
- Smart filtering: Only counts
type: "assistant" messages, skips sidechain and error messages
- Cross-platform: Works on Windows, macOS, and Linux
- Historical caching: Three-tier cache (in-memory → per-file → disk) for fast historical data loading
Multi-Window Support
- Leader/follower coordination: When multiple VS Code windows open the same project, only one window actively watches log files — others poll the leader's snapshot, eliminating data races and cost inflation
Internationalization
- 6 languages: English, German, Traditional Chinese, Simplified Chinese, Japanese, Korean
- Auto-detection: Picks up your VS Code locale automatically, or set manually
Installation & Quick Start
- Install the extension from the VS Code Marketplace
- Start using any Claude-powered coding tool
- The status bar shows your running cost automatically
No configuration needed — it just works.
Configuration
All settings are prefixed with saropaClaudeGuard.
Core Settings
| Setting |
Default |
Description |
enabled |
true |
Enable or disable the extension |
paused |
false |
Temporarily pause cost monitoring without disabling |
provider |
"anthropic-official" |
Which AI provider log format to parse |
dataDirectory |
"" |
Custom Claude data directory (empty = auto-detect) |
Budget Settings
| Setting |
Default |
Description |
budgets.dailyLimit |
2.00 |
Daily spending soft cap in USD |
budgets.monthlyLimit |
50.00 |
Monthly spending hard cap in USD |
budgets.linkMonthlyToDaily |
true |
Monthly limit = daily × 30 when locked |
pricing.overrides |
{} |
Model pricing overrides (per million tokens USD) |
Interceptor Settings
| Setting |
Default |
Description |
interceptors.enabled |
true |
Enable post-action cost alerts |
interceptors.heavyContextThreshold |
30000 |
Input token count triggering heavy-context alert |
interceptors.bannedPhrases |
["thanks", ...] |
Low-value phrases that trigger fluff alerts |
interceptors.fluffMinCost |
0.05 |
Minimum response cost ($) to trigger fluff alert |
interceptors.costDecimalPlaces |
2 |
Decimal places for costs in interceptor notifications |
Rate Limit Settings
| Setting |
Default |
Description |
rateLimits.plan |
"none" |
Subscription plan (none, pro, max5x, max20x) |
rateLimits.windowTokenLimit |
0 |
Custom 5-hour burst token limit (0 = plan default) |
rateLimits.warningThreshold |
0.8 |
Fraction of limit to trigger warning (0.1–1.0) |
rateLimits.opusMultiplier |
15 |
Quota weight for Opus models |
rateLimits.haikuMultiplier |
0.1 |
Quota weight for Haiku models |
rateLimits.outputMultiplier |
3 |
Output/thinking token weight multiplier |
rateLimits.conservativeMode |
true |
Count cached tokens at full weight |
rateLimits.sustainTokenLimit |
0 |
Custom 7-day sustain limit (0 = plan default) |
safety.cooldownSeconds |
15 |
Cooldown between messages (0 = disable) |
safety.maxBurstMessages |
3 |
Max messages within cooldown before velocity warning |
Display Settings
| Setting |
Default |
Description |
display.refreshInterval |
60 |
Historical data refresh interval in seconds (min 30) |
display.language |
"auto" |
Display language (auto, en, de-DE, zh-TW, zh-CN, ja, ko) |
ui.showContextBar |
true |
Show context weight progress bar in status bar |
Known Limitations
- Currently supports Claude Code (Anthropic official) logs only. Multi-provider support (Cline, Aider) is planned for a future release.
- Rate limit thresholds are estimated — Anthropic does not publish exact quota numbers, so built-in plan defaults are approximations.
- Cost-per-message preview (estimate cost before sending) is not yet implemented.
Contributing
Great tools are built by communities, not companies. Contributions and feedback are welcome.
If you think a feature is:
- Broken — tell us what happened, we'll fix it
- Missing — propose it, or better yet, submit a PR
- Confusing — help us improve the docs or UX
How to contribute
See CONTRIBUTING.md for developer setup, code quality standards, and contribution guidelines.
Quick start:
- Fork the repository
- Create a feature branch
- Run
npm run compile to verify your changes
- Open a Pull Request
Reporting issues:
- Include your VS Code version and OS
- Describe the expected vs actual behavior
- If possible, include relevant log output
Discussing ideas
Not sure if something is a bug or a feature request? Open a discussion issue. We're happy to talk through ideas.
Documentation
License
MIT — see LICENSE. Use it however you like.
Built by Saropa. Questions? Ideas? Open an issue — we'd love to hear from you.
GitHub | Issues | Saropa
| |
