# isabbir/tokeneconomizer architecture

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

- Interactive diagram: https://gitdiagram.com/isabbir/tokeneconomizer
- Repository: https://github.com/isabbir/tokeneconomizer

## Overview

TokenEconomizer is a coding-agent plugin that learns repository-specific cost-saving decisions across sessions. Its live path receives agent hooks, identifies repository state, applies micro-skills, tool pruning, and loop-guard interventions, then folds session evidence into future decisions. Agent-specific trace readers and cache-aware pricing support learning and reporting. The repository also contains an experimental benchmark suite with agent harnesses and task runners. Edges follow the supplied source references and excerpts or README descriptions; some experimental subsystems are represented at directory level because their implementation was not sampled.

Main entry points: [`tokeneconomizer/plugin/controller.py`](https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/controller.py) (Hook controller), [`tokeneconomizer/plugin/fold.py`](https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/fold.py) (Session fold), [`experiments/te_harness/swebench.py`](https://github.com/isabbir/tokeneconomizer/blob/main/experiments/te_harness/swebench.py) (SWE-Bench runner), [`tokeneconomizer/plugin/context.py`](https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/context.py) (Runtime context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_live["Live plugin"]
  node_hooks["Host adapters<br/>[hosts.py]"]
  node_controller["Hook controller<br/>[controller.py]"]
  node_context["Runtime context<br/>[context.py]"]
end

subgraph group_mechanisms["Cost mechanisms"]
  node_micro["Micro-skills"]
  node_fold["Session fold<br/>[fold.py]"]
  node_prune["Tool pruning"]
  node_settings["Agent settings<br/>[denylist.py]"]
  node_guard["Loop guard<br/>[turn.py]"]
  node_rules["Loop assessment<br/>[rules.py]"]
end

subgraph group_shared["Shared services"]
  node_repo[("Repository state<br/>[repos.py]")]
  node_storage["State paths<br/>[paths.py]"]
  node_trace["Session traces"]
  node_accounting["Cost accounting<br/>[accounting.py]"]
  node_pricing["Cache pricing<br/>[pricing.py]"]
end

subgraph group_experiments["Experiments"]
  node_spiral["Codex recovery<br/>[codex_spiral.py]"]
  node_workloads["Benchmark workloads<br/>[workloads.py]"]
  node_swe["SWE-Bench runner<br/>[swebench.py]"]
  node_codex["Codex harness<br/>[codex.py]"]
  node_copilot["Copilot harness<br/>[copilot.py]"]
  node_results["Experiment results"]
end

node_developer(("Developer"))
node_agent{{"Coding agent"}}

node_developer -->|"starts sessions"| node_agent
node_agent -->|"emits hooks"| node_hooks
node_hooks -->|"dispatches events"| node_controller
node_controller -->|"builds context"| node_context
node_context -->|"resolves repository"| node_repo
node_context -->|"selects state paths"| node_storage
node_controller -->|"injects learned facts"| node_micro
node_controller -->|"checks tool turns"| node_guard
node_guard -->|"assesses progress"| node_rules
node_agent -->|"writes session logs"| node_trace
node_controller -->|"starts session fold"| node_fold
node_fold -->|"reads session traces"| node_trace
node_fold -->|"updates learned facts"| node_micro
node_fold -->|"evaluates tool use"| node_prune
node_prune -->|"proposes removals"| node_settings
node_settings -->|"configures loaded tools"| node_agent
node_fold -->|"records cost"| node_accounting
node_accounting -->|"weights token usage"| node_pricing
node_workloads -.->|"supplies tasks"| node_swe
node_swe -->|"runs agent variant"| node_codex
node_swe -->|"runs agent variant"| node_copilot
node_swe -->|"uses Codex recovery"| node_spiral
node_codex -->|"accounts token cost"| node_pricing
node_copilot -->|"accounts token cost"| node_pricing
node_swe -.->|"produces measurements"| node_results

click node_hooks "https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/hosts.py"
click node_controller "https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/controller.py"
click node_context "https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/context.py"
click node_repo "https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/repos.py"
click node_storage "https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/paths.py"
click node_trace "https://github.com/isabbir/tokeneconomizer/tree/main/tokeneconomizer/trace"
click node_accounting "https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/accounting.py"
click node_pricing "https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/pricing.py"
click node_micro "https://github.com/isabbir/tokeneconomizer/tree/main/tokeneconomizer/microskills"
click node_fold "https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/fold.py"
click node_prune "https://github.com/isabbir/tokeneconomizer/tree/main/tokeneconomizer/toolprune"
click node_settings "https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/denylist.py"
click node_guard "https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/loopguard/turn.py"
click node_rules "https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/loopguard/rules.py"
click node_spiral "https://github.com/isabbir/tokeneconomizer/blob/main/experiments/te_bench/codex_spiral.py"
click node_workloads "https://github.com/isabbir/tokeneconomizer/blob/main/experiments/te_bench/workloads.py"
click node_swe "https://github.com/isabbir/tokeneconomizer/blob/main/experiments/te_harness/swebench.py"
click node_codex "https://github.com/isabbir/tokeneconomizer/blob/main/experiments/te_harness/codex.py"
click node_copilot "https://github.com/isabbir/tokeneconomizer/blob/main/experiments/te_harness/copilot.py"
click node_results "https://github.com/isabbir/tokeneconomizer/tree/main/experiments/scripts"

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_controller,node_context toneBlue
class node_micro,node_fold,node_prune,node_settings,node_guard,node_rules toneAmber
class node_repo,node_storage,node_trace,node_accounting,node_pricing toneMint
class node_spiral,node_workloads,node_swe,node_codex,node_copilot,node_results toneRose
class node_developer,node_agent toneIndigo
```

## Components

### Live plugin

- [Host adapters](https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/hosts.py): `tokeneconomizer/plugin/hosts.py`
- [Hook controller](https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/controller.py): `tokeneconomizer/plugin/controller.py`
- [Runtime context](https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/context.py): `tokeneconomizer/plugin/context.py`

### Cost mechanisms

- [Micro-skills](https://github.com/isabbir/tokeneconomizer/tree/main/tokeneconomizer/microskills): `tokeneconomizer/microskills`
- [Session fold](https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/fold.py): `tokeneconomizer/plugin/fold.py`
- [Tool pruning](https://github.com/isabbir/tokeneconomizer/tree/main/tokeneconomizer/toolprune): `tokeneconomizer/toolprune`
- [Agent settings](https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/denylist.py): `tokeneconomizer/plugin/denylist.py`
- [Loop guard](https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/loopguard/turn.py): `tokeneconomizer/loopguard/turn.py`
- [Loop assessment](https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/loopguard/rules.py): `tokeneconomizer/loopguard/rules.py`

### Shared services

- [Repository state](https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/repos.py): `tokeneconomizer/plugin/repos.py`
- [State paths](https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/paths.py): `tokeneconomizer/plugin/paths.py`
- [Session traces](https://github.com/isabbir/tokeneconomizer/tree/main/tokeneconomizer/trace): `tokeneconomizer/trace`
- [Cost accounting](https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/plugin/accounting.py): `tokeneconomizer/plugin/accounting.py`
- [Cache pricing](https://github.com/isabbir/tokeneconomizer/blob/main/tokeneconomizer/pricing.py): `tokeneconomizer/pricing.py`

### Experiments

- [Codex recovery](https://github.com/isabbir/tokeneconomizer/blob/main/experiments/te_bench/codex_spiral.py): `experiments/te_bench/codex_spiral.py`
- [Benchmark workloads](https://github.com/isabbir/tokeneconomizer/blob/main/experiments/te_bench/workloads.py): `experiments/te_bench/workloads.py`
- [SWE-Bench runner](https://github.com/isabbir/tokeneconomizer/blob/main/experiments/te_harness/swebench.py): `experiments/te_harness/swebench.py`
- [Codex harness](https://github.com/isabbir/tokeneconomizer/blob/main/experiments/te_harness/codex.py): `experiments/te_harness/codex.py`
- [Copilot harness](https://github.com/isabbir/tokeneconomizer/blob/main/experiments/te_harness/copilot.py): `experiments/te_harness/copilot.py`
- [Experiment results](https://github.com/isabbir/tokeneconomizer/tree/main/experiments/scripts): `experiments/scripts`

### Other components

- **Developer**
- **Coding agent**

## Connections

- Developer → Coding agent: starts sessions (evidence: `README.md`)
- Coding agent → Host adapters: emits hooks (evidence: `tokeneconomizer/plugin/hosts.py`)
- Host adapters → Hook controller: dispatches events (evidence: `tokeneconomizer/plugin/controller.py`)
- Hook controller → Runtime context: builds context (evidence: `tokeneconomizer/plugin/controller.py`)
- Runtime context → Repository state: resolves repository (evidence: `tokeneconomizer/plugin/context.py`)
- Runtime context → State paths: selects state paths (evidence: `tokeneconomizer/plugin/context.py`)
- Hook controller → Micro-skills: injects learned facts (evidence: `README.md`)
- Hook controller → Loop guard: checks tool turns (evidence: `tokeneconomizer/plugin/controller.py`)
- Loop guard → Loop assessment: assesses progress (evidence: `tokeneconomizer/loopguard/turn.py`)
- Coding agent → Session traces: writes session logs (evidence: `tokeneconomizer/trace/__init__.py`)
- Hook controller → Session fold: starts session fold (evidence: `tokeneconomizer/plugin/controller.py`)
- Session fold → Session traces: reads session traces (evidence: `tokeneconomizer/plugin/fold.py`)
- Session fold → Micro-skills: updates learned facts (evidence: `tokeneconomizer/plugin/fold.py`)
- Session fold → Tool pruning: evaluates tool use (evidence: `tokeneconomizer/plugin/fold.py`)
- Tool pruning → Agent settings: proposes removals (evidence: `tokeneconomizer/plugin/denylist.py`)
- Agent settings → Coding agent: configures loaded tools (evidence: `README.md`)
- Session fold → Cost accounting: records cost (evidence: `tokeneconomizer/plugin/fold.py`)
- Cost accounting → Cache pricing: weights token usage
- Benchmark workloads → SWE-Bench runner: supplies tasks
- SWE-Bench runner → Codex harness: runs agent variant (evidence: `experiments/te_harness/swebench.py`)
- SWE-Bench runner → Copilot harness: runs agent variant (evidence: `experiments/te_harness/swebench.py`)
- SWE-Bench runner → Codex recovery: uses Codex recovery (evidence: `experiments/te_harness/swebench.py`)
- Codex harness → Cache pricing: accounts token cost (evidence: `experiments/te_harness/codex.py`)
- Copilot harness → Cache pricing: accounts token cost (evidence: `experiments/te_harness/copilot.py`)
- SWE-Bench runner → Experiment results: produces measurements
