TokenFootprint

TokenFootprint is a VS Code extension for previewing token usage and approximate environmental impact of code context before sending it to an LLM, and for tracking user-imported or locally discovered usage afterward.

The extension stores records locally and has no TokenFootprint backend or telemetry.

Important disclaimers

• TokenFootprint provides estimates and interpretation aids only.
• CO₂e, water, derived energy, cost, and equivalent comparisons are not exact measurements.
• Do not use TokenFootprint for audited environmental reporting, regulatory filings, ESG disclosures, billing verification, or contractual emissions claims.
• TokenFootprint is not affiliated with, endorsed by, sponsored by, or certified by OpenAI, GitHub, Anthropic, Google, Cursor, Windsurf, xAI, Hugging Face, Microsoft, Visual Studio Code, or their respective owners.

What it does

• Previews selected text or the active file against a remembered model-family picker.
• Ships presets for OpenAI GPT/Codex, Anthropic Claude, Google Gemini, GitHub Copilot, DeepSeek, Qwen, and Meta Llama, plus custom model entry.
• Shows a compact unsaved result panel with token method, confidence, expected accuracy, CO₂e range, and assumptions.
• Saves pre-send estimates only after Save planned context is selected.
• Manually imports usage totals shown by Codex, GitHub Copilot, Claude Code, Cursor, Windsurf, Gemini CLI, or another AI coding assistant with TokenFootprint: Import AI Usage.
• Imports copied usage summaries with TokenFootprint: Import Usage From Clipboard, parsing common token, credit, provider, and model labels locally.
• Imports one, multiple, or all local Codex chats with TokenFootprint: Import Local Codex Chat Usage. No API key is required.
• Imports readable local Copilot, Cursor, or Claude Cowork chat transcripts with TokenFootprint: Import Local Assistant Chat Usage when those tools expose transcript files locally.
• Stores Anthropic and Gemini token-count API credentials in VS Code SecretStorage when explicitly configured.
• Uses the Anthropic and Gemini token-count APIs for pre-send text when their credentials are configured.
• Stores the last 1,000 planned and actual usage records in VS Code local global state.
• Shows today's estimated token total in the status bar.
• Opens a local webview dashboard with:
  • An all-time summary of tokens, estimated CO₂e, water, and derived energy
  • Input/output donut breakdowns based on locally stored token records
  • LED bulb, water, and phone-charge equivalents
  • The last 10 local records
• Deletes all locally stored extension data with explicit confirmation.

Privacy and local-first behavior

• No telemetry is included.
• There is no TokenFootprint backend.
• TokenFootprint does not use network calls for telemetry, analytics, account tracking, usage storage, clipboard import, manual import, local dashboard display, or local history imports.
• Selected text and current file content are processed locally by default and only when you explicitly run an estimate command. If you explicitly configure Anthropic or Gemini token-count credentials and choose the corresponding model path, selected text or current-file content may be sent to the chosen provider's token-count endpoint solely to request a token count.
• Clipboard content is read only when you explicitly run TokenFootprint: Import Usage From Clipboard.
• Clipboard content is parsed locally and is not transmitted by the clipboard import workflow.
• Usage records are stored locally using VS Code storage. Usage records, credentials, remembered model selection, and downloaded tokenizer assets can be removed with TokenFootprint: Delete All Local Data.

Some optional token-counting or tokenizer features may contact third-party services only when you choose a model path that requires them and, where applicable, explicitly configure a provider API key. These calls are not TokenFootprint telemetry and are not sent to a TokenFootprint backend.

Environmental estimate disclaimer

CO₂e and water values are estimates based on configurable assumptions. They are not exact measurements.

Dashboard energy is derived from the CO₂e range and the configured grid-intensity assumption. Equivalent comparisons are illustrative interpretation aids, not direct measurements.

Actual impact varies by provider, model, data center, hardware, energy source, region, hidden reasoning compute, caching, batching, and workload. TokenFootprint should be used as an approximate local planning aid, not as audited environmental reporting.

Affiliation disclaimer

TokenFootprint is not affiliated with, endorsed by, or sponsored by OpenAI, GitHub, Anthropic, Google, Cursor, Windsurf, xAI, or their respective owners.

Provider names are used only for user-facing categorization, model-family selection, and import labels.

Project documents

By installing or using TokenFootprint, you agree to the Terms of Use.

• Privacy Policy
• Security Policy
• Terms of Use
• Changelog
• Third-Party Notices

Marketplace-safe summary

TokenFootprint estimates AI coding token usage, cost, CO₂e, water impact, derived energy, and human-readable equivalents in VS Code. Values are approximate and based on configurable assumptions and available token-count data. TokenFootprint has no TokenFootprint backend and no TokenFootprint telemetry. Optional Anthropic/Gemini token-count APIs are used only when the user explicitly configures credentials and selects those model paths.

Current MVP limitations

• Token counts are model-specific. OpenAI/Codex uses a bundled compatible tokenizer. Qwen, DeepSeek, Llama, Mistral/Codestral, and Gemma use compatible Hugging Face tokenizer files.
• Hugging Face tokenizer files are downloaded on first use into VS Code's extension-specific global storage and reused locally afterward. If a download fails, the result remains a disclosed heuristic rather than claiming tokenizer accuracy.
• Anthropic and Gemini use their provider token-count APIs when configured. Copilot and unknown/custom models use the disclosed heuristic because their exact tokenizer cannot be determined reliably.
• Compatible tokenizer counts have high confidence and expected accuracy of roughly 95–99%. Heuristic counts have medium confidence and expected accuracy of roughly 60–80%.
• Manually imported provider-reported totals have high confidence (roughly 95–99%); clipboard totals that are parsed and user-confirmed have high confidence (roughly 90–99%).
• Exact token counts depend on the tokenizer and version used by the specific model, so the same text can produce different counts across model families.
• Carbon values are never exact measurements. They are ranges from versioned model-family profiles or explicit user overrides.
• Optional Anthropic and Gemini prompt-count credentials are stored in VS Code SecretStorage and are never written to usage records or normal settings.
• Personal Codex subscriptions, personal Copilot, and Claude Cowork do not expose a supported immediate per-request usage API to this extension; use clipboard or manual import for those tools.

How estimates work

1. Choose the model family that will receive the selected text or current file.
2. TokenFootprint uses a compatible local tokenizer or configured provider count API. Unsupported models fall back to ceil(characters / 4).
3. It resolves a versioned model-family carbon profile, or uses your custom override when tokenFootprint.carbonProfileMode is custom.
4. It calculates footprint ranges per 1,000 tokens:
   • Estimated water low/high ml per 1,000 tokens
   • Estimated CO₂e low/high grams per 1,000 tokens

The preview is not stored until you choose Save planned context. Higher-confidence token counting does not make environmental impact exact: impact varies by model implementation, hardware, provider, data-center region, grid mix, hidden reasoning compute, caching, batching, and workload.

Manual AI usage import

Run TokenFootprint: Import AI Usage to enter usage numbers that another local or hosted AI coding assistant already shows you. The command is manual by design:

• It uses VS Code quick picks and input boxes only.
• It supports Codex, GitHub Copilot, Claude Code, Cursor, Windsurf, Gemini CLI, and an "Other" provider option.
• It accepts comma-formatted numbers such as 125,000.
• It stores the imported total locally as an imported-ai-usage record, includes it in today's status-bar total, and shows it in the recent estimates table.
• It does not integrate private APIs, scrape provider UIs, add telemetry, authenticate with providers, or make network calls.

Clipboard AI usage import

Run TokenFootprint: Import Usage From Clipboard after manually copying a usage summary from your AI coding assistant. TokenFootprint reads only your local VS Code clipboard, parses common labels such as Tokens used, Input tokens, Output tokens, Remaining tokens, Credits used, Remaining credits, Provider, and Model, then lets you confirm or edit parsed token, credit, and remaining-balance values before saving.

Clipboard import remains local-first:

• You must copy the usage text manually.
• Clipboard import does not connect to provider APIs. Separate pre-send estimates may call Anthropic or Gemini token-count APIs only when you explicitly configure a key.
• It does not scrape UIs, use private integrations, send telemetry, authenticate with providers, or make network calls.
• If total tokens are not present but input and output tokens are present, TokenFootprint computes the total locally.
• If total tokens cannot be detected, TokenFootprint asks you to enter the total before import.

Imported usage totals are treated as already-counted tokens. TokenFootprint applies the current water and CO₂e methodology to those totals, so environmental values remain modeled estimates rather than exact measurements.

Higher-confidence token-count APIs

Run TokenFootprint: Configure Token Counting to securely store an Anthropic or Gemini API key. These credentials are used only when counting selected text or the current file for the corresponding model family.

Claude setup

1. Create or select an API key in the Anthropic Console. A Claude.ai or Claude Code subscription login is not an API key, and API access may require billing to be enabled.
2. In VS Code, open the Command Palette with Ctrl+Shift+P or Cmd+Shift+P.
3. Run TokenFootprint: Configure Token Counting.
4. Select Anthropic Claude, paste the API key, and press Enter.
5. Run TokenFootprint: Estimate Selected Text or Estimate Current File and choose the Claude preset.
6. Confirm that the preview shows anthropic-count-api with high confidence.

TokenFootprint sends only the selected text or current-file content and selected model name to Anthropic's token-count endpoint. It does not generate a model response. To remove the key, run the configuration command again, select Claude, and submit an empty value.

Gemini setup

1. Create or select a key from the Google AI Studio API Keys page. The key must be able to access the Gemini API.
2. In VS Code, open the Command Palette with Ctrl+Shift+P or Cmd+Shift+P.
3. Run TokenFootprint: Configure Token Counting.
4. Select Google Gemini, paste the API key, and press Enter.
5. Run TokenFootprint: Estimate Selected Text or Estimate Current File and choose the Gemini preset.
6. Confirm that the preview shows gemini-count-api with high confidence.

TokenFootprint sends only the selected text or current-file content and selected model name to Gemini's countTokens endpoint. It does not generate a model response. To remove the key, run the configuration command again, select Gemini, and submit an empty value.

If no key is configured, the API rejects the request, or the selected model is unavailable, TokenFootprint falls back to the local character heuristic and labels the result as medium confidence.

Historical organization usage synchronization is not part of the current extension. For Codex, Claude/Cowork, Copilot, Gemini, or another assistant, use local Codex history, clipboard import, or manual import.

Local Codex chat usage

Run TokenFootprint: Import Local Codex Chat Usage to discover chats stored under ~/.codex/sessions. Select one or more chats, or choose All local Codex chats.

• The extension reads session_index.jsonl for chat titles and rollout JSONL files for session metadata, model, timestamps, and token_count events.
• It does not read ~/.codex/auth.json, send chat data anywhere, or analyze user/assistant message content.
• Codex token events are cumulative, so TokenFootprint uses only the latest total_token_usage snapshot per chat.
• Re-importing refreshes the existing chat record when its usage grows instead of creating a duplicate.
• Set tokenFootprint.autoImportLocalCodexHistory to true for a startup refresh.
• This depends on Codex's local storage format and gracefully skips chats that have no token-count event.

Local assistant chat usage

Run TokenFootprint: Import Local Assistant Chat Usage to estimate usage from readable local chat transcripts for GitHub Copilot, Cursor, or Claude Cowork.

• The command lets you choose the assistant, then select one, multiple, or all discovered local chats.
• Copilot/Cursor/Cowork local imports are not provider-reported token counts unless those products expose token totals in a supported local format.
• TokenFootprint estimates input and output tokens from readable transcript text, saves the records as actual-usage, and labels token confidence as medium with the heuristic method.
• The extension does not read auth files, scrape encrypted/local browser databases, call private APIs, or infer hidden provider usage.
• If no readable transcript files are found, the command offers Import Usage From Clipboard and Import AI Usage as fallback workflows.

Current local-history support:

Run locally

npm install
npm run compile

Run tests

npm test

The test suite uses Vitest and covers the local token estimator, footprint calculator, and display formatters. For a full beta-release check, run:

npm run compile
npm run lint
npm test

Then open this folder in VS Code and launch the extension:

1. Press F5 or run Debug: Start Debugging.
2. In the Extension Development Host, open a file.
3. Run commands from the Command Palette:
   • TokenFootprint: Estimate Selected Text
   • TokenFootprint: Estimate Current File
   • TokenFootprint: Import AI Usage
   • TokenFootprint: Import Usage From Clipboard
   • TokenFootprint: Import Local Codex Chat Usage
   • TokenFootprint: Open Dashboard
   • TokenFootprint: Delete All Local Data

Configure settings

Open VS Code Settings and search for TokenFootprint, or edit settings.json directly:

{
  "tokenFootprint.provider": "generic",
  "tokenFootprint.model": "generic-large",
  "tokenFootprint.waterMlPer1kTokensLow": 1,
  "tokenFootprint.waterMlPer1kTokensHigh": 20,
  "tokenFootprint.co2gPer1kTokensLow": 0.1,
  "tokenFootprint.co2gPer1kTokensHigh": 5,
  "tokenFootprint.carbonProfileMode": "profile",
  "tokenFootprint.defaultModelPreset": "openai",
  "tokenFootprint.autoImportLocalCodexHistory": false,
  "tokenFootprint.equivalentGridIntensityGPerKwh": 400,
  "tokenFootprint.equivalentLedBulbWatts": 9,
  "tokenFootprint.equivalentPhoneBatteryWh": 12.7,
  "tokenFootprint.equivalentWaterBottleMl": 500,
  "tokenFootprint.showStatusBar": true
}

The four equivalent* settings affect only dashboard interpretation. They do not change stored token, CO₂e, or water estimates.

Commands

Future roadmap

• Additional tokenizer revisions and model-family mappings
• Optional richer manual usage metadata display
• Prompt/context bloat detection
• Team reports
• JetBrains plugin
• Carbon intensity by region
• Water estimate methodology improvements
• Optional organization usage synchronization

License

MIT