TokenSave

Cross-agent quota pacing and model-tier routing for agent apps.

TokenSave helps you avoid both sides of the reset-window problem: running out of usage too early, or leaving useful capacity unused. It keeps account usage quota separate from the current session context window, asks for fresh data instead of reusing stale screenshots, and recommends low / medium / high model tiers based on task risk.

What It Does

• Divides remaining usage across days until reset.
• Shows the remaining-percentage floor where balanced work should stop today.
• Keeps a configurable reserve, defaulting to 15%.
• Interprets context-window pressure separately from account quota.
• Routes work to low, medium, high, or specialist tiers.
• Uses compact multiple-choice questions when fresh data or work-division preferences are missing.
• Can parse Codex local session JSONL token-count events when available.

Install

Codex Skill

Build the Codex skill package:

node scripts/build-codex-skill.mjs

Then copy dist/codex-skill/tokensave into your Codex skills folder.

On Windows:

xcopy /E /I /Y dist\codex-skill\tokensave %USERPROFILE%\.codex\skills\tokensave

On macOS/Linux:

mkdir -p ~/.codex/skills
cp -R dist/codex-skill/tokensave ~/.codex/skills/tokensave

Use it in Codex with:

$tokensave

Claude Code

Copy the Claude skill package into your personal or project skill directory:

mkdir -p ~/.claude/skills
cp -R packages/claude-code/skills/tokensave ~/.claude/skills/tokensave

Use it in Claude Code with:

/tokensave

For current Claude Code values, run /usage first. Use /context when TokenSave needs current context-window pressure. Then reply with only what is missing, for example:

weekly=82%, reset=aug 2
weekly=82%, context=20%, tasks: fix tests

Cursor

Copy the Cursor rule into a project:

mkdir -p .cursor/rules
cp packages/cursor/tokensave.mdc .cursor/rules/tokensave.mdc

Invoke it by asking Cursor about usage pacing, model routing, or TokenSave.

Windsurf

Copy the Windsurf rule into a project:

mkdir -p .windsurf/rules
cp packages/windsurf/tokensave.md .windsurf/rules/tokensave.md

Invoke it by asking Cascade about TokenSave, quota pacing, or model routing.

ChatGPT Or Generic Agents

Use packages/chatgpt/TOKENSAVE_CUSTOM_INSTRUCTIONS.md or packages/generic/TOKENSAVE_PROMPT.md as reusable prompt instructions.

CLI Examples

node scripts/tokensave.mjs questions
node scripts/tokensave.mjs auto
node scripts/tokensave.mjs today --current-remaining 94 --context-used 28 --reset 2026-08-05
node scripts/tokensave.mjs route "debug auth refresh race condition"
node scripts/tokensave.mjs codex-sessions

Data And Privacy

TokenSave does not require account credentials. It works from visible percentages, user-provided values, local client-state files, local Codex session logs when you choose to scan them, and Claude Code /usage or /context output supplied by the user.

Do not commit .tokensave/, local logs, screenshots, or generated usage ledgers. This repository's .gitignore excludes local TokenSave state by default.

Verification

Run:

node scripts/smoke-test.mjs

The smoke suite validates pacing, routing, stale-data refusal, reset-day handling, Codex session parsing, and package validation.

Name

The project is named TokenSave because it is short, memorable, and matches how users describe the pain: saving limited agent usage. The exact purpose is broader than saving tokens, so the subtitle is the precise positioning: cross-agent quota pacing and model-tier routing.