How lugia19/claude-usage-extension works
1. What this repo is
- A browser extension for claude.ai that estimates and tracks token usage across chats, files, projects, tools, and some integrations.
- The architecture is centered on observing the Claude web app, reconstructing context, calculating token counts, and presenting the result in-page and in the extension popup.
2. Runtime packaging
- There are separate manifests for Chrome, Firefox, and Electron (manifest_chrome.json, manifest_firefox.json, manifest_electron.json).
- This is a single codebase with runtime-specific permission/API differences, not a standalone web app.
3. Page instrumentation layer
- injections/ contains scripts that run as close to the page as possible:
- rate-limit-watcher.js watches the Claude UI for quota/rate-limit state.
- webrequest-polyfill.js fills gaps where network interception behavior differs by browser/runtime.
- These scripts are the closest boundary to the actual Claude app and are used to extract state that is not exposed through normal extension APIs.
4. Content-script / in-page UI layer
- content-components/ is responsible for interacting with the Claude page and rendering overlays.
- UI pieces include length_ui.js, usage_ui.js, and notification_card.js, which correspond to the “length”, “cost”, estimate, and caching/status indicators shown on the chat page.
- content_utils.js provides DOM/message helpers, and electron_reciever.js bridges messages in the Electron setup.
5. Background orchestration
- background.js is the central controller for extension-wide behavior.
- bg-components/ holds the background-side subsystems:
- tokenManagement.js for usage/token state and persistence.
- claude-api.js for Claude/Anthropic API interactions when an API key is available.
- electron-compat.js for adapting extension behavior to the Electron launcher/client.
- utils.js for shared background helpers.
- This layer is where cross-tab, cross-page, and long-lived state is managed.
6. Token calculation path
- The extension can calculate token usage in two ways:
- via Anthropic’s API if the user supplies a key,
- or locally using gpt-tokenizer.
- lib/o200k_base.js provides the tokenizer encoding data used for local estimation.
- This tokenization subsystem is the core computational boundary of the project.
7. Shared data model
- shared/dataclasses.js is a shared schema layer for the objects passed between background, content, popup, and injected scripts.
- scripts/build-dataclasses.js suggests those structures are generated or kept in sync from a source definition, reducing drift between extension contexts.
8. State, identity, and sync
- The README notes that the extension fetches the user’s organization ID from Claude and uses Firebase to synchronize usage data across devices.
- That means the extension has both local persistence and a remote sync boundary, with Firebase acting as the cross-device storage layer.
- Token/organization identity is therefore part of the state model, not just the UI.
9. Extension UI surfaces
- popup.html / popup.js provide the browser-action popup, likely for summary/status/settings.
- debug.html / debug.js are a diagnostic surface for inspecting tracker behavior.
- tracker-styles.css is the shared styling for the injected on-page UI.
10. External dependencies and scope limits
- The project depends on the Claude web app’s DOM and conversation structure, so it is tightly coupled to Claude UI behavior.
- It explicitly handles limitations where full context is not exposed, such as web search results and much of research.
- The main architecture implication is that accuracy depends on what can be observed in the browser, with fallback heuristics where Claude does not expose full inputs.
11. End-to-end data flow
- Page/injection scripts observe Claude activity → content scripts extract and render usage-relevant details → background logic aggregates and persists state → popup/debug surfaces read the same shared state → Firebase sync propagates organization-linked usage across devices.
- The repo is therefore organized around a clear split between page observation, state computation, UI rendering, and cross-device persistence.
Main entry points: background.js Background · content_utils.js Content utils · dataclasses.js Shared schema · tokenManagement.js Token state
Components 20
Runtime packaging
Browser and Electron manifest variants
- Chrome manifest · Chrome extension packaging and permissions
manifest_chrome.json - Firefox manifest · Firefox extension packaging and permissions
manifest_firefox.json - Electron manifest · Electron runtime packaging and permissions
manifest_electron.json
Page observation
Scripts that watch Claude and bridge browser gaps
- Rate watcher · Watches Claude UI for quota and rate-limit state
injections/rate-limit-watcher.js - Request polyfill · Normalizes network interception across runtimes
injections/webrequest-polyfill.js
Extension core
Background orchestration and token/state management
- Background · Central extension-wide orchestration
background.js - Token state · Usage tracking, persistence, and aggregation
bg-components/tokenManagement.js - Claude API · Anthropic API integration when a key is available
bg-components/claude-api.js - Electron compat · Adapts background behavior for Electron
bg-components/electron-compat.js - BG utils · Shared background-side helpers
bg-components/utils.js
UI surfaces
Injected overlays and extension-facing screens
- Content utils · DOM and message helpers for in-page scripts
content-components/content_utils.js - Length UI · In-page token length estimate display
content-components/length_ui.js - Usage UI · In-page cost and usage display
content-components/usage_ui.js - Status card · Caching and status notifications on the chat page
content-components/notification_card.js - Electron receiver · Message bridge for the Electron setup
content-components/electron_reciever.js - Popup · Browser-action summary and settings surface
popup.js - Debug page · Diagnostics for tracker behavior
debug.js
Shared model
Data structures and tokenization assets
- Shared schema · Shared objects passed across extension contexts
shared/dataclasses.js - Tokenizer data · Encoding tables for local token estimation
lib/o200k_base.js - Dataclass build · Keeps shared structures in sync
scripts/build-dataclasses.js
Connections 18
- Chrome manifest → Background: loads · Chrome runtime loads the core background controller
- Firefox manifest → Background: loads · Firefox runtime loads the core background controller
- Electron manifest → Background: loads · Electron runtime loads the core background controller
- Background → Token state: orchestrates · Background delegates usage persistence and aggregation
- Background → Claude API: uses · Background can call Anthropic APIs for token estimation
- Background → Electron compat: adapts · Background routes runtime-specific behavior through Electron compat
- Background → BG utils: shares helpers · Background uses common helper utilities
- Rate watcher → Background: reports · Page watcher forwards Claude UI state to background
- Request polyfill → Background: signals · Network interception gaps are normalized for background handling
- Content utils → Background: messages · Content layer exchanges data with background state
- Length UI → Content utils: renders via · Length overlay uses content DOM/message helpers
- Usage UI → Content utils: renders via · Usage overlay uses content DOM/message helpers
- Status card → Content utils: renders via · Status card uses content DOM/message helpers
- Electron receiver → Background: bridges · Electron bridge relays messages into background orchestration
- Popup → Shared schema: reads model · Popup consumes shared extension data shapes
- Debug page → Shared schema: reads model · Debug surface inspects shared extension data shapes
- Dataclass build → Shared schema: generates · Build script keeps shared dataclasses synchronized
- Tokenizer data → Token state: powers · Tokenizer data supports local token counting