A lightweight ZSH plugin that displays real-time AI usage costs from the ccusage CLI tool directly in your terminal prompt.

The zsh-ccusage plugin helps developers monitor their AI usage costs in real-time by displaying the current active block cost and daily usage percentage in the terminal prompt. It prevents exceeding block limits by providing visual feedback with color-coded indicators.

The plugin provides different visual states based on your usage:

[$12.50A | 45%D]   # Green - Active block, within daily average
[$22.00D | 85%P]   # Yellow - Daily total, approaching plan limit
[$180.00M | 120%M] # Red/Bold - Monthly total, exceeded limit
[$22.00D* | 85%*]  # Asterisk - Using cached data
$12.50A|45%D       # Compact - For narrow terminals

• 🚀 Multiple cost display modes - Active block, daily total, or monthly total
• 📊 Multiple percentage modes - Daily average, daily plan, or monthly tracking
• 🎨 Color-coded indicators - Green (<80%), Yellow (80-99%), Red (≥100%)
• ⚡ Async updates - Non-blocking data fetching
• 💾 Smart caching - Reduces API calls with intelligent cache management
• 🔧 Highly configurable - Customize display format, update intervals, and limits
• 📱 Responsive design - Adapts to terminal width automatically
• 🛡️ Robust error handling - Gracefully handles network issues and missing dependencies

• ZSH 5.0 or higher
• Node.js and npm/npx (for running ccusage CLI)
• ccusage CLI installed or accessible via npx

1. Clone the repository into your custom plugins directory:

   git clone https://github.com/yourusername/zsh-ccusage ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-ccusage

2. Add the plugin to your .zshrc:

   plugins=(... zsh-ccusage)

3. Reload your shell:

   source ~/.zshrc

1. Clone the repository:

   git clone https://github.com/yourusername/zsh-ccusage ~/zsh-ccusage

2. Add to your .zpreztorc:

   zstyle ':prezto:load' pmodule \
     ... \
     'zsh-ccusage'

3. Create a symlink:

   ln -s ~/zsh-ccusage ~/.zprezto/modules/zsh-ccusage

Add to your .zshrc:

zinit light yourusername/zsh-ccusage

1. Clone the repository:

   git clone https://github.com/yourusername/zsh-ccusage.git ~/zsh-ccusage

2. Source the plugin in your .zshrc:

   source ~/zsh-ccusage/zsh-ccusage.plugin.zsh

3. Reload your shell:

   source ~/.zshrc

The plugin can be configured using environment variables. Add these to your .zshrc before sourcing the plugin:

The CCUSAGE_PERCENTAGE_MODE variable controls how the usage percentage is calculated:

• daily_avg (default): Compares today's usage against the daily average of your monthly plan

  • Formula: today's usage / (plan limit / days in month) * 100
  • Example: $20 today with $200 plan in 31-day month = 310%D
  • Use case: Best for tracking if you're on pace to stay within monthly budget

• daily_plan: Compares today's usage against your full monthly plan limit

  • Formula: today's usage / plan limit * 100
  • Example: $100 today with $200 plan = 50%P
  • Use case: Shows how much of your total monthly budget you've used today

• monthly: Compares total monthly usage against your plan limit

  • Formula: monthly usage / plan limit * 100
  • Example: $1800 this month with $200 plan = 900%M
  • Use case: Shows your actual monthly usage vs plan limit

The mode indicator (D/P/M) is displayed after the percentage to show which calculation is being used.

# Example 1: Developer with $200/month plan
# Current date: Day 15 of a 30-day month
# Today's usage: $20
# Monthly usage so far: $150

# daily_avg mode (default)
export CCUSAGE_PERCENTAGE_MODE=daily_avg
# Display: [$20.00 | 300%D]
# Calculation: $20 / ($200/30) = $20 / $6.67 = 300%

# daily_plan mode
export CCUSAGE_PERCENTAGE_MODE=daily_plan
# Display: [$20.00 | 10%P]
# Calculation: $20 / $200 = 10%

# monthly mode
export CCUSAGE_PERCENTAGE_MODE=monthly
# Display: [$20.00 | 75%M]
# Calculation: $150 / $200 = 75%

The CCUSAGE_COST_MODE variable controls which cost metric is displayed:

• active (default): Shows the cost of the current active block

  • Fetches using: ccstat --quiet blocks --active --json
  • Display suffix: 'A' (e.g., $45.23A)
  • Use case: Monitor cost of current work session

• daily: Shows today's total cost across all usage

  • Fetches using: ccstat --quiet -s YYYYMMDD --json
  • Display suffix: 'D' (e.g., $20.45D)
  • Use case: Track daily spending regardless of blocks

• monthly: Shows current month's total cost

  • Fetches using: ccstat --quiet monthly -s YYYYMM01 --json
  • Display suffix: 'M' (e.g., $1800.00M)
  • Use case: Monitor overall monthly spending

Each cost mode maintains its own cache to ensure fast switching between modes.

# Show active block cost (default)
export CCUSAGE_COST_MODE=active
# Display: [$45.23A | 85%D]

# Show daily total cost
export CCUSAGE_COST_MODE=daily
# Display: [$20.45D | 85%D]

# Show monthly total cost
export CCUSAGE_COST_MODE=monthly
# Display: [$1800.00M | 85%D]

You can combine any cost mode with any percentage mode for maximum flexibility:

# Example 1: Monitor active block with monthly percentage
export CCUSAGE_COST_MODE=active
export CCUSAGE_PERCENTAGE_MODE=monthly
# Display: [$45.23A | 900%M]
# Shows: Current block cost is $45.23, monthly usage at 900% of plan

# Example 2: Track daily cost with daily average percentage
export CCUSAGE_COST_MODE=daily
export CCUSAGE_PERCENTAGE_MODE=daily_avg
# Display: [$20.45D | 310%D]
# Shows: Today's total is $20.45, which is 310% of daily average

# Example 3: View monthly cost with daily plan percentage
export CCUSAGE_COST_MODE=monthly
export CCUSAGE_PERCENTAGE_MODE=daily_plan
# Display: [$1800.00M | 10%P]
# Shows: Monthly total is $1800, today's usage is 10% of monthly plan

# Basic Configuration - Track daily average usage
export CCUSAGE_PLAN_LIMIT=200
export CCUSAGE_PERCENTAGE_MODE=daily_avg
source ~/zsh-ccusage/zsh-ccusage.plugin.zsh

# Advanced Configuration - Monitor monthly totals
export CCUSAGE_AUTO_UPDATE=true
export CCUSAGE_UPDATE_INTERVAL=60
export CCUSAGE_PLAN_LIMIT=500
export CCUSAGE_COST_MODE=monthly
export CCUSAGE_PERCENTAGE_MODE=monthly
export CCUSAGE_DISPLAY_FORMAT="AI: $%.2f (%d%%M)"
source ~/zsh-ccusage/zsh-ccusage.plugin.zsh

# Minimal Configuration - Manual updates only
export CCUSAGE_AUTO_UPDATE=false
export CCUSAGE_PERCENTAGE_MODE=daily_plan
source ~/zsh-ccusage/zsh-ccusage.plugin.zsh

# Team Configuration - Shared high limit
export CCUSAGE_PLAN_LIMIT=2000
export CCUSAGE_PERCENTAGE_MODE=monthly
export CCUSAGE_UPDATE_INTERVAL=300  # Update every 5 minutes
source ~/zsh-ccusage/zsh-ccusage.plugin.zsh

For Individual Developers:

# Track if you're on pace for your monthly budget
export CCUSAGE_COST_MODE=active      # Monitor current work session
export CCUSAGE_PERCENTAGE_MODE=daily_avg
export CCUSAGE_PLAN_LIMIT=200

For Heavy Users:

# Monitor total monthly usage closely
export CCUSAGE_COST_MODE=monthly     # See monthly totals
export CCUSAGE_PERCENTAGE_MODE=monthly
export CCUSAGE_PLAN_LIMIT=1000
export CCUSAGE_UPDATE_INTERVAL=30  # Frequent updates

For Occasional Users:

# See daily usage as portion of monthly plan
export CCUSAGE_COST_MODE=daily       # Track daily spending
export CCUSAGE_PERCENTAGE_MODE=daily_plan
export CCUSAGE_PLAN_LIMIT=100
export CCUSAGE_AUTO_UPDATE=false  # Update manually

For Team Environments:

# Monitor both active work and monthly totals
export CCUSAGE_COST_MODE=active      # Default to active blocks
export CCUSAGE_PERCENTAGE_MODE=monthly # Compare to team budget
export CCUSAGE_PLAN_LIMIT=5000       # Team monthly budget
# Use ccusage-set-cost-mode to switch views as needed

By default, the plugin automatically updates cost information in the background. The display appears in your right prompt (RPROMPT).

Force a refresh of the cost data:

ccusage-refresh

Switch between cost modes without restarting your shell:

# Switch to daily cost mode
ccusage-set-cost-mode daily

# Switch to monthly cost mode
ccusage-set-cost-mode monthly

# Switch back to active block mode
ccusage-set-cost-mode active

# Show available modes and current mode
ccusage-set-cost-mode

The plugin shows information in the format: [costMODE | percentageMODE]

• Cost: Shows cost with mode suffix (e.g., $45.23A for active, $20.45D for daily, $1800.00M for monthly)
• Percentage: Usage percentage with mode suffix (e.g., 35%D for daily avg, 50%P for daily plan, 900%M for monthly)

• [$45.23A | 35%D] - Normal display with current data
• [$45.23A* | 35%*] - Asterisk indicates stale/cached data
• [$0.00A | 0%D] - No active blocks or usage
• $45.23A|35%D - Compact format for narrow terminals (<80 chars)
• $-.--D | 85%D] - No data available for daily cost mode

The plugin uses color coding to provide visual warnings about your usage:

• 🟢 Green: 0-79% of limit - Safe usage level
• 🟡 Yellow: 80-99% of limit - Approaching limit
• 🔴 Red: ≥100% of limit - Exceeded limit (may use bold formatting)

Color Examples by Mode:

# Daily Average Mode (daily_avg)
[$5.00A | 75%D]   # Green - On track for the month
[$6.00A | 90%D]   # Yellow - Slightly above daily average
[$10.00A | 150%D] # Red - Significantly over daily average

# Daily Plan Mode (daily_plan)
[$150.00D | 75%P]  # Green - Used 75% of monthly plan today
[$170.00D | 85%P]  # Yellow - High daily usage
[$250.00D | 125%P] # Red - Exceeded monthly plan in one day

# Monthly Mode (monthly)
[$150.00M | 75%M]  # Green - 75% of monthly plan used
[$170.00M | 85%M]  # Yellow - Approaching monthly limit
[$250.00M | 125%M] # Red - Exceeded monthly plan

Cost Mode Display Examples:

# Active Block Mode (shows current work session)
[$45.23A | 85%D]   # Active block costing $45.23
[$0.00A | 0%D]     # No active blocks

# Daily Total Mode (shows today's total)
[$120.50D | 60%P]  # Today's total is $120.50
[$-.--D | 85%D]    # Daily data unavailable

# Monthly Total Mode (shows month's total)
[$1800.00M | 900%M] # Monthly total is $1800
[$2500.00M* | 125%M*] # Using cached monthly data

If you were using the older CCUSAGE_DAILY_LIMIT variable, you'll need to update your configuration:

Old Configuration:

export CCUSAGE_DAILY_LIMIT=200  # This is deprecated

New Configuration:

export CCUSAGE_PLAN_LIMIT=200   # Use this instead

The plugin maintains backward compatibility, so CCUSAGE_DAILY_LIMIT will still work but will show a deprecation warning. The new CCUSAGE_PLAN_LIMIT better reflects that this is your monthly plan limit, not a daily limit.

• CCUSAGE_DAILY_LIMIT was misleading as it actually represented your monthly plan limit
• CCUSAGE_PLAN_LIMIT clearly indicates this is your monthly plan amount
• All percentage calculations now reference "plan limit" instead of "daily limit"
• The default value remains $200

1. Open your .zshrc file
2. Find any line with export CCUSAGE_DAILY_LIMIT=
3. Replace CCUSAGE_DAILY_LIMIT with CCUSAGE_PLAN_LIMIT
4. Save and reload your shell: source ~/.zshrc

• Use daily_avg if you want to know whether you're on track to stay within your monthly budget
• Use daily_plan if you want to see how much of your total monthly allowance you've used today
• Use monthly if you want to track your cumulative monthly usage against your limit

This is normal and indicates you've exceeded the threshold for that mode:

• Over 100%D: You've used more than your daily average budget
• Over 100%P: You've used more than your entire monthly plan in one day
• Over 100%M: You've exceeded your monthly plan limit

Yes! You can set CCUSAGE_PLAN_LIMIT differently in each project's directory using tools like direnv or by sourcing project-specific configuration files.

You can customize the display format to show only the cost:

export CCUSAGE_DISPLAY_FORMAT="[$%.2f]"

• Live data: Fresh data fetched from the ccusage API
• Cached data (*): Previously fetched data shown when the cache is still valid or when the API is unavailable

• Use active to monitor your current work session costs in real-time
• Use daily to track your total spending for today across all sessions
• Use monthly to see your cumulative monthly costs

Not in the same prompt, but you can quickly switch between modes using ccusage-set-cost-mode without restarting your shell. Each mode maintains its own cache for instant switching.

The suffixes help you identify which metrics you're viewing:

• Cost suffixes: A (active), D (daily), M (monthly)
• Percentage suffixes: D (daily average), P (daily plan), M (monthly) Example: [$45.23A | 85%D] shows active block cost with daily average percentage

1. Verify ZSH version: echo $ZSH_VERSION (should be 5.0+)
2. Check if plugin is loaded: echo $plugins (for Oh My Zsh)
3. Ensure ccstat CLI is accessible: ccstat --version

1. Check if ccstat is working: ccstat blocks --active
2. Force refresh: ccusage-refresh
3. Check cache directory permissions: ls -la $HOME/.cache/zsh-ccusage

1. Disable automatic updates: export CCUSAGE_AUTO_UPDATE=false
2. Increase cache interval: export CCUSAGE_UPDATE_INTERVAL=1800
3. The plugin uses async loading and should have <100ms impact on startup

The asterisk indicates cached data is being used due to:

• Network connectivity issues
• ccusage API errors
• Cache still valid (within update interval)

Run ccusage-refresh to force an update.

The plugin is optimized for minimal impact on shell performance:

• Lazy loading: Components load only when needed
• Async updates: Non-blocking background data fetching
• Smart caching: Reduces API calls and network overhead
• Efficient parsing: Optimized JSON parsing without external dependencies
• Startup impact: <100ms on average systems

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork and clone the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Test with different ZSH configurations
5. Submit a pull request

Test the plugin with different scenarios:

# Test with no active blocks
# Test with high usage (>80%)
# Test with network disconnected
# Test with narrow terminal

MIT License - see LICENSE file for details.

Created for developers who want to keep track of their AI usage costs without leaving the terminal.