ZSH CCUsage Plugin

August 14, 2025 · View on GitHub

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

License ZSH

Overview

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.

Demo

ZSH CCUsage Plugin Demo

Display Examples

Cost ModePercentage ModeDisplayDescription
ActiveDaily Average`[$45.23A35%D]`
DailyDaily Plan`[$20.45D22%P]`
MonthlyMonthly`[$1800.00M185%M]`

Visual Examples

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

Features

  • 🚀 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

Requirements

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

Installation

Oh My Zsh

  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

Prezto

  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

Zinit

Add to your .zshrc:

zinit light yourusername/zsh-ccusage

Manual Installation

  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

Configuration

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

VariableDefaultDescription
CCUSAGE_AUTO_UPDATEtrueEnable/disable automatic updates on each command
CCUSAGE_UPDATE_INTERVAL30Cache duration in seconds (30 seconds)
CCUSAGE_PLAN_LIMIT200Monthly plan limit in USD for percentage calculations
CCUSAGE_PERCENTAGE_MODEdaily_avgPercentage calculation mode (see below)
CCUSAGE_COST_MODEactiveCost display mode (see below)
CCUSAGE_DISPLAY_FORMAT[$%.2f | %d%%]Custom display format (printf-style)
CCUSAGE_CACHE_DIR$HOME/.cache/zsh-ccusageDirectory for cache files
CCUSAGE_DAILY_LIMIT-Deprecated - Use CCUSAGE_PLAN_LIMIT instead

Percentage Modes

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.

Percentage Mode Examples

# 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%

Cost Modes

The CCUSAGE_COST_MODE variable controls which cost metric is displayed:

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

    • Fetches using: ccstat 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 daily --since YYYY-MM-DD --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 monthly --since YYYY-MM --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.

Cost Mode Examples

# 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]

Cost and Percentage Mode Combinations

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

Example Configuration

# 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

Configuration by Use Case

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

Usage

Automatic Updates

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

Manual Refresh

Force a refresh of the cost data:

ccusage-refresh

Runtime Mode Switching

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

Display Format

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)

Display States

  • [\$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

Color Coding

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

Migration Guide

Migrating from CCUSAGE_DAILY_LIMIT to CCUSAGE_PLAN_LIMIT

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.

Understanding the Change

  • 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

Quick Migration Steps

  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

Frequently Asked Questions

Which percentage mode should I use?

  • 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

Why is my percentage over 100%?

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

Can I use different limits for different projects?

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

How do I disable the percentage display?

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

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

What's the difference between cached data (*) and live data?

  • 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

Which cost mode should I use?

  • 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

Can I see different cost modes simultaneously?

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.

What do the mode suffixes mean?

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

Troubleshooting

Plugin not displaying

  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 (v0.3.1+) is accessible: ccstat --version

No cost data showing

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

Slow shell startup

  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

Stale data indicator (*)

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.

Performance

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

Contributing

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

Development Setup

  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

Testing

Test the plugin with different scenarios:

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

License

MIT License - see LICENSE file for details.

Credits

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