ccstat-acp

ccstat-acp

A Claude Code usage status monitor that provides real-time monitoring of Claude API usage, context consumption, and token burn rates. While it creates concise status line style output for general use, it was specifically created to allow monitoring Claude Code context and usage when using it as an External Agent via ACP (Agent Client Protocol) in Zed Editor.

Installation

Via npm (Recommended)

npm install -g ccstat-acp

After installation, you can run the monitor from anywhere:

ccstat-acp

Via npx (No Installation)

Run without installing:

npx ccstat-acp

Features

• Real-time monitoring of Claude usage with 1-second updates
• Billing-aware sessions aligned with Claude's 5-hour billing blocks
• Context tracking with project-specific context usage (especially useful for ACP sessions)
• Burn rate alerts with configurable thresholds
• Progress indicators for time and token usage
• Git integration showing current branch and directory
• Configurable thresholds for warnings and alerts
• ACP-optimized for monitoring External Agent usage in Zed Editor

Usage

Simply run the command in any directory:

ccstat-acp

The monitor will display:

• 📁 Current directory (optional, configurable)
• 🌿 Git branch (optional, configurable)
• ⏰ Time remaining in current billing block
• 🧠 Context usage for current project
• 🔥 Burn rate indicator (Normal/Moderate/High)
• Usage percentages and projections

ACP/Zed Editor Usage

When using Claude Code as an External Agent in Zed Editor via ACP, this monitor becomes especially valuable for:

• Tracking context consumption in real-time as you work
• Monitoring token usage during extended coding sessions
• Getting early warnings before hitting context or billing limits
• Understanding usage patterns when Claude Code is integrated into your editor workflow

Configuration

Configuration is stored in ~/.config/ccstat.json with these options:

{
  "TOKEN_LIMIT": 60000000,
  "CONTEXT_RESERVED": 15,
  "BURN_RATE_HIGH_THRESHOLD": 1000,
  "BURN_RATE_MODERATE_THRESHOLD": 500,
  "REFRESH_INTERVAL_MS": 1000,
  "SHOW_CURRENT_DIR": false,
  "SHOW_GIT_BRANCH": false
}

Key Configuration Options

• CONTEXT_RESERVED: Percentage of context to reserve (default: 15%)
• BURN_RATE_*_THRESHOLD: Token usage rate thresholds (tokens/minute)
• *_WARNING_THRESHOLD: Warning levels for time/usage percentages
• SHOW_CURRENT_DIR: Show current directory in status display (default: false)
• SHOW_GIT_BRANCH: Show git branch in status display (default: false)
• DEBUG_OUTPUT: Enable detailed debug information

Display Options

By default, the directory and git branch are not shown to keep the display minimal. To enable them:

{
  "SHOW_CURRENT_DIR": true,
  "SHOW_GIT_BRANCH": true
}

When enabled:

• Directory paths are shown relative to home (~/Projects/myapp)
• Git branch is shown only when in a git repository
• Both are displayed with color coding for better visibility

Requirements

• Node.js 18 or higher
• Claude Code with usage data in ~/.config/claude/projects/
• For ACP monitoring: Claude Code configured as External Agent in Zed Editor

Development

# Clone and install
git clone https://github.com/PeteHalsted/ccstat.git
cd ccstat
npm install

# Build and run
npm run build
npm start

# Development with auto-rebuild
npm run dev

# Code quality
npm run check:fix

Attribution

This project contains code derived from ccusage by ryoppippi, licensed under the MIT License.

License

MIT License - see LICENSE file for details.