# ppgranger/token-saver architecture

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

- Interactive diagram: https://gitdiagram.com/ppgranger/token-saver
- Repository: https://github.com/ppgranger/token-saver

## Overview

Token-Saver locally compresses terminal output before it reaches an AI coding assistant. The main workflow intercepts command output, checks whether the command is eligible, routes it through a specialized processor, and returns compressed output; hooks provide automatic integration, while Codex can use an explicit wrapper. Separate capabilities include Delta comparisons across runs, savings tracking and statistics, and quality contracts. Edges reflect the supplied excerpts, SOURCE INDEX references, and README; some subsystem internals were not sampled.

Main entry points: [`src/engine.py`](https://github.com/ppgranger/token-saver/blob/main/src/engine.py) (Processor engine), [`src/delta.py`](https://github.com/ppgranger/token-saver/blob/main/src/delta.py) (Delta comparison), [`src/core.py`](https://github.com/ppgranger/token-saver/blob/main/src/core.py) (Compression core), [`src/cli.py`](https://github.com/ppgranger/token-saver/blob/main/src/cli.py) (CLI commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Assistant integrations"]
  node_hooks["Host hooks<br/>[platforms.py]"]
  node_wrap["Output wrapper<br/>[wrap.py]"]
  node_cli["CLI commands<br/>[cli.py]"]
end

subgraph group_compression["Compression runtime"]
  node_policy["Command policy<br/>[command_policy.py]"]
  node_core["Compression core<br/>[core.py]"]
  node_engine["Processor engine<br/>[engine.py]"]
  node_registry["Processor registry<br/>[registry.py]"]
  node_processors["Command processors"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_delta["Delta comparisons"]
  node_delta["Delta comparison<br/>[delta.py]"]
  node_diagnostics["Diagnostic comparison<br/>[diagnostics.py]"]
  node_delta_store[("Delta run store<br/>[delta_store.py]")]
  node_delta_cli["Delta commands<br/>[delta_cli.py]"]
end

subgraph group_insight["Tracking and quality"]
  node_tracker["Savings tracker<br/>[tracker.py]"]
  node_database[("Savings database<br/>[tracker.py]")]
  node_stats["Savings statistics<br/>[stats.py]"]
  node_quality["Quality contracts<br/>[quality_cli.py]"]
end

node_developer(("Developer"))
node_assistant["AI assistant"]
node_commands["Terminal commands"]

node_developer -->|"requests work"| node_assistant
node_assistant -->|"runs commands"| node_commands
node_commands -.->|"provides output"| node_hooks
node_hooks -.->|"compresses output"| node_core
node_commands -->|"pipes output"| node_wrap
node_wrap -->|"checks command"| node_policy
node_wrap -->|"requests compression"| node_core
node_core -->|"checks eligibility"| node_policy
node_core -->|"compresses output"| node_engine
node_engine -->|"loads processors"| node_registry
node_engine -->|"dispatches processing"| node_processors
node_engine -->|"reads settings"| node_config
node_cli -->|"benchmarks output"| node_engine
node_cli -->|"routes commands"| node_delta_cli
node_cli -->|"shows savings"| node_stats
node_delta_cli -->|"requests comparison"| node_delta
node_delta -->|"compares snapshots"| node_diagnostics
node_delta -->|"stores run history"| node_delta_store
node_delta -->|"checks redaction state"| node_engine
node_delta -->|"reads Delta settings"| node_config
node_tracker -->|"records savings"| node_database
node_stats -->|"reads totals"| node_tracker
node_quality -.->|"checks compression"| node_engine
node_hooks -->|"shows session savings"| node_tracker

click node_hooks "https://github.com/ppgranger/token-saver/blob/main/src/platforms.py"
click node_wrap "https://github.com/ppgranger/token-saver/blob/main/scripts/wrap.py"
click node_cli "https://github.com/ppgranger/token-saver/blob/main/src/cli.py"
click node_policy "https://github.com/ppgranger/token-saver/blob/main/src/command_policy.py"
click node_core "https://github.com/ppgranger/token-saver/blob/main/src/core.py"
click node_engine "https://github.com/ppgranger/token-saver/blob/main/src/engine.py"
click node_registry "https://github.com/ppgranger/token-saver/blob/main/src/registry.py"
click node_processors "https://github.com/ppgranger/token-saver/tree/main/src/processors"
click node_config "https://github.com/ppgranger/token-saver/blob/main/src/config.py"
click node_delta "https://github.com/ppgranger/token-saver/blob/main/src/delta.py"
click node_diagnostics "https://github.com/ppgranger/token-saver/blob/main/src/diagnostics.py"
click node_delta_store "https://github.com/ppgranger/token-saver/blob/main/src/delta_store.py"
click node_delta_cli "https://github.com/ppgranger/token-saver/blob/main/src/delta_cli.py"
click node_tracker "https://github.com/ppgranger/token-saver/blob/main/src/tracker.py"
click node_database "https://github.com/ppgranger/token-saver/blob/main/src/tracker.py"
click node_stats "https://github.com/ppgranger/token-saver/blob/main/src/stats.py"
click node_quality "https://github.com/ppgranger/token-saver/blob/main/src/quality_cli.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_hooks,node_wrap,node_cli toneBlue
class node_policy,node_core,node_engine,node_registry,node_processors,node_config toneAmber
class node_delta,node_diagnostics,node_delta_store,node_delta_cli toneMint
class node_tracker,node_database,node_stats,node_quality toneRose
class node_developer,node_assistant,node_commands toneIndigo
```

## Components

### Assistant integrations

- [Host hooks](https://github.com/ppgranger/token-saver/blob/main/src/platforms.py): `src/platforms.py`
- [Output wrapper](https://github.com/ppgranger/token-saver/blob/main/scripts/wrap.py): `scripts/wrap.py`
- [CLI commands](https://github.com/ppgranger/token-saver/blob/main/src/cli.py): `src/cli.py`

### Compression runtime

- [Command policy](https://github.com/ppgranger/token-saver/blob/main/src/command_policy.py): `src/command_policy.py`
- [Compression core](https://github.com/ppgranger/token-saver/blob/main/src/core.py): `src/core.py`
- [Processor engine](https://github.com/ppgranger/token-saver/blob/main/src/engine.py): `src/engine.py`
- [Processor registry](https://github.com/ppgranger/token-saver/blob/main/src/registry.py): `src/registry.py`
- [Command processors](https://github.com/ppgranger/token-saver/tree/main/src/processors): `src/processors`
- [Configuration](https://github.com/ppgranger/token-saver/blob/main/src/config.py): `src/config.py`

### Delta comparisons

- [Delta comparison](https://github.com/ppgranger/token-saver/blob/main/src/delta.py): `src/delta.py`
- [Diagnostic comparison](https://github.com/ppgranger/token-saver/blob/main/src/diagnostics.py): `src/diagnostics.py`
- [Delta run store](https://github.com/ppgranger/token-saver/blob/main/src/delta_store.py): `src/delta_store.py`
- [Delta commands](https://github.com/ppgranger/token-saver/blob/main/src/delta_cli.py): `src/delta_cli.py`

### Tracking and quality

- [Savings tracker](https://github.com/ppgranger/token-saver/blob/main/src/tracker.py): `src/tracker.py`
- [Savings database](https://github.com/ppgranger/token-saver/blob/main/src/tracker.py): `src/tracker.py`
- [Savings statistics](https://github.com/ppgranger/token-saver/blob/main/src/stats.py): `src/stats.py`
- [Quality contracts](https://github.com/ppgranger/token-saver/blob/main/src/quality_cli.py): `src/quality_cli.py`

### Other components

- **Developer**
- **AI assistant**
- **Terminal commands**

## Connections

- Developer → AI assistant: requests work
- AI assistant → Terminal commands: runs commands
- Terminal commands → Host hooks: provides output
- Host hooks → Compression core: compresses output
- Terminal commands → Output wrapper: pipes output
- Output wrapper → Command policy: checks command (evidence: `scripts/wrap.py`)
- Output wrapper → Compression core: requests compression (evidence: `scripts/wrap.py`)
- Compression core → Command policy: checks eligibility (evidence: `src/core.py`)
- Compression core → Processor engine: compresses output (evidence: `src/core.py`)
- Processor engine → Processor registry: loads processors (evidence: `src/engine.py`)
- Processor engine → Command processors: dispatches processing (evidence: `src/engine.py`)
- Processor engine → Configuration: reads settings (evidence: `src/engine.py`)
- CLI commands → Processor engine: benchmarks output (evidence: `src/cli.py`)
- CLI commands → Delta commands: routes commands (evidence: `src/cli.py`)
- CLI commands → Savings statistics: shows savings (evidence: `src/cli.py`)
- Delta commands → Delta comparison: requests comparison (evidence: `src/delta_cli.py`)
- Delta comparison → Diagnostic comparison: compares snapshots (evidence: `src/delta.py`)
- Delta comparison → Delta run store: stores run history (evidence: `src/delta.py`)
- Delta comparison → Processor engine: checks redaction state (evidence: `src/delta.py`)
- Delta comparison → Configuration: reads Delta settings (evidence: `src/delta.py`)
- Savings tracker → Savings database: records savings (evidence: `src/tracker.py`)
- Savings statistics → Savings tracker: reads totals (evidence: `src/stats.py`)
- Quality contracts → Processor engine: checks compression
- Host hooks → Savings tracker: shows session savings