Intercept LLM API traffic and visualize token usage in a real-time terminal dashboard. Track costs, debug prompts, and monitor context window usage across your AI development sessions. . It is open-source on GitHub.

Is tokentap free to use?

tokentap is open-source under the MIT license, so it is free to use.

What category does tokentap belong to?

tokentap is listed under devtools in the Claudeers registry of Claude-compatible tools.

Tokentap (formerly Sherlock)

Token Tracker for LLM CLI Tools

Installation • Quick Start • Features • Commands • Contributing

tokentap tracks token usage for LLM CLI tools with a live terminal dashboard. See exactly how many tokens you're using in real-time.

Why tokentap?

Track Token Usage: See exactly how many tokens each request consumes
Monitor Context Windows: Visual fuel gauge shows cumulative usage against your limit
Debug Prompts: Automatically saves every prompt as markdown and JSON for review
Zero Configuration: No certificates, no setup - just install and go

Installation

pip install tokentap

Or install from source:

git clone https://github.com/jmuncor/tokentap.git
cd tokentap
pip install -e .

Requirements

Python 3.10+

Quick Start

Terminal 1: Start the Dashboard

tokentap start

You'll be prompted to choose where to save captured prompts, then the dashboard appears:

┌─────────────────────────────────────────────────────────────┐
│  TOKENTAP - LLM Traffic Inspector                           │
├─────────────────────────────────────────────────────────────┤
│  Context Usage  ████████████░░░░░░░░░░░░░░░░  42%           │
│                 (84,231 / 200,000 tokens)                   │
├─────────────────────────────────────────────────────────────┤
│  Time     Provider    Model                      Tokens     │
│  14:23:01 Anthropic   claude-sonnet-4-20250514   12,847     │
│  14:23:45 Anthropic   claude-sonnet-4-20250514   8,234      │
│  14:24:12 Anthropic   claude-sonnet-4-20250514   15,102     │
├─────────────────────────────────────────────────────────────┤
│  Last Prompt: "Can you help me refactor this function..."   │
└─────────────────────────────────────────────────────────────┘

Terminal 2: Run Your LLM Tool

# For Claude Code
tokentap claude

# For Gemini CLI (see known issues)
tokentap gemini

# For OpenAI Codex
tokentap codex

# For MiniMax-powered tools
tokentap run --provider minimax python my_app.py

That's it! Watch the dashboard update in real-time as you work.

Features

Live Terminal Dashboard

Real-time token tracking with color-coded fuel gauge:

Green: < 50% of limit
Yellow: 50-80% of limit
Red: > 80% of limit

Prompt Archive

Every intercepted request is saved to your chosen directory:

Markdown - Human-readable format with metadata
JSON - Raw API request body for debugging

Session Summary

When you exit, see your total usage:

Session complete. Total: 84,231 tokens across 12 requests.

Commands

Command	Description
`tokentap start`	Start the proxy and dashboard
`tokentap claude`	Run Claude Code with proxy configured
`tokentap gemini`	Run Gemini CLI with proxy configured
`tokentap codex`	Run OpenAI Codex CLI with proxy configured
`tokentap run --provider <name> <cmd>`	Run any command with proxy configured

Supported providers for --provider: anthropic, openai, gemini, minimax

Options

tokentap start [OPTIONS]

Options:
  -p, --port NUM    Proxy port (default: 8080)
  -l, --limit NUM   Token limit for fuel gauge (default: 200000)

tokentap claude [OPTIONS] [ARGS]...

Options:
  -p, --port NUM    Proxy port (default: 8080)

How It Works

┌─────────────────────────────────────────────────────────────────┐
│  Terminal 1: tokentap start                                     │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │  HTTP Proxy (localhost:8080)                                ││
│  │  + Dashboard                                                ││
│  │  + Prompt Archive                                           ││
│  └─────────────────────────────────────────────────────────────┘│
└───────────────────────────────┬─────────────────────────────────┘
                                │ HTTP
                                │
┌───────────────────────────────┴─────────────────────────────────┐
│  Terminal 2: tokentap claude                                    │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │  Sets ANTHROPIC_BASE_URL=http://localhost:8080              ││
│  │  Runs: claude                                               ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
                                │
                                │ HTTPS
                                ▼
                      ┌───────────────────┐
                      │ api.anthropic.com │
                      └───────────────────┘

For OpenAI-compatible providers like MiniMax, tokentap uses path-prefix routing so requests are forwarded to the correct upstream API:

tokentap run --provider minimax python my_app.py
  → sets OPENAI_BASE_URL=http://localhost:8080/minimax/v1
  → requests arrive at /minimax/v1/chat/completions
  → proxy strips prefix, forwards to https://api.minimax.io/v1/chat/completions

Supported Providers

Provider	Command	Status
Anthropic (Claude Code)	`tokentap claude`	Supported
Google (Gemini CLI)	`tokentap gemini`	Blocked by upstream issue
OpenAI (Codex)	`tokentap codex`	Supported
MiniMax	`tokentap run --provider minimax <cmd>`	Supported

Known Issues

Gemini CLI

Gemini CLI currently has a known issue where it ignores custom base URLs when using OAuth authentication. tokentap's Gemini support will work automatically once the Gemini CLI team fixes this issue.

Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

git clone https://github.com/jmuncor/tokentap.git
cd tokentap
python -m venv venv
source venv/bin/activate
pip install -e .

License

This project is licensed under the MIT License - see the LICENSE file for details.

See what's really being sent to the LLM. Track. Learn. Optimize.

tokentap.ai

Platforms	cli, api
Operating systems	—
AI compatibility	claude
License	MIT
Pricing	open-source
Language	Python

tokentap