super-token-saver: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

Claude Code plugin (super-token-saver) that automates token/cache management, cost tracking, session control, and research-backed thinking patterns. No npm dependencies, zero config. Pure Node.js + Bash (two pure-JS image codecs are vendored under scripts/lib/vendor/, still no install step).

Architecture

hooks/          → Host-specific lifecycle registries plus their Bash commands and injected guidance.
skills/         → 5 SKILL.md-based skills invoked via /s-continue, /s-compact, /usage-view, /setup-statusline, /report-limit
scripts/        → Node.js processing pipeline (no npm, no build step)
                  + shrink-img.js — image downscaler for cheaper file attachments
scripts/lib/    → Shared utilities (pricing, cache paths, locale, window calculations)
scripts/lib/vendor/ → Vendored pure-JS third-party (pngjs MIT, jpeg-js BSD) for shrink-img; see THIRD-PARTY-NOTICES.md
locales/        → 23 language JSON files for dashboard UI strings

Data flow: transcripts (JSONL) → preprocess.js / analyze-usage.js → cached artifacts → skills consume them.

Two transcript sources, one pipeline

/s-continue and /s-compact read Claude Code AND Codex sessions. A Codex rollout is not parsed by a second parser — scripts/lib/codex-transcript.js rewrites it into the shape CC writes, one output line per input line, and everything downstream runs unchanged.

• Why line parity matters: every L{n} marker must still address the Codex original's line. A normalizer that dropped non-message rows would silently shift them.
• Key on payload.id, never session_id. In Codex session_id is the THREAD id and a spawned subagent inherits its parent's, so three files can carry the same one and overwrite each other's cache. Subagent rollouts are excluded from the list, as CC subtask transcripts already are.
• Codex compaction is translated into system/compact_boundary, so a compacted Codex session gets the same #0 pre-loss restore a compacted CC session gets.
• CODEX_HOME is honoured. Everything Codex lives under …-data/codex/: normalized copies in codex/.normalized/{projectHash}/, analysis cache and compact.txt in codex/{projectHash}/{sid}/. Claude Code stays at the root of the same base (the Bash statusline hook writes there). Get paths from cache-paths.forHost('codex'); the root getters and listProjects() are the Claude tree and never return codex. The one-time move of pre-split entries is migrateCodexSubdir() (it runs while .codex-normalized still exists at the root). Gate: node scripts/test-cache-host-split.js.
• Gate: node scripts/test-codex-adapter.js — synthetic fixture, no real transcript needed.
• Never read a whole Codex rollout into one string. A rollout can pass V8's max string length (~512 MB; a 694 MB one was measured) and the throw stops usage-view and restoration alike. Use forEachLine() in codex-transcript.js; its chunk-boundary cases are in the adapter test.
• The Claude path is byte-identical and must stay so; preprocess.js only changes its footer when --original is passed. Verify by diffing against git show main:scripts/preprocess.js.