# lugia19/claude-usage-extension architecture

> Architecture diagram of the GitHub repository lugia19/claude-usage-extension, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lugia19/claude-usage-extension
- Repository: https://github.com/lugia19/claude-usage-extension

## Overview

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`](https://github.com/lugia19/claude-usage-extension/blob/main/background.js) (Background), [`content-components/content_utils.js`](https://github.com/lugia19/claude-usage-extension/blob/main/content-components/content_utils.js) (Content utils), [`shared/dataclasses.js`](https://github.com/lugia19/claude-usage-extension/blob/main/shared/dataclasses.js) (Shared schema), [`bg-components/tokenManagement.js`](https://github.com/lugia19/claude-usage-extension/blob/main/bg-components/tokenManagement.js) (Token state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_packaging["Runtime packaging"]
  node_manifest_chrome["Chrome manifest"]
  node_manifest_firefox["Firefox manifest"]
  node_manifest_electron["Electron manifest"]
end

subgraph group_observation["Page observation"]
  node_rate_limit_watcher["Rate watcher<br/>injection"]
  node_webrequest_polyfill["Request polyfill<br/>injection"]
end

subgraph group_core["Extension core"]
  node_background["Background<br/>controller<br/>[background.js]"]
  node_token_management["Token state<br/>state service<br/>[tokenManagement.js]"]
  node_claude_api["Claude API<br/>api client<br/>[claude-api.js]"]
  node_electron_compat["Electron compat<br/>runtime adapter<br/>[electron-compat.js]"]
  node_bg_utils["BG utils<br/>helpers<br/>[utils.js]"]
end

subgraph group_ui["UI surfaces"]
  node_content_utils["Content utils<br/>dom bridge<br/>[content_utils.js]"]
  node_length_ui["Length UI<br/>overlay<br/>[length_ui.js]"]
  node_usage_ui["Usage UI<br/>overlay<br/>[usage_ui.js]"]
  node_notification_card["Status card<br/>overlay"]
  node_electron_receiver["Electron receiver<br/>bridge"]
  node_popup["Popup<br/>extension page<br/>[popup.js]"]
  node_debug["Debug page<br/>diagnostic page<br/>[debug.js]"]
end

subgraph group_shared["Shared model"]
  node_dataclasses["Shared schema<br/>data model<br/>[dataclasses.js]"]
  node_o200k_base["Tokenizer data<br/>encoding data<br/>[o200k_base.js]"]
  node_build_dataclasses["Dataclass build<br/>build script"]
end

node_manifest_chrome -->|"loads"| node_background
node_manifest_firefox -->|"loads"| node_background
node_manifest_electron -->|"loads"| node_background
node_background -->|"orchestrates"| node_token_management
node_background -->|"uses"| node_claude_api
node_background -->|"adapts"| node_electron_compat
node_background -->|"shares helpers"| node_bg_utils
node_rate_limit_watcher -->|"reports"| node_background
node_webrequest_polyfill -->|"signals"| node_background
node_content_utils -->|"messages"| node_background
node_length_ui -->|"renders via"| node_content_utils
node_usage_ui -->|"renders via"| node_content_utils
node_notification_card -->|"renders via"| node_content_utils
node_electron_receiver -->|"bridges"| node_background
node_popup -->|"reads model"| node_dataclasses
node_debug -->|"reads model"| node_dataclasses
node_build_dataclasses -->|"generates"| node_dataclasses
node_o200k_base -->|"powers"| node_token_management

click node_manifest_chrome "https://github.com/lugia19/claude-usage-extension/blob/main/manifest_chrome.json"
click node_manifest_firefox "https://github.com/lugia19/claude-usage-extension/blob/main/manifest_firefox.json"
click node_manifest_electron "https://github.com/lugia19/claude-usage-extension/blob/main/manifest_electron.json"
click node_rate_limit_watcher "https://github.com/lugia19/claude-usage-extension/blob/main/injections/rate-limit-watcher.js"
click node_webrequest_polyfill "https://github.com/lugia19/claude-usage-extension/blob/main/injections/webrequest-polyfill.js"
click node_background "https://github.com/lugia19/claude-usage-extension/blob/main/background.js"
click node_token_management "https://github.com/lugia19/claude-usage-extension/blob/main/bg-components/tokenManagement.js"
click node_claude_api "https://github.com/lugia19/claude-usage-extension/blob/main/bg-components/claude-api.js"
click node_electron_compat "https://github.com/lugia19/claude-usage-extension/blob/main/bg-components/electron-compat.js"
click node_bg_utils "https://github.com/lugia19/claude-usage-extension/blob/main/bg-components/utils.js"
click node_content_utils "https://github.com/lugia19/claude-usage-extension/blob/main/content-components/content_utils.js"
click node_length_ui "https://github.com/lugia19/claude-usage-extension/blob/main/content-components/length_ui.js"
click node_usage_ui "https://github.com/lugia19/claude-usage-extension/blob/main/content-components/usage_ui.js"
click node_notification_card "https://github.com/lugia19/claude-usage-extension/blob/main/content-components/notification_card.js"
click node_electron_receiver "https://github.com/lugia19/claude-usage-extension/blob/main/content-components/electron_reciever.js"
click node_popup "https://github.com/lugia19/claude-usage-extension/blob/main/popup.js"
click node_debug "https://github.com/lugia19/claude-usage-extension/blob/main/debug.js"
click node_dataclasses "https://github.com/lugia19/claude-usage-extension/blob/main/shared/dataclasses.js"
click node_o200k_base "https://github.com/lugia19/claude-usage-extension/blob/main/lib/o200k_base.js"
click node_build_dataclasses "https://github.com/lugia19/claude-usage-extension/blob/main/scripts/build-dataclasses.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_manifest_chrome,node_manifest_firefox,node_manifest_electron toneBlue
class node_rate_limit_watcher,node_webrequest_polyfill toneAmber
class node_background,node_token_management,node_claude_api,node_electron_compat,node_bg_utils toneMint
class node_content_utils,node_length_ui,node_usage_ui,node_notification_card,node_electron_receiver,node_popup,node_debug toneRose
class node_dataclasses,node_o200k_base,node_build_dataclasses toneIndigo
```

## Components

### Runtime packaging

Browser and Electron manifest variants

- [Chrome manifest](https://github.com/lugia19/claude-usage-extension/blob/main/manifest_chrome.json): manifest · Chrome extension packaging and permissions · `manifest_chrome.json`
- [Firefox manifest](https://github.com/lugia19/claude-usage-extension/blob/main/manifest_firefox.json): manifest · Firefox extension packaging and permissions · `manifest_firefox.json`
- [Electron manifest](https://github.com/lugia19/claude-usage-extension/blob/main/manifest_electron.json): manifest · Electron runtime packaging and permissions · `manifest_electron.json`

### Page observation

Scripts that watch Claude and bridge browser gaps

- [Rate watcher](https://github.com/lugia19/claude-usage-extension/blob/main/injections/rate-limit-watcher.js): injection · Watches Claude UI for quota and rate-limit state · `injections/rate-limit-watcher.js`
- [Request polyfill](https://github.com/lugia19/claude-usage-extension/blob/main/injections/webrequest-polyfill.js): injection · Normalizes network interception across runtimes · `injections/webrequest-polyfill.js`

### Extension core

Background orchestration and token/state management

- [Background](https://github.com/lugia19/claude-usage-extension/blob/main/background.js): controller · Central extension-wide orchestration · `background.js`
- [Token state](https://github.com/lugia19/claude-usage-extension/blob/main/bg-components/tokenManagement.js): state service · Usage tracking, persistence, and aggregation · `bg-components/tokenManagement.js`
- [Claude API](https://github.com/lugia19/claude-usage-extension/blob/main/bg-components/claude-api.js): api client · Anthropic API integration when a key is available · `bg-components/claude-api.js`
- [Electron compat](https://github.com/lugia19/claude-usage-extension/blob/main/bg-components/electron-compat.js): runtime adapter · Adapts background behavior for Electron · `bg-components/electron-compat.js`
- [BG utils](https://github.com/lugia19/claude-usage-extension/blob/main/bg-components/utils.js): helpers · Shared background-side helpers · `bg-components/utils.js`

### UI surfaces

Injected overlays and extension-facing screens

- [Content utils](https://github.com/lugia19/claude-usage-extension/blob/main/content-components/content_utils.js): dom bridge · DOM and message helpers for in-page scripts · `content-components/content_utils.js`
- [Length UI](https://github.com/lugia19/claude-usage-extension/blob/main/content-components/length_ui.js): overlay · In-page token length estimate display · `content-components/length_ui.js`
- [Usage UI](https://github.com/lugia19/claude-usage-extension/blob/main/content-components/usage_ui.js): overlay · In-page cost and usage display · `content-components/usage_ui.js`
- [Status card](https://github.com/lugia19/claude-usage-extension/blob/main/content-components/notification_card.js): overlay · Caching and status notifications on the chat page · `content-components/notification_card.js`
- [Electron receiver](https://github.com/lugia19/claude-usage-extension/blob/main/content-components/electron_reciever.js): bridge · Message bridge for the Electron setup · `content-components/electron_reciever.js`
- [Popup](https://github.com/lugia19/claude-usage-extension/blob/main/popup.js): extension page · Browser-action summary and settings surface · `popup.js`
- [Debug page](https://github.com/lugia19/claude-usage-extension/blob/main/debug.js): diagnostic page · Diagnostics for tracker behavior · `debug.js`

### Shared model

Data structures and tokenization assets

- [Shared schema](https://github.com/lugia19/claude-usage-extension/blob/main/shared/dataclasses.js): data model · Shared objects passed across extension contexts · `shared/dataclasses.js`
- [Tokenizer data](https://github.com/lugia19/claude-usage-extension/blob/main/lib/o200k_base.js): encoding data · Encoding tables for local token estimation · `lib/o200k_base.js`
- [Dataclass build](https://github.com/lugia19/claude-usage-extension/blob/main/scripts/build-dataclasses.js): build script · Keeps shared structures in sync · `scripts/build-dataclasses.js`

## Connections

- 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
