Save Tokens

Without context, coding agents burn through usage searching for files, reading code they don’t need, and rebuilding things that already exist. With aspens, they know your codebase structure before writing a single line — fewer tool calls, fewer wasted reads, fewer rewrites.

The save-tokens command

npx aspens save-tokens --recommended

This installs a set of session management tools that help reduce token usage in Claude Code:

• Token tracking — monitors token usage across the session
• Warning prompts — alerts when approaching context limits
• Session rotation — helps manage long-running sessions
• Statusline — shows token usage in the Claude Code UI
• Precompact handoffs — prepares session state before context compression

What gets installed

.claude/
  hooks/
    save-tokens-statusline.sh    # Token usage in the Claude Code UI
    save-tokens-prompt-guard.sh  # Warning when approaching context limits
    save-tokens-precompact.sh    # Prepares session state before compression
  commands/
    save-handoff.md              # Save session state for resuming later
    resume-handoff.md            # Resume from a saved handoff
    resume-handoff-latest.md     # Resume from the most recent handoff

Plus entries in .claude/settings.json to wire up the hooks.

Configuration

Save-tokens configuration is stored in .aspens.json:

{
  "saveTokens": {
    "warnAtTokens": 175000,
    "compactAtTokens": 200000
  }
}

• warnAtTokens — token count that triggers a usage warning
• compactAtTokens — token count that triggers compaction suggestion

Install and remove

# Install with defaults (no prompts)
npx aspens save-tokens --recommended

# Remove all save-tokens files and settings
npx aspens save-tokens --remove

Health checks

aspens doc impact includes save-tokens health in its report:

Save tokens: healthy
  Hooks: installed
  Commands: installed
  Settings: configured

If anything is missing or misconfigured, impact will flag it and suggest the fix command.