1. Resolve measure.py path (works for both skill and plugin installs):

MEASURE_PY=""
for f in "$HOME/.claude/skills/token-optimizer/scripts/measure.py" \
         "$HOME/.claude/plugins/cache"/*/token-optimizer/*/skills/token-optimizer/scripts/measure.py; do
  [ -f "$f" ] && MEASURE_PY="$f" && break
done
[ -z "$MEASURE_PY" ] && { echo "[Error] measure.py not found. Is Token Optimizer installed?"; exit 1; }
echo "Using: $MEASURE_PY"

$MEASURE_PY

1. Detect context window size: Check if

   TOKEN_OPTIMIZER_CONTEXT_SIZE

   env var is already set. If not:
   • Check for

     ANTHROPIC_API_KEY

     env var (indicates API usage, possibly 1M context)
   • If API key found, ask the user: "You appear to be using the API. Do you have 1M token context (e.g. Opus)? If so I'll calibrate for 1M instead of 200K."
   • If they confirm 1M,

     export TOKEN_OPTIMIZER_CONTEXT_SIZE=1000000

     for this session
   • If no API key or they say no, default is 200K (no action needed) Keep this quick, one question max. Don't belabor it.
2. Quick pre-check (detect minimal setups): Run

   python3 $MEASURE_PY report

   . If estimated controllable tokens < 1,000 and no CLAUDE.md exists, short-circuit:

   [Token Optimizer] Your setup is already minimal (~X tokens overhead).
   Focus on behavioral changes instead: /compact at 70%, /clear between topics,
   default agents to haiku, batch requests.

3. Backup everything first (before touching anything):

BACKUP_DIR="$HOME/.claude/_backups/token-optimizer-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BACKUP_DIR"
chmod 700 "$BACKUP_DIR"
cp ~/.claude/CLAUDE.md "$BACKUP_DIR/" 2>/dev/null || true
cp ~/.claude/settings.json "$BACKUP_DIR/" 2>/dev/null || true
cp -r ~/.claude/commands "$BACKUP_DIR/" 2>/dev/null || true

4. **Create coordination folder**:
```bash
COORD_PATH=$(mktemp -d /tmp/token-optimizer-XXXXXXXXXX)
[ -d "$COORD_PATH" ] || { echo "[Error] Failed to create coordination folder. Check /tmp permissions."; exit 1; }
mkdir -p "$COORD_PATH"/{audit,analysis,plan,verification}

1. Check SessionEnd hook (first-time setup, skips silently if already installed):

python3 $MEASURE_PY check-hook

• If exit 0: hook is already installed (includes plugin auto-install), skip entirely and proceed to Phase 1.
• If exit 1 (manual/script install users only): explain and offer to install:

[Token Optimizer] Want to track your token usage over time?

Right now, the optimizer can audit your setup. But to track *trends* (which
skills you actually use, how your context fills up day to day, model costs),
it needs to save a small log after each Claude Code session.

What this does:
- When you close a Claude Code session, it automatically saves usage stats
- Takes ~2 seconds, runs silently in the background, then stops
- All data stays on your machine (stored in ~/.claude/_backups/token-optimizer/)
- Powers the Trends and Health tabs in your dashboard

Without this, the dashboard only shows a snapshot from right now.
With it, you get a living history that updates every session.

Remove anytime by running: python3 measure.py setup-hook --uninstall
Or manually: delete the SessionEnd entry from ~/.claude/settings.json

1. Install it (run

   measure.py setup-hook --dry-run

   first to show the diff, then confirm and run

   measure.py setup-hook

   )
2. Show me the JSON first (run

   measure.py setup-hook --dry-run

   and stop)
3. Skip for now

measure.py collect

1. Offer the bookmarkable dashboard URL (macOS and Windows. Linux lands in a future release; skip silently there.):
   Run BOTH probes in one pass, then branch on the combination:

python3 "$MEASURE_PY" daemon-status
python3 "$MEASURE_PY" daemon-consent --get

daemon-status

DAEMON_RUNNING

DAEMON_FOREIGN

DAEMON_NOT_RUNNING

daemon-consent --get

{}

{"prompted": true, "consent": true|false, ...}

{}

consent: true

consent: false

DAEMON_RUNNING

setup-daemon --uninstall

DAEMON_FOREIGN

netstat -ano | findstr :24842

lsof -i :24842

DAEMON_NOT_RUNNING

measure.py setup-daemon

[Token Optimizer] Want a bookmarkable dashboard URL?

URL:  http://localhost:24842/token-optimizer
File: ~/.claude/_backups/token-optimizer/dashboard.html  (always works)

The URL stays bookmarked and auto-updates after every session.
The file is the fallback — same content, just harder to reach.

What installing the URL does:
- Runs a tiny web server on your machine (~2MB memory)
- Starts automatically at login, restarts if it ever stops
- Only reachable from this machine (localhost), not the network
- Serves just this one dashboard file, nothing else

Remove anytime: python3 measure.py setup-daemon --uninstall

1. Install it (default — write consent FIRST so we never end up with a running daemon the user said no to, then install: run

   measure.py daemon-consent --set yes

   , then

   measure.py setup-daemon

   )
2. Skip (run

   measure.py daemon-consent --set no

   )

file://

--user

1. Check Smart Compaction hooks (v2.0, first-time setup, skips silently if already installed; plugin users get these automatically):

python3 $MEASURE_PY setup-smart-compact --status

• If all 4 hooks installed (includes plugin auto-install): skip entirely.
• If partially or not installed (manual/script install users only): explain and offer to install:

[Token Optimizer] New in v2.0: Smart Compaction

Auto-compaction destroys working memory. Smart Compaction captures your
session state (decisions, modified files, errors, agent state) BEFORE
compaction fires, then restores it afterward.

What this does:
- Before compaction: saves a structured checkpoint of your session state
- After compaction: injects recovered context so you don't lose your place
- On session end: captures state for potential pickup in next session
- All checkpoints stored locally (~/.claude/token-optimizer/checkpoints/)

Remove anytime: python3 measure.py setup-smart-compact --uninstall

1. Install it (run

   measure.py setup-smart-compact --dry-run

   first, then confirm and run

   measure.py setup-smart-compact

   )
2. Show me the JSON first (run

   measure.py setup-smart-compact --dry-run

   and stop)
3. Skip for now

[Token Optimizer Initialized] Backup: $BACKUP_DIR | Coordination: $COORD_PATH

1. Install hooks (PreCompact + SessionStart + Stop + SessionEnd):

undefined

Show the user the dry-run diff first. Explain:
- **PreCompact**: Captures decisions, modified files, errors, agent state to a checkpoint file before compaction runs
- **SessionStart** (matcher: compact): Injects recovered context after compaction completes
- **Stop**: Captures checkpoint when session ends normally
- **SessionEnd**: Captures checkpoint on /clear or session death

All hooks call `measure.py` directly (pure Python, no shell scripts). Composes safely with any existing hooks the user already has.

2. **Generate Compact Instructions** (project-specific compaction guidance):
```bash
python3 $MEASURE_PY compact-instructions

.claude/settings.json

compactInstructions

1. Verify installation:

python3 $MEASURE_PY setup-smart-compact --status

/compact

~/.claude/token-optimizer/checkpoints/

• TOKEN_OPTIMIZER_CHECKPOINT_FILES

  : Max checkpoint files kept (default: 10)

• TOKEN_OPTIMIZER_CHECKPOINT_TTL

  : Seconds before checkpoint expires for restore (default: 300)

• TOKEN_OPTIMIZER_CHECKPOINT_RETENTION_DAYS

  : Days to keep old checkpoints (default: 7)

• TOKEN_OPTIMIZER_RELEVANCE_THRESHOLD

  : Keyword overlap for new-session restore (default: 0.3)

python3 $MEASURE_PY quality current

• Stale reads (25%): Files read then later edited (re-read would be fresher)
• Bloated results (25%): Large tool outputs never referenced again
• Duplicates (15%): Repeated system reminders or injected content
• Compaction depth (15%): Number of compactions (each = information loss)
• Decision density (10%): Ratio of substantive exchanges to overhead
• Agent efficiency (10%): Dispatch cost vs useful result size

• 85-100: Excellent, clean session
• 70-84: Good, some bloat, smart compaction would help
• 50-69: Degraded, significant waste,

  /compact

  with checkpoint recommended
• <50: Critical, heavy rot, consider

  /clear

  with checkpoint

report

snapshot

compare

dashboard

• measure.py dashboard

  : Generates a standalone persistent dashboard at

  ~/.claude/_backups/token-optimizer/dashboard.html

  with Trends and Health tabs. Auto-regenerated by the SessionEnd hook.

• measure.py setup-daemon

  : Installs a macOS launchd daemon serving the dashboard at

  http://localhost:24842/token-optimizer

  . Starts on login, restarts on crash. Remove with

  --uninstall

  .

• measure.py trends [--days N] [--json]

  : Scans all JSONL session logs across projects. Shows which skills you actually use, subagent patterns, model mix, and cross-references against installed skills to surface unused ones. Default: last 30 days.

• measure.py health

  : Detects running Claude Code sessions, checks their version against installed, flags stale/zombie processes, and shows automated Claude-related processes.
• Both

  trends

  and

  health

  data appear as interactive tabs in the dashboard (standalone or full audit).

• measure.py quality [session-id|current]

  : Analyzes session content quality. Scores stale reads, bloated results, duplicates, compaction depth, decision density, agent efficiency. Returns composite 0-100 score with actionable breakdown.

• measure.py setup-smart-compact [--dry-run] [--status] [--uninstall]

  : Installs/manages the Smart Compaction hook system (PreCompact capture + SessionStart restore + Stop/SessionEnd checkpoints). Use

  --dry-run

  to preview,

  --status

  to check,

  --uninstall

  to remove.

• measure.py compact-capture

  : Called by PreCompact/Stop/SessionEnd hooks. Parses JSONL transcript, extracts decisions/files/errors/agent state, writes checkpoint to

  ~/.claude/token-optimizer/checkpoints/

  . Not intended for direct user invocation.

• measure.py compact-restore

  : Called by SessionStart hook (matcher: compact). Reads most recent checkpoint and injects recovered context. Not intended for direct user invocation.

• measure.py compact-instructions [--json]

  : Generates project-specific Compact Instructions based on CLAUDE.md and session patterns. Output is text the user adds to their

  .claude/settings.json

  compactInstructions field.

• measure.py list-checkpoints [--cwd PATH] [--max-age MINUTES]

  : Lists session checkpoints with age, trigger type, and quality scores. Useful for debugging the smart compact system.

• Agent timeout/failure: If an audit agent fails, note the gap and continue. Do not retry. The synthesis agent handles missing files gracefully.
• Model unavailable: Fall back one tier: opus -> sonnet -> haiku. Log which model was actually used.
• No CLAUDE.md found: Report 0 tokens, skip to skills audit.
• No skills directory: Report 0 tokens, note as "fresh setup."
• measure.py not found: Fall back to manual estimation (line count x 15 for prose, x 8 for YAML).
• Coordination folder write failure: Abort and report the error. Do not proceed without audit storage.
• Backup write failure: If

  ls "$BACKUP_DIR"

  shows 0 files after Phase 0 backup, warn user and ask whether to proceed without backup. Do not silently continue.
• mktemp failure: If

  COORD_PATH

  directory does not exist after creation, print error and abort. Check /tmp permissions.
• Synthesis agent failure: If

  analysis/optimization-plan.md

  is missing or empty after Phase 2, present raw audit files to user instead. Do not proceed to Phase 4 blindly.
• Verification agent failure: If Phase 5 agent fails, fall back to running

  measure.py snapshot after

  +

  measure.py compare

  directly in the shell.
• Snapshot file corrupt: If

  compare

  fails with a JSON error, re-run

  measure.py snapshot [label]

  to regenerate the corrupt file.
• Stale snapshot warning: If the "before" snapshot is >24h old when running

  compare

  , a warning is printed. Consider re-taking it for accurate results.

Guard against path traversal in crafted backup filenames

Backups are never automatically deleted. They accumulate in `~/.claude/_backups/`.

---

• Quantify everything (X tokens, Y%)
• Create backups before any changes (

  ~/.claude/_backups/

  )
• Ask user before implementing
• Never delete files, always archive
• Check dependencies before archiving (skills, MCP servers, deny rules can break other tools)
• Warn about side effects: deny rules block ALL tools, MCP removal breaks dependent skills, skill archival breaks @imports
• Prefer project-level deny rules over global (easier to debug, less blast radius)
• Use appropriate models (with fallbacks) for each task
• Show before/after diffs
• Frame savings as context budget (% of context window), not dollar amounts