Summary

claude-pulse provides real-time usage monitoring for Claude Code, displaying session limits, weekly quotas, and plan tiers via a customizable status bar. It targets users of Claude Code with active subscriptions, offering immediate visual feedback on usage to prevent exceeding limits and enhance the user experience.

How It Works

The tool integrates directly with Claude Code, leveraging Anthropic's OAuth API via the user's existing login credentials to fetch precise usage data. It processes this data, including session details passed via stdin, and renders a dynamic status line with color-coded progress bars. This approach offers real-time accuracy without requiring a separate API key or background processes, with optional animations purely based on status line refresh cycles.

Quick Start & Requirements

• Primary install / run command: One-liner install script (curl, wget, PowerShell) or manual cloning and execution.
• Non-default prerequisites and dependencies: Python 3.6+ and an active Claude Code subscription (Pro, Max 5x, or Max 20x). No API key is necessary, as it utilizes existing Claude Code OAuth tokens.
• Links:
  • Installer (Linux/macOS): https://raw.githubusercontent.com/NoobyGains/claude-pulse/main/install.sh
  • Installer (Windows): https://raw.githubusercontent.com/NoobyGains/claude-pulse/main/install.ps1
  • Manual Install: https://github.com/NoobyGains/claude-pulse.git
  • Plugin Marketplace: Installation is pending review.

Highlighted Details

• Visual Usage Tracking: Features color-coded progress bars (green → yellow → red) for session, weekly, Opus/Sonnet, and context window usage.
• Dynamic Status Display: Shows session usage, time remaining, weekly usage, context window fullness, active model, effort level, and worktree branch.
• Customization Options: Offers 10 built-in themes, adjustable text colors, bar sizes (4-12 chars), and diverse bar styles (e.g., block, braille).
• Real-time Notifications: Provides automatic update alerts for claude-pulse and Claude Code itself.
• Advanced Features: Includes auto-detection of extra credits, a weekly reset timer with countdown, and an optional rainbow animation effect.

Maintenance & Community

The project is maintained by PigeonDroid. No specific details regarding community channels (e.g., Discord, Slack), notable contributors, or sponsorships are provided in the README.

Licensing & Compatibility

The project is "Source Available," permitting free use and modification but restricting redistribution. Full details are in the LICENSE file. It is compatible with all Claude subscription tiers and integrates seamlessly with Claude Code without requiring external API keys.

Limitations & Caveats

Requires an active Claude Code subscription. The "Source Available" license may impose redistribution limitations. Users must ensure their Claude Code credentials are valid and refreshed, especially after plan upgrades. The Claude Code update indicator is informational only; users must manually update Claude Code.