# alexgreensh/token-optimizer architecture

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

- Interactive diagram: https://gitdiagram.com/alexgreensh/token-optimizer
- Repository: https://github.com/alexgreensh/token-optimizer

## Overview

Token Optimizer is a cross-platform assistant plugin that reduces context waste, preserves session work, and reports usage and savings. The main workflow is: an assistant session triggers hooks; measurement and optimization features act on tool/context events; compaction checkpoints and restores continuity; and audits or dashboards summarize results. Platform-specific integrations extend that workflow, while OpenCode and OpenClaw provide substantial native plugin implementations. Evidence is limited to the README and supplied excerpts/SOURCE INDEX; some subsystem links are therefore omitted rather than inferred.

Main entry points: [`hooks/posttooluse_runner.py`](https://github.com/alexgreensh/token-optimizer/blob/main/hooks/posttooluse_runner.py) (Tool Hooks), [`skills/token-optimizer/scripts/measure.py`](https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/measure.py) (Measure & Audit), [`hooks/sessionstart_runner.py`](https://github.com/alexgreensh/token-optimizer/blob/main/hooks/sessionstart_runner.py) (Session Hooks), [`opencode/src/index.ts`](https://github.com/alexgreensh/token-optimizer/blob/main/opencode/src/index.ts) (OpenCode Plugin)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hooks["Hook Runtime"]
  node_session_hooks["Session Hooks"]
  node_tool_hooks["Tool Hooks"]
end

subgraph group_features["Optimization Features"]
  node_read_cache["Read Cache<br/>[read_cache.py]"]
  node_compression["Output Compression"]
  node_checkpoint["Checkpoint &amp; Restore<br/>[measure.py]"]
  node_continuity["Session Continuity"]
  node_context_intel["Context Intelligence<br/>[context_intel.py]"]
  node_routing["Model Routing<br/>[routing_advisor.py]"]
  node_detectors["Waste Detectors<br/>[registry.py]"]
end

subgraph group_insights["Measurement &amp; Insights"]
  node_measure["Measure &amp; Audit<br/>[measure.py]"]
  node_storage[("Session State<br/>[session_store.py]")]
  node_dashboard["Dashboard &amp; Reports<br/>[dashboard.py]"]
end

subgraph group_platforms["Platform Integrations"]
  node_opencode["OpenCode Plugin<br/>[index.ts]"]
  node_opencode_store[("OpenCode Session Store<br/>[session-store.ts]")]
  node_fresh_nudge["Fresh Session Nudge"]
  node_openclaw["OpenClaw Plugin<br/>[index.ts]"]
  node_openclaw_parser["Session Parser<br/>[session-parser.ts]"]
  node_openclaw_models["Model Pricing<br/>[pricing.ts]"]
  node_openclaw_dashboard["OpenClaw Dashboard<br/>[dashboard.ts]"]
  node_pi["Pi Extension<br/>[token-optimizer.ts]"]
end

node_user(("Assistant User"))
node_assistant(("Coding Assistant"))

node_user -->|"uses"| node_assistant
node_assistant -->|"fires session events"| node_session_hooks
node_assistant -->|"fires tool events"| node_tool_hooks
node_session_hooks -->|"dispatches"| node_measure
node_session_hooks -->|"initializes cache"| node_read_cache
node_tool_hooks -->|"invokes"| node_read_cache
node_tool_hooks -->|"invokes"| node_measure
node_tool_hooks -->|"invokes"| node_compression
node_tool_hooks -->|"invokes"| node_context_intel
node_tool_hooks -->|"uses"| node_storage
node_measure -.->|"records session state"| node_storage
node_measure -.->|"produces reports"| node_dashboard
node_assistant -->|"compacts context"| node_checkpoint
node_checkpoint -->|"restores work"| node_continuity
node_assistant -->|"receives nudges"| node_routing
node_assistant -->|"analyzes behavior"| node_detectors
node_opencode -->|"creates session store"| node_opencode_store
node_opencode -.->|"registers nudge"| node_fresh_nudge
node_openclaw -->|"parses sessions"| node_openclaw_parser
node_openclaw_parser -->|"calculates cost"| node_openclaw_models
node_openclaw -->|"builds dashboard"| node_openclaw_dashboard
node_assistant -->|"runs extension"| node_pi

click node_session_hooks "https://github.com/alexgreensh/token-optimizer/blob/main/hooks/sessionstart_runner.py"
click node_tool_hooks "https://github.com/alexgreensh/token-optimizer/blob/main/hooks/posttooluse_runner.py"
click node_measure "https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/measure.py"
click node_read_cache "https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/read_cache.py"
click node_compression "https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/bash_compress_hook.py"
click node_checkpoint "https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/measure.py"
click node_continuity "https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/lean_resume_carry.py"
click node_context_intel "https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/context_intel.py"
click node_routing "https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/routing_advisor.py"
click node_detectors "https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/detectors/registry.py"
click node_storage "https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/session_store.py"
click node_dashboard "https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/_measure/dashboard.py"
click node_opencode "https://github.com/alexgreensh/token-optimizer/blob/main/opencode/src/index.ts"
click node_opencode_store "https://github.com/alexgreensh/token-optimizer/blob/main/opencode/src/storage/session-store.ts"
click node_fresh_nudge "https://github.com/alexgreensh/token-optimizer/blob/main/opencode/src/nudges/fresh-session-nudge.ts"
click node_openclaw "https://github.com/alexgreensh/token-optimizer/blob/main/openclaw/src/index.ts"
click node_openclaw_parser "https://github.com/alexgreensh/token-optimizer/blob/main/openclaw/src/session-parser.ts"
click node_openclaw_models "https://github.com/alexgreensh/token-optimizer/blob/main/openclaw/src/pricing.ts"
click node_openclaw_dashboard "https://github.com/alexgreensh/token-optimizer/blob/main/openclaw/src/dashboard.ts"
click node_pi "https://github.com/alexgreensh/token-optimizer/blob/main/pi/extensions/token-optimizer.ts"

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_session_hooks,node_tool_hooks,node_user toneBlue
class node_read_cache,node_compression,node_checkpoint,node_continuity,node_context_intel,node_routing,node_detectors toneAmber
class node_measure,node_storage,node_dashboard toneMint
class node_opencode,node_opencode_store,node_fresh_nudge,node_openclaw,node_openclaw_parser,node_openclaw_models,node_openclaw_dashboard,node_pi toneRose
class node_assistant toneIndigo
```

## Components

### Hook Runtime

- [Session Hooks](https://github.com/alexgreensh/token-optimizer/blob/main/hooks/sessionstart_runner.py): `hooks/sessionstart_runner.py`
- [Tool Hooks](https://github.com/alexgreensh/token-optimizer/blob/main/hooks/posttooluse_runner.py): `hooks/posttooluse_runner.py`

### Optimization Features

- [Read Cache](https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/read_cache.py): `skills/token-optimizer/scripts/read_cache.py`
- [Output Compression](https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/bash_compress_hook.py): `skills/token-optimizer/scripts/bash_compress_hook.py`
- [Checkpoint & Restore](https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/measure.py): `skills/token-optimizer/scripts/measure.py`
- [Session Continuity](https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/lean_resume_carry.py): `skills/token-optimizer/scripts/lean_resume_carry.py`
- [Context Intelligence](https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/context_intel.py): `skills/token-optimizer/scripts/context_intel.py`
- [Model Routing](https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/routing_advisor.py): `skills/token-optimizer/scripts/routing_advisor.py`
- [Waste Detectors](https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/detectors/registry.py): `skills/token-optimizer/scripts/detectors/registry.py`

### Measurement & Insights

- [Measure & Audit](https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/measure.py): `skills/token-optimizer/scripts/measure.py`
- [Session State](https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/session_store.py): `skills/token-optimizer/scripts/session_store.py`
- [Dashboard & Reports](https://github.com/alexgreensh/token-optimizer/blob/main/skills/token-optimizer/scripts/_measure/dashboard.py): `skills/token-optimizer/scripts/_measure/dashboard.py`

### Platform Integrations

- [OpenCode Plugin](https://github.com/alexgreensh/token-optimizer/blob/main/opencode/src/index.ts): `opencode/src/index.ts`
- [OpenCode Session Store](https://github.com/alexgreensh/token-optimizer/blob/main/opencode/src/storage/session-store.ts): `opencode/src/storage/session-store.ts`
- [Fresh Session Nudge](https://github.com/alexgreensh/token-optimizer/blob/main/opencode/src/nudges/fresh-session-nudge.ts): `opencode/src/nudges/fresh-session-nudge.ts`
- [OpenClaw Plugin](https://github.com/alexgreensh/token-optimizer/blob/main/openclaw/src/index.ts): `openclaw/src/index.ts`
- [Session Parser](https://github.com/alexgreensh/token-optimizer/blob/main/openclaw/src/session-parser.ts): `openclaw/src/session-parser.ts`
- [Model Pricing](https://github.com/alexgreensh/token-optimizer/blob/main/openclaw/src/pricing.ts): `openclaw/src/pricing.ts`
- [OpenClaw Dashboard](https://github.com/alexgreensh/token-optimizer/blob/main/openclaw/src/dashboard.ts): `openclaw/src/dashboard.ts`
- [Pi Extension](https://github.com/alexgreensh/token-optimizer/blob/main/pi/extensions/token-optimizer.ts): `pi/extensions/token-optimizer.ts`

### Other components

- **Assistant User**
- **Coding Assistant**

## Connections

- Assistant User → Coding Assistant: uses (evidence: `README.md`)
- Coding Assistant → Session Hooks: fires session events (evidence: `README.md`)
- Coding Assistant → Tool Hooks: fires tool events (evidence: `README.md`)
- Session Hooks → Measure & Audit: dispatches (evidence: `hooks/sessionstart_runner.py`)
- Session Hooks → Read Cache: initializes cache (evidence: `hooks/sessionstart_runner.py`)
- Tool Hooks → Read Cache: invokes (evidence: `hooks/posttooluse_runner.py`)
- Tool Hooks → Measure & Audit: invokes (evidence: `hooks/posttooluse_runner.py`)
- Tool Hooks → Output Compression: invokes (evidence: `hooks/posttooluse_runner.py`)
- Tool Hooks → Context Intelligence: invokes (evidence: `hooks/posttooluse_runner.py`)
- Tool Hooks → Session State: uses
- Measure & Audit → Session State: records session state
- Measure & Audit → Dashboard & Reports: produces reports
- Coding Assistant → Checkpoint & Restore: compacts context (evidence: `README.md`)
- Checkpoint & Restore → Session Continuity: restores work (evidence: `README.md`)
- Coding Assistant → Model Routing: receives nudges (evidence: `README.md`)
- Coding Assistant → Waste Detectors: analyzes behavior (evidence: `README.md`)
- OpenCode Plugin → OpenCode Session Store: creates session store (evidence: `opencode/src/index.ts`)
- OpenCode Plugin → Fresh Session Nudge: registers nudge (evidence: `opencode/src/index.ts`)
- OpenClaw Plugin → Session Parser: parses sessions (evidence: `openclaw/src/index.ts`)
- Session Parser → Model Pricing: calculates cost (evidence: `openclaw/src/session-parser.ts`)
- OpenClaw Plugin → OpenClaw Dashboard: builds dashboard (evidence: `openclaw/src/index.ts`)
- Coding Assistant → Pi Extension: runs extension (evidence: `README.md`)
