Stingy Budget

What's your target? You can specify in dollars or tokens.

Before creating budget.json, check if one already exists. If it does, show the user the current config and ask whether they want to update it or keep it. Don't silently overwrite.

mkdir -p ~/.stingy
if [ -f ~/.stingy/budget.json ]; then
  echo "EXISTING_BUDGET_FOUND"
  cat ~/.stingy/budget.json
  # Ask the user: "You already have a budget set. Want to update it or keep the current one?"
  # Only proceed with the write below if they confirm they want to update.
else
  echo "NO_EXISTING_BUDGET"
fi

If the user confirms (or no budget exists), create the budget file:

cat > ~/.stingy/budget.json << EOF
{
  "period": "daily",
  "limit_dollars": 10.00,
  "limit_tokens": 1000000,
  "model_default": "sonnet",
  "alert_at": 0.75,
  "created": "$(date +%Y-%m-%d)",
  "notes": "Set via /budget"
}
EOF
echo "Budget saved to ~/.stingy/budget.json"

Step 3: Log This Session

Every time /budget runs, log an entry.

IMPORTANT: The values CURRENT_MODEL, ESTIMATED_TOKEN_COUNT, and SESSION_DESCRIPTION below are placeholders you must replace with real data from the current session:

• CURRENT_MODEL — the model in use (e.g., "opus", "sonnet", "haiku")
• ESTIMATED_TOKEN_COUNT — actual token count if known; otherwise estimate from conversation length
• SESSION_DESCRIPTION — brief description of what this session was about

If you don't have actual token counts, set "estimated": true in the JSON and estimate based on conversation length. If you have no useful data at all, skip logging entirely rather than writing placeholder literals.

mkdir -p ~/.stingy
# Append a usage entry — replace ALL placeholders with real values before running
cat >> ~/.stingy/usage.jsonl << EOF
{"date":"$(date +%Y-%m-%d)","time":"$(date +%H:%M)","model":"CURRENT_MODEL","estimated_tokens":ESTIMATED_TOKEN_COUNT,"estimated":true,"notes":"SESSION_DESCRIPTION"}
EOF

Fill in the values based on what you know about the current session. Ask the user for /cost output if you need actual numbers.

Step 4: Budget Status Report

BUDGET STATUS
═══════════════════════════════════════

Period: [daily/weekly/monthly]
Budget: $XX.XX / XX,XXX tokens
Used:   $XX.XX / XX,XXX tokens (XX%)
Left:   $XX.XX / XX,XXX tokens

[████████████░░░░░░░░] 62% used

DAILY BREAKDOWN (this week):
  Mon: $X.XX  ████████
  Tue: $X.XX  ████████████
  Wed: $X.XX  ██████
  Thu: $X.XX  ████████████████  ← over budget!
  Fri: $X.XX  ████  (today, in progress)

AVG DAILY: $X.XX
ON TRACK: [Yes / Over by $X.XX / Under by $X.XX]

TOP SPENDING CATEGORIES:
  Coding:    $XX.XX (XX%)
  Research:  $XX.XX (XX%)
  Reviews:   $XX.XX (XX%)

Step 5: Budget Recommendations

Based on usage patterns, suggest:

RECOMMENDATIONS:
- [You're spending $X.XX/day on Opus. Switching to Sonnet for routine tasks
   would save ~$X.XX/day]
- [Your heaviest day was [day] at $XX. Main cost: [what]. Consider: [alternative]]
- [At current pace, you'll hit your monthly budget by [date]]

Step 6: Alerts Configuration

Help the user set up a reminder:

Want me to create a reminder to check /budget?

A) Add a note to CLAUDE.md to run /budget at session start B) No, I'll check manually

If A, add to the project or global CLAUDE.md:

## Token Budget
Run `/budget` at the start of each session to check spending.
Current budget: $XX/[period]. Alert at XX%.

Storage Format

All data lives in ~/.stingy/:

~/.stingy/
├── budget.json        # Budget config
├── usage.jsonl        # Usage log (append-only)
└── alerts.json        # Alert thresholds and state

Rules

• Never overwrite usage.jsonl — always append
• Round dollar amounts to 2 decimal places
• Show visual progress bars — humans process them faster than numbers
• If the user doesn't know their spending, help them estimate from their plan
• Be honest: if they're consistently over budget, say so and suggest a higher budget or a strategy change, don't just warn repeatedly