tokensniff weekly downloads statistics

tokensniff

Local telemetry sidecar for AI coding CLIs.

Track every token, every turn, every dollar — live in your terminal and on a calendar heatmap dashboard. Zero runtime dependencies.

What Is tokensniff?

tokensniff is a transparent HTTP reverse proxy and local telemetry sidecar designed specifically for the Claude Code CLI harness running alongside the local antigravity-claude-proxy.

By default, tokensniff orchestrates and connects to antigravity-claude-proxy to route Claude Code API requests through Google Antigravity / Cloud Code, allowing you to utilize your Antigravity Gemini quota directly inside Claude Code.

⚠️ Important Notice: Use At Your Own Risk & Account Warning

[!CAUTION] Use at your own risk. By default, tokensniff routes traffic through antigravity-claude-proxy, which accesses Google Antigravity / Cloud Code endpoints using unofficial proxying techniques.

- Risk of Account Suspension / Bans: Google actively monitors and enforces Terms of Service (ToS) restrictions. Accounts connected to unofficial Cloud Code and Antigravity reverse proxies risk being shadow-banned, quota-restricted, or permanently banned. - No Guarantees & Zero Liability: The creators and maintainers of tokensniff provide no guarantees or warranties of any kind, express or implied. We are not responsible or liable for any account bans, suspensions, quota penalties, data loss, or any other consequences resulting from the use of this software. - Safety Recommendation: Do not use your primary, personal, or corporate Google account. If you choose to use this integration, use a dedicated burner/disposable Google account. - Learn More: Read the upstream antigravity-claude-proxy GitHub Repository and its Safety, Usage, and Risk Notices to understand how the underlying authentication and proxying operate.

It captures every API turn flowing through it and gives you:

• Per-turn token counts — input, output, cache-read, cache-write, thinking tokens • Real-time cost tracking — per turn, per session, per day (in USD) • Performance metrics — Time to First Token (TTFT), tokens per second (TPS), turn duration • Live terminal status line — a single-line HUD rendered directly inside Claude Code's status bar • Calendar heatmap dashboard — a beautiful, self-contained HTML page showing your daily token spend over the entire year • Multi-terminal session management — run multiple terminals against the same proxy without conflicts • Tool call tracking — which tools the model called, how many times, argument token sizes • Context window monitoring — how full your context is, with color-coded warnings (green → yellow → red)

All of this happens transparently. Your AI tool doesn't know tokensniff exists. It just thinks it's talking to the normal API. tokensniff forwards every byte with zero latency overhead, while quietly recording the telemetry.

How It Works

1. Harness Redirection: You point Claude Code to http://localhost:4000 by setting ANTHROPIC_BASE_URL in ~/.claude/settings.json. Claude Code continues sending standard Anthropic Messages API requests normally. 2. Upstream Proxy Startup: When launched, tokensniff checks port 8085 and automatically starts the local upstream proxy command (npx antigravity-claude-proxy@latest start) if it is not already running. 3. Protocol & Quota Translation: The local antigravity-claude-proxy receives the Anthropic-formatted request, authenticates with your Google Antigravity / Cloud Code OAuth credentials, translates the schema to Google Generative AI format, and submits it to Google Cloud Code's backend to consume your Antigravity Gemini quota. 4. Streaming Response Pass-Through: As Google's response streams back, antigravity-claude-proxy transforms it into Anthropic-compatible SSE events or buffered JSON. tokensniff instantly relays every raw byte back to Claude Code (res.write(chunk)) with zero latency overhead. 5. Telemetry Extraction: Concurrently and non-blockingly, tokensniff's parser inspects the response payload. It extracts Google's usageMetadata (input, output, cache-read, cache-write, and thinking/reasoning tokens), measures Time to First Token (TTFT) and token generation speed (TPS), and tracks turn duration. 6. Live Pricing Calculation: tokensniff queries live pricing from OpenRouter's model catalog, computing turn cost, session cumulative spend, and daily totals. 7. Statusline HUD & Calendar Heatmap: Telemetry snapshots are written atomically to disk (latest.json, totals.json, history.ndjson). Claude Code's status bar runs tokensniff-status to display the live single-line HUD, and tokensniff serves an interactive calendar heatmap dashboard at http://localhost:4000/dashboard.

Quick Start

1. Install

Or with pnpm:

2. Initialize Configuration

This creates a configuration file at ~/.tokensniff/config.json with sensible defaults:

Default Upstream: Out of the box, tokensniff is pre-configured to launch antigravity-claude-proxy on port 8085, allowing you to route Claude Code prompts through your Antigravity Gemini quota. Please review the Risk & Terms of Service Warning before running with this configuration.

3. Configure Claude Code

Add the following to your ~/.claude/settings.json file:

This does two things:

• ANTHROPIC_BASE_URL — Tells Claude Code to send all API requests through tokensniff's proxy on port 4000 instead of directly to Anthropic • statusLine — Tells Claude Code to run tokensniff-status and display its output as a live status bar at the bottom of the terminal

4. Run

That's it. tokensniff will:

1. Start the upstream proxy (if configured) 2. Start the telemetry proxy on port 4000 3. Launch Claude Code (or whatever harness command you configured) 4. Show you a live status line and dashboard URL

Open the dashboard in your browser:

CLI Commands

tokensniff

Runs the full telemetry pipeline: starts the upstream proxy, starts the tokensniff proxy, and launches your AI coding tool.

tokensniff init…

Description from the npm listing.