setup-statusline

name	setup-statusline
description	Live token counter in your CLI. Shows real-time input/output/cache token counts in the Claude Code status bar
when_to_use	Use when user wants to install, uninstall, or configure the token-saver statusline. Triggers on "setup statusline", "install statusline", "statusline install".

Manage the claude-code-token-saver statusline in Claude Code's ~/.claude/settings.json.

Help

ONLY show help if the user's argument literally contains the word "help" (e.g. /setup-statusline help). If no argument or any other argument is given, SKIP this section entirely and proceed to Step 1.

If the user provides "help" as argument, show usage summary and stop:

/setup-statusline — Install or uninstall the live usage monitor

Format:
  [RUN🟢] ＄0.10/＄12.23 | [5H🟢] 9% ⏳1h32m | [W🟡] 65% ⏳1d3h | [CTX🟢] 22%
  ─────   last / total     5h window usage    weekly (≥60% only)  context window
                           (subscribers only)

Options:
  install       Register statusline (default)
  uninstall     Remove and restore previous config
  help          Show this help

Examples:
  /setup-statusline install
  /setup-statusline uninstall

Do not modify any settings. Just display the help text and stop.

Args

• install (default if no arg) — register the statusline script
• uninstall — remove and restore backup if available

Install Flow

1. Read ~/.claude/settings.json

2. Check current statusLine field:

   Case A: No statusLine — install directly.

   Case B: Already our script — check if path matches current ${CLAUDE_PLUGIN_ROOT}. If version differs, update path silently, then print "Updated to current version." and stop. If same version, print "Already installed." and stop. Check by matching the command path containing claude-code-token-saver/scripts/statusline-logger.sh.

   Case C: Different statusLine exists — warn and ask the user:

   ⚠️ Existing statusline detected:
     command: {existing command}
   
   Options:
   1. Replace (backup existing to _statusLineBackup)
   2. Cancel
   
   Which? (1/2)
   

   Wait for user response. If "1", backup to _statusLineBackup then install. If "2", stop.

3. Install: set statusLine to:

   {
     "type": "command",
     "command": "${CLAUDE_PLUGIN_ROOT}/scripts/statusline-logger.sh"
   }
   

4. Verify the script is executable:

   chmod +x "${CLAUDE_PLUGIN_ROOT}/scripts/statusline-logger.sh"
   

5. Output:

   ✅ Statusline installed.
   It will appear after your next interaction with Claude.
   
   Subscriber format:
     [RUN🟢] ＄0.10/＄12.23 | [5H🟢] 9% ⏳1h32m | [W🟡] 65% ⏳1d3h | [CTX🟢] 22%
   
   API key format:
     [RUN🟢] ＄0.10/＄12.23 | [CTX🟢] 22%
   
   Fields:
   - [RUN]  ＄0.10/＄12.23 — **Current user turn cost** / cumulative cost since `claude` started.
                        The turn cost accumulates across follow-up tool calls so a $1.43 warning
                        stays visible until you start a new prompt. A new turn is detected when
                        no API call happens for 60 seconds (tunable via
                        `CC_TOKEN_SAVER_TURN_IDLE_SEC`). Resets when you exit and restart claude.
   - [5H]  9% ⏳1h32m — Anthropic 5-hour rate limit usage (subscribers only).
                        ⏳ shows time until the window resets.
   - [W]   65% ⏳1d3h — 7-day weekly rate limit. Only shown when ≥60%.
                        ⏳ shows time until the weekly window resets.
   - [CTX] 22%         — Context window usage. Higher = more tokens per call.
   
   Color thresholds:
   | Indicator | 🟢 Normal | 🟡 Warning | 🔴 Critical |
   |-----------|-----------|------------|-------------|
   | RUN       | < ＄0.30  | ≥ ＄0.30   | ≥ ＄1.00   |
   | 5H        | < 70%     | ≥ 70%      | ≥ 90%      |
   | W         | (hidden)  | ≥ 60%      | ≥ 90%      |
   | CTX       | < 35%     | ≥ 35%      | ≥ 70%      |
   
   When 5H reaches 🔴, → /report-limit hint appears.
   Other warnings show → /usage-view current for detailed analysis.
   
   To remove: /setup-statusline uninstall
   

Uninstall Flow

1. Read ~/.claude/settings.json

2. Check current statusLine:

   Not our script — print "claude-code-token-saver statusline is not installed." and stop.

   Our script — remove statusLine field. If _statusLineBackup exists, restore it to statusLine and delete _statusLineBackup.

3. Output:

   ✅ Statusline removed.
   {If restored: "Previous statusline restored from backup."}
   {If no backup: "No previous statusline to restore."}
   

Important

• Always use node -e for JSON manipulation (safe parsing, no jq dependency).
• Never modify fields other than statusLine and _statusLineBackup.
• The script path must use ${CLAUDE_PLUGIN_ROOT} to stay portable.