# nadimtuhin/claude-token-optimizer architecture

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

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

## Overview

Claude Token Optimizer is a project-facing CLI for reducing and managing the documentation Claude Code loads into context. Users invoke commands through the CLI: initialize a framework-aware documentation layout, measure token usage, then audit or maintain it with compression, pruning, diffs, and live monitoring. It also manages Claude Code hook templates and refreshes project content. The excerpts show CLI dispatch and several command-to-library calls; README documents other command capabilities. Dashed edges mark README-described flows whose implementation details were not sampled.

Main entry points: [`src/cli.js`](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/cli.js) (Command router), [`src/commands/init.js`](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/init.js) (Initialize docs), [`src/lib/tokenizer.js`](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/lib/tokenizer.js) (Token counter), [`src/commands/hooks.js`](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/hooks.js) (Hook manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry"]
  node_cli["Command router<br/>[cli.js]"]
end

subgraph group_setup["Project setup"]
  node_init["Initialize docs<br/>[init.js]"]
  node_frameworks["Framework detection<br/>[frameworks.js]"]
  node_update["Update content<br/>[update.js]"]
end

subgraph group_maintenance["Token maintenance"]
  node_measure["Measure tokens<br/>[measure.js]"]
  node_audit["Structure audit<br/>[audit.js]"]
  node_compress["Compress docs<br/>[compress.js]"]
  node_prune["Prune stale docs<br/>[prune.js]"]
  node_diff["Token comparison<br/>[diff.js]"]
  node_watch["Live dashboard<br/>[watch.js]"]
end

subgraph group_hooks["Hook management"]
  node_hooks["Hook manager<br/>[hooks.js]"]
  node_hooktemplates["Hook scripts"]
end

subgraph group_shared["Shared libraries"]
  node_scanner["Auto-load scanner<br/>[scanner.js]"]
  node_tokenizer["Token counter<br/>[tokenizer.js]"]
end

node_user(("Project user"))
node_claudecode(("Claude Code"))
node_projectfiles["Project docs"]

node_user -->|"runs command"| node_cli
node_cli -->|"dispatches"| node_init
node_cli -->|"dispatches"| node_measure
node_cli -->|"dispatches"| node_audit
node_cli -->|"dispatches"| node_compress
node_cli -->|"dispatches"| node_prune
node_cli -->|"dispatches"| node_diff
node_cli -->|"dispatches"| node_watch
node_cli -->|"dispatches"| node_hooks
node_cli -->|"dispatches"| node_update
node_init -->|"detects framework"| node_frameworks
node_init -->|"installs hooks"| node_hooks
node_measure -->|"scans files"| node_scanner
node_measure -->|"counts tokens"| node_tokenizer
node_audit -->|"counts tokens"| node_tokenizer
node_audit -->|"checks ignore rules"| node_frameworks
node_audit -->|"builds missing docs"| node_init
node_compress -->|"counts tokens"| node_tokenizer
node_prune -->|"counts tokens"| node_tokenizer
node_diff -->|"counts tokens"| node_tokenizer
node_watch -->|"counts tokens"| node_tokenizer
node_measure -.->|"reads docs"| node_projectfiles
node_compress -.->|"rewrites docs"| node_projectfiles
node_prune -->|"archives sections"| node_projectfiles
node_diff -.->|"compares versions"| node_projectfiles
node_watch -->|"monitors changes"| node_projectfiles
node_hooks -->|"copies scripts"| node_hooktemplates
node_hooks -.->|"configures hooks"| node_claudecode
node_update -->|"appends sections"| node_init
node_update -->|"refreshes hooks"| node_hooks
node_init -->|"writes docs"| node_projectfiles

click node_cli "https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/cli.js"
click node_init "https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/init.js"
click node_frameworks "https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/lib/frameworks.js"
click node_measure "https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/measure.js"
click node_scanner "https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/lib/scanner.js"
click node_audit "https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/audit.js"
click node_compress "https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/compress.js"
click node_prune "https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/prune.js"
click node_diff "https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/diff.js"
click node_watch "https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/watch.js"
click node_hooks "https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/hooks.js"
click node_hooktemplates "https://github.com/nadimtuhin/claude-token-optimizer/tree/main/templates/hooks"
click node_update "https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/update.js"
click node_tokenizer "https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/lib/tokenizer.js"

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_cli,node_user toneBlue
class node_init,node_frameworks,node_update toneAmber
class node_measure,node_audit,node_compress,node_prune,node_diff,node_watch toneMint
class node_hooks,node_hooktemplates toneRose
class node_scanner,node_tokenizer,node_claudecode,node_projectfiles toneIndigo
```

## Components

### CLI entry

- [Command router](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/cli.js): `src/cli.js`

### Project setup

- [Initialize docs](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/init.js): `src/commands/init.js`
- [Framework detection](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/lib/frameworks.js): `src/lib/frameworks.js`
- [Update content](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/update.js): `src/commands/update.js`

### Token maintenance

- [Measure tokens](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/measure.js): `src/commands/measure.js`
- [Structure audit](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/audit.js): `src/commands/audit.js`
- [Compress docs](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/compress.js): `src/commands/compress.js`
- [Prune stale docs](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/prune.js): `src/commands/prune.js`
- [Token comparison](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/diff.js): `src/commands/diff.js`
- [Live dashboard](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/watch.js): `src/commands/watch.js`

### Hook management

- [Hook manager](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/commands/hooks.js): `src/commands/hooks.js`
- [Hook scripts](https://github.com/nadimtuhin/claude-token-optimizer/tree/main/templates/hooks): `templates/hooks`

### Shared libraries

- [Auto-load scanner](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/lib/scanner.js): `src/lib/scanner.js`
- [Token counter](https://github.com/nadimtuhin/claude-token-optimizer/blob/main/src/lib/tokenizer.js): `src/lib/tokenizer.js`

### Other components

- **Project user**
- **Claude Code**
- **Project docs**

## Connections

- Project user → Command router: runs command (evidence: `src/cli.js`)
- Command router → Initialize docs: dispatches (evidence: `src/cli.js`)
- Command router → Measure tokens: dispatches (evidence: `src/cli.js`)
- Command router → Structure audit: dispatches (evidence: `src/cli.js`)
- Command router → Compress docs: dispatches (evidence: `src/cli.js`)
- Command router → Prune stale docs: dispatches (evidence: `src/cli.js`)
- Command router → Token comparison: dispatches (evidence: `src/cli.js`)
- Command router → Live dashboard: dispatches (evidence: `src/cli.js`)
- Command router → Hook manager: dispatches (evidence: `src/cli.js`)
- Command router → Update content: dispatches (evidence: `src/cli.js`)
- Initialize docs → Framework detection: detects framework (evidence: `src/commands/init.js`)
- Initialize docs → Hook manager: installs hooks (evidence: `src/commands/init.js`)
- Measure tokens → Auto-load scanner: scans files (evidence: `src/commands/measure.js`)
- Measure tokens → Token counter: counts tokens (evidence: `src/commands/measure.js`)
- Structure audit → Token counter: counts tokens (evidence: `src/commands/audit.js`)
- Structure audit → Framework detection: checks ignore rules (evidence: `src/commands/audit.js`)
- Structure audit → Initialize docs: builds missing docs (evidence: `src/commands/audit.js`)
- Compress docs → Token counter: counts tokens (evidence: `src/commands/compress.js`)
- Prune stale docs → Token counter: counts tokens (evidence: `src/commands/prune.js`)
- Token comparison → Token counter: counts tokens (evidence: `src/commands/diff.js`)
- Live dashboard → Token counter: counts tokens (evidence: `src/commands/watch.js`)
- Measure tokens → Project docs: reads docs (evidence: `src/commands/measure.js`)
- Compress docs → Project docs: rewrites docs (evidence: `README.md`)
- Prune stale docs → Project docs: archives sections (evidence: `README.md`)
- Token comparison → Project docs: compares versions (evidence: `README.md`)
- Live dashboard → Project docs: monitors changes (evidence: `README.md`)
- Hook manager → Hook scripts: copies scripts (evidence: `src/commands/hooks.js`)
- Hook manager → Claude Code: configures hooks (evidence: `README.md`)
- Update content → Initialize docs: appends sections (evidence: `src/commands/update.js`)
- Update content → Hook manager: refreshes hooks (evidence: `src/commands/update.js`)
- Initialize docs → Project docs: writes docs (evidence: `src/commands/init.js`)
