save-tokens · git:20260409.df814ae · 2026-04-09 · sha256 57773bcb4346b2b2
save-tokens git:20260409.df814aeA
Immutable. This exact content never changes and is served at /api/v1/blob/57773bcb4346b2b2.
No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_2n43f7etj3cygdc2/57773bcb4346b2b2a571e5e8f58bfde1b17613cfbc503bb3e51baeced16fa3b1.json
Then /plugin install save-tokens@markdownregistry-2n43f7etj3cygdc2 in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.
--- name: save-tokens description: Token-saving session automation — statusline, prompt guard, precompact handoffs, session rotation, and handoff commands for Claude Code --- ## Activation This skill triggers when editing save-tokens files: - `src/commands/save-tokens.js` - `src/lib/save-tokens.js` - `src/templates/hooks/save-tokens*.sh` - `src/templates/hooks/save-tokens.mjs` - `src/templates/commands/save-handoff.md` - `src/templates/commands/resume-handoff*.md` - `tests/save-tokens*.test.js` Keywords: save-tokens, handoff, statusline, prompt-guard, precompact, session rotation, token warning --- You are working on **save-tokens** — the feature that installs Claude Code hooks and commands to warn about token usage, auto-save handoffs before compaction, and support session rotation. ## Key Files - `src/commands/save-tokens.js` — Main command: interactive or `--recommended` install, `--remove` uninstall, installs hooks + commands + settings - `src/lib/save-tokens.js` — Config defaults (`DEFAULT_SAVE_TOKENS_CONFIG`), `buildSaveTokensConfig()`, `buildSaveTokensSettings()`, `buildSaveTokensGitignore()`, `buildSaveTokensReadme()` - `src/templates/hooks/save-tokens.mjs` — Runtime hook: `runStatusline()`, `runPromptGuard()`, `runPrecompact()`, telemetry recording, handoff saving/pruning - `src/templates/hooks/save-tokens-statusline.sh` — Shell wrapper for statusline hook - `src/templates/hooks/save-tokens-prompt-guard.sh` — Shell wrapper for prompt guard hook - `src/templates/hooks/save-tokens-precompact.sh` — Shell wrapper for precompact hook - `src/templates/commands/save-handoff.md` — Slash command to save a rich handoff summary - `src/templates/commands/resume-handoff-latest.md` — Slash command to resume from most recent handoff - `src/templates/commands/resume-handoff.md` — Slash command to list and pick a handoff to resume ## Key Concepts - **Claude-only feature:** Save-tokens hooks and statusline only work with Claude Code. Config is stored in `.aspens.json` under `saveTokens`. - **Three hook entry points:** Shell wrappers (`*.sh`) read stdin, resolve project dir, and call `save-tokens.mjs` with a subcommand (`statusline`, `prompt-guard`, `precompact`). - **Statusline:** Records Claude context telemetry to `.aspens/sessions/claude-context.json` on every status update. Displays `save-tokens Xk/Yk` in the Claude status bar. - **Prompt guard:** Checks token count against `warnAtTokens` (175k default) and `compactAtTokens` (200k default). Above compact threshold: saves a handoff and recommends fresh session. Above warn threshold: suggests `/save-handoff`. - **Precompact:** Auto-saves a handoff before Claude compaction when `saveHandoff` is enabled. - **Handoff files:** Saved to `.aspens/sessions/<timestamp>-claude-handoff.md` with task summary, token count, latest prompt, transcript excerpt. Pruned to keep max 10. - **Telemetry:** `recordClaudeContextTelemetry()` sums input/output/cache tokens from Claude's `context_window.current_usage`. Stale telemetry (>5 min) is ignored. - **Config thresholds:** `warnAtTokens` and `compactAtTokens` can be `Number.MAX_SAFE_INTEGER` as disabled sentinel. - **Settings merge:** `buildSaveTokensSettings()` produces `statusLine` + `hooks` config. Merged into existing `settings.json` via `mergeSettings()` which treats save-tokens hooks as aspens-managed. - **`--recommended` install:** Called standalone or from `doc init --recommended`. Installs hooks, commands, sessions dir, settings — no prompts. - **`--remove` uninstall:** Removes hook files (including legacy `.mjs` variants), commands, cleans settings.json entries, nulls `saveTokens` in `.aspens.json`. ## Critical Rules - **Shell wrappers resolve project dir from script location** — `SCRIPT_DIR` → `PROJECT_DIR` via `cd "$SCRIPT_DIR/../.." && pwd`. `ASPENS_PROJECT_DIR` env var overrides `CLAUDE_PROJECT_DIR`. - **Config validation in `target.js`** — `isValidSaveTokensConfig()` validates shape, types, and threshold ordering. Invalid config causes `readConfig()` to return `null`. - **`writeConfig` preserves feature config** — `saveTokens` is preserved across `writeConfig` calls unless explicitly set to `null`. - **Handoff pruning** — `pruneOldHandoffs()` keeps newest 10, deletes older. Only touches `*-handoff.md` files. - **Sessions dir gitignored** — `.aspens/sessions/.gitignore` excludes everything except `.gitignore` and `README.md`. - **Settings backup** — First install creates `.claude/settings.json.bak` if settings exist and no backup exists yet. - **`doc init --recommended`** — Calls `installSaveTokensRecommended()` from `save-tokens.js`, also installs agents and doc-sync git hook. ## References - **Impact integration:** `src/lib/impact.js` — `evaluateSaveTokensHealth()` validates installed state --- **Last Updated:** 2026-04-09