# sakthimpr/claude-codex-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/sakthimpr/claude-codex-tracker
- Repository: https://github.com/sakthimpr/claude-codex-tracker

## Overview

Claude & Codex Tracker is a macOS menu-bar usage monitor. Its main workflow obtains authenticated usage from Claude and Codex, converts it into a shared snapshot, and displays limits, reset countdowns, and warnings in the native menu. An optional mobile branch pushes snapshots to Supabase for a static web view. The README documents the shared-file handoff and mobile flow; sampled source confirms the Python fetcher’s API requests and Supabase push. The web page’s read implementation was not sampled, so its Supabase read link is based on README documentation.

Main entry points: [`src/python/tracker_data.py`](https://github.com/sakthimpr/claude-codex-tracker/blob/main/src/python/tracker_data.py) (Usage fetcher), [`src/native/Launcher.swift`](https://github.com/sakthimpr/claude-codex-tracker/blob/main/src/native/Launcher.swift) (Menu-bar interface), [`web/index.html`](https://github.com/sakthimpr/claude-codex-tracker/blob/main/web/index.html) (Mobile usage page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["Usage collection"]
  node_fetcher["Usage fetcher<br/>[tracker_data.py]"]
  node_snapshot[("Shared snapshot")]
end

subgraph group_desktop["Mac app"]
  node_menubar["Menu-bar interface<br/>[Launcher.swift]"]
end

subgraph group_mobile["Mobile access"]
  node_supabase[("Supabase snapshot")]
  node_web["Mobile usage page<br/>[index.html]"]
end

node_user(("User"))
node_chrome["Chrome session"]
node_claude["Claude usage API"]
node_chatgpt["ChatGPT session and usage APIs"]
node_browser(("Web browser"))

node_fetcher -->|"reads cookies"| node_chrome
node_fetcher -->|"fetches usage"| node_claude
node_fetcher -->|"fetches usage"| node_chatgpt
node_fetcher -->|"writes snapshot"| node_snapshot
node_menubar -->|"reads snapshot"| node_snapshot
node_menubar -->|"starts and refreshes"| node_fetcher
node_user -->|"views and controls"| node_menubar
node_fetcher -->|"pushes snapshot"| node_supabase
node_web -->|"reads snapshot"| node_supabase
node_browser -->|"opens page"| node_web
node_user -->|"opens mobile view"| node_browser

click node_fetcher "https://github.com/sakthimpr/claude-codex-tracker/blob/main/src/python/tracker_data.py"
click node_menubar "https://github.com/sakthimpr/claude-codex-tracker/blob/main/src/native/Launcher.swift"
click node_web "https://github.com/sakthimpr/claude-codex-tracker/blob/main/web/index.html"

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_fetcher,node_snapshot,node_user,node_browser toneBlue
class node_menubar toneAmber
class node_supabase,node_web,node_claude,node_chatgpt toneMint
class node_chrome toneIndigo
```

## Components

### Usage collection

- [Usage fetcher](https://github.com/sakthimpr/claude-codex-tracker/blob/main/src/python/tracker_data.py): `src/python/tracker_data.py`
- **Shared snapshot**

### Mac app

- [Menu-bar interface](https://github.com/sakthimpr/claude-codex-tracker/blob/main/src/native/Launcher.swift): `src/native/Launcher.swift`

### Mobile access

- **Supabase snapshot**
- [Mobile usage page](https://github.com/sakthimpr/claude-codex-tracker/blob/main/web/index.html): `web/index.html`

### Other components

- **User**
- **Chrome session**
- **Claude usage API**
- **ChatGPT session and usage APIs**
- **Web browser**

## Connections

- Usage fetcher → Chrome session: reads cookies (evidence: `src/python/tracker_data.py`)
- Usage fetcher → Claude usage API: fetches usage (evidence: `src/python/tracker_data.py`)
- Usage fetcher → ChatGPT session and usage APIs: fetches usage (evidence: `src/python/tracker_data.py`)
- Usage fetcher → Shared snapshot: writes snapshot (evidence: `README.md`)
- Menu-bar interface → Shared snapshot: reads snapshot (evidence: `README.md`)
- Menu-bar interface → Usage fetcher: starts and refreshes (evidence: `README.md`)
- User → Menu-bar interface: views and controls (evidence: `README.md`)
- Usage fetcher → Supabase snapshot: pushes snapshot (evidence: `src/python/tracker_data.py`)
- Mobile usage page → Supabase snapshot: reads snapshot (evidence: `README.md`)
- Web browser → Mobile usage page: opens page (evidence: `README.md`)
- User → Web browser: opens mobile view (evidence: `README.md`)
