# koureasstavros/aitoolsessiontracker architecture

> Architecture diagram of the GitHub repository koureasstavros/aitoolsessiontracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/koureasstavros/aitoolsessiontracker
- Repository: https://github.com/koureasstavros/aitoolsessiontracker

## Overview

AI Tool Session Tracker is a local, read-only browser app for exploring AI coding-agent sessions from provider transcripts and OpenTelemetry data. Users select a provider and inspect sessions, turns, invocations, context, tool activity, token usage, costs, and aggregate statistics. The large viewer module is the documented app entry point; provider modules parse distinct local formats, while shared modules handle OTEL ingestion, source selection, pricing, and configuration storage. The supplied excerpts do not expose the full UI-to-parser orchestration, so only documented or indexed relationships are shown.

Main entry points: [`session_token_viewer.py`](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/session_token_viewer.py) (Session Viewer), [`src/common/source_archive.py`](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/source_archive.py) (Source Archives), [`src/common/source_otel.py`](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/source_otel.py) (OTEL Receiver), [`src/providers/anthropic_claude_local_provider.py`](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/anthropic_claude_local_provider.py) (Claude Local)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Viewer"]
  node_viewer["Session Viewer"]
end

subgraph group_local["Local Providers"]
  node_claude_local["Claude Local"]
  node_devin_local["Devin Local"]
  node_copilot_local["Copilot Local"]
  node_antigravity_local["Antigravity Local"]
  node_codex_local["Codex Local"]
  node_cursor_local["Cursor Local"]
  node_m365_local["M365 Copilot"]
end

subgraph group_otel["OpenTelemetry"]
  node_otel_receiver["OTEL Receiver<br/>[source_otel.py]"]
  node_claude_otel["Claude OTEL"]
  node_copilot_otel["Copilot OTEL"]
  node_codex_otel["Codex OTEL"]
end

subgraph group_shared["Shared Services"]
  node_pricing["Model Pricing<br/>[model_costs.py]"]
  node_model_mapping["Model Mapping<br/>[model_mapping.py]"]
  node_source_routing["Source Routing<br/>[source_routing.py]"]
  node_source_paths["Provider Paths<br/>[source_paths.py]"]
  node_archive["Source Archives<br/>[source_archive.py]"]
  node_database[("SQLite Storage")]
end

node_user(("User"))
node_otel_service(("OTEL Client"))

node_user -->|"explores sessions"| node_viewer
node_viewer -->|"loads sessions"| node_claude_local
node_viewer -->|"loads sessions"| node_devin_local
node_viewer -->|"loads sessions"| node_copilot_local
node_viewer -->|"loads sessions"| node_antigravity_local
node_viewer -->|"loads sessions"| node_codex_local
node_viewer -->|"loads sessions"| node_cursor_local
node_viewer -->|"loads sessions"| node_m365_local
node_otel_service -->|"sends OTLP"| node_otel_receiver
node_viewer -->|"reads OTEL sessions"| node_otel_receiver
node_otel_receiver -->|"uses adapter"| node_claude_otel
node_otel_receiver -->|"uses adapter"| node_copilot_otel
node_otel_receiver -->|"uses adapter"| node_codex_otel
node_otel_receiver -->|"stores content"| node_database
node_viewer -->|"calculates costs"| node_pricing
node_viewer -->|"maps models"| node_model_mapping
node_viewer -->|"selects source"| node_source_routing
node_claude_local -->|"finds storage"| node_source_paths
node_copilot_local -->|"finds storage"| node_source_paths
node_claude_local -->|"archives sources"| node_archive
node_devin_local -->|"archives sources"| node_archive
node_copilot_local -->|"archives sources"| node_archive
node_antigravity_local -->|"archives sources"| node_archive
node_codex_local -->|"archives sources"| node_archive
node_cursor_local -->|"archives sources"| node_archive
node_m365_local -->|"archives sources"| node_archive
node_source_routing -->|"persists settings"| node_database

click node_viewer "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/session_token_viewer.py"
click node_claude_local "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/anthropic_claude_local_provider.py"
click node_devin_local "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/cognition_devin_local_provider.py"
click node_copilot_local "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/github_copilot_local_provider.py"
click node_antigravity_local "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/google_antigravity_local_provider.py"
click node_codex_local "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/openai_codex_local_provider.py"
click node_cursor_local "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/xai_cursor_local_provider.py"
click node_m365_local "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/m365_copilot_local_provider.py"
click node_otel_receiver "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/source_otel.py"
click node_claude_otel "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/anthropic_claude_otel_provider.py"
click node_copilot_otel "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/github_copilot_otel_provider.py"
click node_codex_otel "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/openai_codex_otel_provider.py"
click node_pricing "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/model_costs.py"
click node_model_mapping "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/model_mapping.py"
click node_source_routing "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/source_routing.py"
click node_source_paths "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/source_paths.py"
click node_archive "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/source_archive.py"
click node_database "https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/tracker_database.py"

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_viewer,node_user,node_otel_service toneBlue
class node_claude_local,node_devin_local,node_copilot_local,node_antigravity_local,node_codex_local,node_cursor_local,node_m365_local toneAmber
class node_otel_receiver,node_claude_otel,node_copilot_otel,node_codex_otel toneMint
class node_pricing,node_model_mapping,node_source_routing,node_source_paths,node_archive,node_database toneRose
```

## Components

### Viewer

- [Session Viewer](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/session_token_viewer.py): `session_token_viewer.py`

### Local Providers

- [Claude Local](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/anthropic_claude_local_provider.py): `src/providers/anthropic_claude_local_provider.py`
- [Devin Local](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/cognition_devin_local_provider.py): `src/providers/cognition_devin_local_provider.py`
- [Copilot Local](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/github_copilot_local_provider.py): `src/providers/github_copilot_local_provider.py`
- [Antigravity Local](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/google_antigravity_local_provider.py): `src/providers/google_antigravity_local_provider.py`
- [Codex Local](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/openai_codex_local_provider.py): `src/providers/openai_codex_local_provider.py`
- [Cursor Local](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/xai_cursor_local_provider.py): `src/providers/xai_cursor_local_provider.py`
- [M365 Copilot](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/m365_copilot_local_provider.py): `src/providers/m365_copilot_local_provider.py`

### OpenTelemetry

- [OTEL Receiver](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/source_otel.py): `src/common/source_otel.py`
- [Claude OTEL](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/anthropic_claude_otel_provider.py): `src/providers/anthropic_claude_otel_provider.py`
- [Copilot OTEL](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/github_copilot_otel_provider.py): `src/providers/github_copilot_otel_provider.py`
- [Codex OTEL](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/providers/openai_codex_otel_provider.py): `src/providers/openai_codex_otel_provider.py`

### Shared Services

- [Model Pricing](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/model_costs.py): `src/common/model_costs.py`
- [Model Mapping](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/model_mapping.py): `src/common/model_mapping.py`
- [Source Routing](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/source_routing.py): `src/common/source_routing.py`
- [Provider Paths](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/source_paths.py): `src/common/source_paths.py`
- [Source Archives](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/source_archive.py): `src/common/source_archive.py`
- [SQLite Storage](https://github.com/koureasstavros/aitoolsessiontracker/blob/main/src/common/tracker_database.py): `src/common/tracker_database.py`

### Other components

- **User**
- **OTEL Client**

## Connections

- User → Session Viewer: explores sessions (evidence: `README.md`)
- Session Viewer → Claude Local: loads sessions (evidence: `session_token_viewer.py`)
- Session Viewer → Devin Local: loads sessions (evidence: `session_token_viewer.py`)
- Session Viewer → Copilot Local: loads sessions (evidence: `session_token_viewer.py`)
- Session Viewer → Antigravity Local: loads sessions (evidence: `session_token_viewer.py`)
- Session Viewer → Codex Local: loads sessions (evidence: `session_token_viewer.py`)
- Session Viewer → Cursor Local: loads sessions (evidence: `session_token_viewer.py`)
- Session Viewer → M365 Copilot: loads sessions (evidence: `session_token_viewer.py`)
- OTEL Client → OTEL Receiver: sends OTLP (evidence: `README.md`)
- Session Viewer → OTEL Receiver: reads OTEL sessions (evidence: `session_token_viewer.py`)
- OTEL Receiver → Claude OTEL: uses adapter (evidence: `src/common/source_otel.py`)
- OTEL Receiver → Copilot OTEL: uses adapter (evidence: `src/common/source_otel.py`)
- OTEL Receiver → Codex OTEL: uses adapter (evidence: `src/common/source_otel.py`)
- OTEL Receiver → SQLite Storage: stores content (evidence: `src/common/source_otel.py`)
- Session Viewer → Model Pricing: calculates costs (evidence: `session_token_viewer.py`)
- Session Viewer → Model Mapping: maps models (evidence: `session_token_viewer.py`)
- Session Viewer → Source Routing: selects source (evidence: `session_token_viewer.py`)
- Claude Local → Provider Paths: finds storage (evidence: `src/providers/anthropic_claude_local_provider.py`)
- Copilot Local → Provider Paths: finds storage (evidence: `src/providers/github_copilot_local_provider.py`)
- Claude Local → Source Archives: archives sources (evidence: `src/providers/anthropic_claude_local_provider.py`)
- Devin Local → Source Archives: archives sources (evidence: `src/providers/cognition_devin_local_provider.py`)
- Copilot Local → Source Archives: archives sources (evidence: `src/providers/github_copilot_local_provider.py`)
- Antigravity Local → Source Archives: archives sources (evidence: `src/providers/google_antigravity_local_provider.py`)
- Codex Local → Source Archives: archives sources (evidence: `src/providers/openai_codex_local_provider.py`)
- Cursor Local → Source Archives: archives sources (evidence: `src/providers/xai_cursor_local_provider.py`)
- M365 Copilot → Source Archives: archives sources (evidence: `src/providers/m365_copilot_local_provider.py`)
- Source Routing → SQLite Storage: persists settings (evidence: `src/common/source_routing.py`)