DOCSEARCHbyAlgolia
Submit Docs

claudetop

repository·main·Indexed 42 days ago

https://github.com/liorwn/claudetop

A real-time cost and token tracking tool for Claude Code. It provides visibility into session costs, model usage, cache efficiency, and plan consumption via a prompt header, slash commands, and a web dashboard. Features include smart alerts for budget and context limits, iTerm2 integration, and deep analytics via claudetop-engine to scan JSONL session files.

Tokens
3.3K
Snippets
18
Records
21
Agent score
53%

What's inside claudetop

  1. Overview of claudetop features

    main

    claudetop provides real-time visibility into Claude Code usage, addressing the lack of cost transparency in the default interface. It provides the following information in the prompt header:

    • Project Context: The current project directory and depth.
    • Session Metadata: The model being used and the current session duration.
    • Cost Tracking: Real-time session cost, hourly cost, and projected monthly cost.
    • Plan Usage: Remaining usage windows for 5-hour, 7-day, and per-model (e.g., Fable, Opus, Sonnet) plans, including reset countdowns.
    • Efficiency Metrics: Cache efficiency percentages and cost-per-line metrics.
    • Model Comparison: Estimated costs for alternative models to help decide when to switch.
    • Smart Alerts: Visual indicators when usage patterns appear problematic.

  2. Understand claudetop smart alerts

    main

    claudetop provides real-time alerts in the status line to help manage costs and context efficiency. Common alerts include:

    AlertMeaningAction
    $5 MARK / $10 / $25Cost milestone crossedCheck if you are getting value
    OVER BUDGETDaily budget exceededWrap up or switch models
    CONSIDER FRESH SESSION>2hrs + >60% contextStart a new session
    LOW CACHE<20% cache after 5minContext was reset; tokens are being re-read
    BURN RATE>$15/hr velocityWatch for runaway subagents
    SPINNING?>$1 spent, zero code outputAgent might be stuck in a research loop
    TRY /fast>$0.05/line on OpusUse a smaller model for this task
    COMPACT SOONContext window >80% fullAuto-compaction is imminent
    FABLE LIMIT 93%Plan window (5h/7d/model) ≥90% usedSwitch models or wrap up

  3. Manage Claude plan usage windows

    main

    For Claude Pro/Max/Team subscribers, claudetop displays rate-limit windows (e.g., 5h, 7d, or per-model windows like Fable) as progress bars.

    • 5h: Current session window (rolls every 5 hours).
    • 7d: Current week usage across all models.
    • Model names (e.g., Fable, Opus, Sonnet): Per-model weekly caps.
    • credits: Monthly extra-usage credits.

    Bars turn yellow at 50% and red at 80%. At 90%, an alert (e.g., Fable LIMIT 93%) is triggered to warn you before Claude Code stops you.

    Configuration via Environment Variables:

    • export CLAUDETOP_USAGE=off: Hides the plan line.
    • export CLAUDETOP_USAGE_TTL=120: Sets the refresh interval in seconds (default is 1 minute/60s).

    CLI Commands for usage data:

    • claudetop-usage --show: Displays every window as a 20-char bar with % used, % left, and reset time.
    • claudetop-usage --refresh: Forces a refetch of usage data.
    export CLAUDETOP_USAGE=off
export CLAUDETOP_USAGE_TTL=120

  4. Tag sessions for cost tracking

    main

    You can track costs for specific features, bugs, or initiatives by setting the CLAUDETOP_TAG environment variable before starting a session. This allows you to aggregate costs for that specific context later using claudetop-stats tag <tag>.

    export CLAUDETOP_TAG=auth-refactor
# ... work on auth ...
claudetop-stats tag auth-refactor

  5. Update Claude model pricing manually

    main

    To force an immediate update of the local Claude model pricing cache from the latest rates in the claudetop repository, run the update script. If the script is not found, you may need to install or re-install claudetop using the installation script in the repository root.

    ~/.claude/update-claudetop-pricing.sh 2>&1 || echo "Run: cd ~/claudetop && ./install.sh"

  6. Integrate claudetop with iTerm2

    main

    You can push claudetop metrics into iTerm2's UI (tab titles, status bar, background color, or badges) using the CLAUDETOP_ITERM environment variable.

    Integration Options:

    • export CLAUDETOP_ITERM=all: Enable all features.
    • export CLAUDETOP_ITERM=title: Tab/window title only.
    • export CLAUDETOP_ITERM=badge: Watermark overlay only.
    • export CLAUDETOP_ITERM=statusbar: Set user variables for the iTerm2 status bar.
    • export CLAUDETOP_ITERM=bgcolor: Background color tint based on session state.
    • Combining options: export CLAUDETOP_ITERM=title,badge.

    iTerm2 Status Bar Configuration: To display metrics in your iTerm2 status bar, add 'Interpolated String' components in Preferences > Profiles > Session > Status Bar using these variables:

    • \(user.claudetop_cost): Session cost
    • \(user.claudetop_model): Current model
    • \(user.claudetop_ctx): Context usage
    • \(user.claudetop_project): Project name
    • \(user.claudetop_duration): Session time
    • \(user.claudetop_cache): Cache hit ratio
    • \(user.claudetop_velocity): Burn rate
    • \(user.claudetop_tokens_in): Input tokens
    • \(user.claudetop_tokens_out): Output tokens
    • \(user.claudetop_lines): Lines changed
    • \(user.claudetop_tag): Session tag
    • \(user.claudetop_usage): All plan windows
    • \(user.claudetop_usage_top): Tightest plan window
    export CLAUDETOP_ITERM=title,badge

  7. Install claudetop

    main

    You can install claudetop using three different methods depending on your preference: cloning the repository, using a one-liner, or installing it directly as a Claude Code plugin.

    Clone and install (Recommended)

    This method allows you to manage the source directly.

    git clone https://github.com/liorwn/claudetop.git
cd claudetop && ./install.sh

    One-liner

    Quick installation via curl.

    curl -fsSL https://raw.githubusercontent.com/liorwn/claudetop/main/install.sh | bash

    As a Claude Code plugin

    Install directly through the Claude Code plugin marketplace. This method automatically provides the SessionEnd hook and all slash commands.

    claude plugin marketplace add liorwn/claudetop
claude plugin install claudetop

    Note: After installing as a plugin, you must restart Claude Code for the changes to take effect.

  8. Create custom status line plugins

    main

    You can extend the claudetop status line by dropping executable scripts into ~/.claude/claudetop.d/. The script receives a JSON object via stdin and should print the desired status string to stdout.

    Example Plugin Template:

    #!/bin/bash
JSON=$(cat)
COST=$(echo "$JSON" | jq -r '.cost.total_cost_usd')
printf "\033[32m$%s\033[0m" "$COST"

    After creating the script, ensure it is executable and move it to the plugin directory.

    #!/bin/bash
JSON=$(cat)
COST=$(echo "$JSON" | jq -r '.cost.total_cost_usd')
printf "\033[32m$%s\033[0m" "$COST"

  9. Configure claudetop themes

    main

    Control the verbosity of the status line using the CLAUDETOP_THEME environment variable:

    • export CLAUDETOP_THEME=full: Default (3-5 lines).
    • export CLAUDETOP_THEME=minimal: 2 lines (shows numbers inline, e.g., 5h:82% 7d:64%).
    • export CLAUDETOP_THEME=compact: 1 line (shows only the tightest window).
    export CLAUDETOP_THEME=minimal

  11. Use claudetop slash commands in Claude Code

    main

    When installed as a Claude Code plugin, claudetop provides several slash commands to access different views of your usage and cost data. These are available immediately after restarting Claude Code:

    • /claudetop:stats: View detailed usage statistics.
    • /claudetop:dashboard: Access the main cost and usage dashboard.
    • /claudetop:branch: View usage broken down by git branch.
    • /claudetop:export: Export your usage data.
    • /claudetop:pricing: View current model pricing information.