Cost Monitor HUD

Persistent HUD showing AI context usage, token cost, and session health across IDE and CLI environments.

Quick Start

For Cursor IDE Users

Install the extension:

cursor --install-extension cost-monitor-hud-0.1.0.vsix --force

Configure the hook:

mkdir -p .cursor/hooks
cp cost-monitor.py .cursor/hooks/

Create .cursor/hooks/hooks.json:

{
  "hooks": {
    "afterAgentResponse": [
      {
        "type": "command",
        "command": "python .cursor/hooks/cost-monitor.py --cursor"
      }
    ]
  }
}

Restart Cursor and start chatting!

For CodeBuddy IDE Users

Install the extension:
- Open CodeBuddy IDE
- Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
- Type "Install from VSIX"
- Select cost-monitor-hud-0.1.0.vsix

Configure the hook:

mkdir -p .codebuddy/hooks
cp cost-monitor.py .codebuddy/hooks/

Create/edit .codebuddy/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/cost-monitor.py\""
          }
        ]
      }
    ]
  }
}

Restart CodeBuddy IDE and start chatting!

For Claude Code CLI Users

Install the plugin:
```
claude /plugin install cost-monitor-hud
```
Or manually copy cli-plugin/ to your Claude Code plugins directory.
Start Claude Code - the statusline will appear automatically.

What It Does

VS Code Extension (Cursor & CodeBuddy IDE)

Status Bar: Always-visible item at the bottom showing T5 | 32% | $0.15
- Green (normal), yellow background (>40%), red background (>70%)
- Click to open the detail sidebar
Sidebar Panel: Full breakdown with progress bar, token distribution, trend chart, and warnings

CLI Plugin (Claude Code & CodeBuddy CLI)

Terminal Output: Rich terminal UI showing context usage, cost, and warnings after each response

Detailed Installation Guide

Prerequisites

Node.js (v18+) - for building the extension from source
Python 3.x - for running the hook script
VS Code / Cursor / CodeBuddy IDE - for running the extension

Build from Source (Optional)

If you want to build the extension yourself:

# Clone the repository
git clone https://github.com/geminiyao/Cost-Monitor.git
cd Cost-Monitor

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Package as .vsix
npm run package

Output: cost-monitor-hud-0.1.0.vsix

Install Pre-built Extension

Download the latest cost-monitor-hud-0.1.0.vsix from the Releases page.

Cursor IDE

cursor --install-extension cost-monitor-hud-0.1.0.vsix --force

CodeBuddy IDE

Method 1 - Via UI:

Open CodeBuddy IDE
Press Ctrl+Shift+P
Type "Install from VSIX"
Select the .vsix file

Method 2 - Via command line (if codebuddy command is available):

codebuddy --install-extension cost-monitor-hud-0.1.0.vsix --force

VS Code (Standard)

code --install-extension cost-monitor-hud-0.1.0.vsix --force

Detailed Configuration Guide

Cursor IDE Configuration

Cursor uses .cursor/hooks/hooks.json to configure hooks.

Step 1: Copy Hook Script

mkdir -p .cursor/hooks
cp /path/to/cost-monitor.py .cursor/hooks/

Step 2: Create Hook Configuration

Create or edit .cursor/hooks/hooks.json:

{
  "hooks": {
    "afterAgentResponse": [
      {
        "type": "command",
        "command": "python .cursor/hooks/cost-monitor.py --cursor",
        "description": "Cost Monitor: track token usage"
      }
    ]
  }
}

Important:

Hook event: afterAgentResponse (triggered after each AI response)
Command: python .cursor/hooks/cost-monitor.py --cursor (note the --cursor flag)
Output: .cursor/hooks/.cost-state.json (watched by the extension)

Step 3: Verify Configuration

Start a chat in Cursor
Check if .cursor/hooks/.cost-state.json is created
The Cost Monitor extension should show data

Manual Test:

echo '{}' | python .cursor/hooks/cost-monitor.py --cursor
ls -la .cursor/hooks/.cost-state.json

CodeBuddy IDE Configuration

CodeBuddy uses .codebuddy/settings.json to configure hooks.

Step 1: Copy Hook Script

mkdir -p .codebuddy/hooks
cp /path/to/cost-monitor.py .codebuddy/hooks/

Step 2: Create Hook Configuration

Create or edit .codebuddy/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python \"$CODEBUDDY_PROJECT_DIR/.codebuddy/hooks/cost-monitor.py\""
          }
        ]
      }
    ]
  }
}

Important:

Hook event: Stop (triggered when AI stops responding)
Command: Uses $CODEBUDDY_PROJECT_DIR environment variable
Output: .codebuddy/hooks/.cost-state.json (watched by the extension)

Note: The exact hook event name may vary by CodeBuddy version. Check the documentation for the correct event name.

Step 3: Verify Configuration

Start a chat in CodeBuddy IDE
Check if .codebuddy/hooks/.cost-state.json is created
The Cost Monitor extension should show data

Manual Test:

echo '{"transcript_path": ""}' | python .codebuddy/hooks/cost-monitor.py
ls -la .codebuddy/hooks/.cost-state.json

Claude Code CLI Configuration

For CLI usage, use the statusline plugin.

Option A: Install via Plugin System

claude /plugin install cost-monitor-hud

Option B: Manual Setup

Copy cli-plugin/ directory to your Claude Code plugins directory:

cp -r cli-plugin ~/.claude/plugins/cost-monitor-hud

Or follow Claude Code's plugin installation documentation.

Configuration Differences

Aspect	Cursor IDE	CodeBuddy IDE	Claude Code CLI
Config File	`.cursor/hooks/hooks.json`	`.codebuddy/settings.json`	Plugin system
Hook Event	`afterAgentResponse`	`Stop`	N/A
Hook Command	`python ... --cursor`	`python ...`	N/A
Output	`.cursor/hooks/.cost-state.json`	`.codebuddy/hooks/.cost-state.json`	stdout (terminal)
Extension Watches	`.cursor/hooks/.cost-state.json`	`.codebuddy/hooks/.cost-state.json`	N/A

Troubleshooting

"Waiting for session data..." in IDE

Cause: The .cost-state.json file is not being generated.

Solution:

Check if hook is configured correctly
Verify cost-monitor.py is in the right location
Start a chat and check if .cost-state.json is created

Debug Steps:

# Check if hook script exists
ls -la .cursor/hooks/cost-monitor.py  # Cursor
ls -la .codebuddy/hooks/cost-monitor.py  # CodeBuddy

# Manual test - Cursor mode
echo '{}' | python .cursor/hooks/cost-monitor.py --cursor
ls -la .cursor/hooks/.cost-state.json

# Manual test - CodeBuddy mode
echo '{"transcript_path": ""}' | python .codebuddy/hooks/cost-monitor.py
ls -la .codebuddy/hooks/.cost-state.json

Chart Aspect Ratio Issue (Fixed)

Cause: Canvas chart doesn't resize properly when sidebar is widened.

Status: Fixed in v0.1.0. If you still see issues, rebuild the extension.

Hook Not Running

Check hook configuration:

Cursor: .cursor/hooks/hooks.json
CodeBuddy: .codebuddy/settings.json

Verify Python is available:

python --version
# or
python3 --version

Check hook event name:

Cursor: Should be afterAgentResponse
CodeBuddy: Should be Stop (may vary by version)

Extension Not Loading

Check if extension is installed:

# Cursor
cursor --list-extensions | grep cost-monitor

# CodeBuddy (if command available)
codebuddy --list-extensions | grep cost-monitor

# VS Code
code --list-extensions | grep cost-monitor

Reinstall if needed:

cursor --install-extension cost-monitor-hud-0.1.0.vsix --force

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     AI Coding Session                        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
        ┌─────────────────────────────────────────┐
        │        cost-monitor.py (Hook)           │
        │  - Reads session data from stdin        │
        │  - Calculates token usage & cost       │
        └─────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
    ┌─────────────────────┐         ┌─────────────────────┐
    │  .cost-state.json   │         │   stdout (terminal)  │
    │  (for VS Code Ext)  │         │  (for CLI statusline)│
    └─────────────────────┘         └─────────────────────┘
              │                               │
              ▼                               ▼
    ┌─────────────────────┐         ┌─────────────────────┐
    │  VS Code Extension  │         │  Claude Code /      │
    │  - Status Bar HUD   │         │  CodeBuddy CLI      │
    │  - Sidebar Panel    │         │  - Terminal output   │
    └─────────────────────┘         └─────────────────────┘

Data Flow:

AI responds → Hook triggered
cost-monitor.py reads session data → writes .cost-state.json
VS Code extension watches .cost-state.json → updates UI
CLI mode: cost-monitor.py outputs to stdout → terminal display

Project Structure

Cost-Monitor/
├── src/                    # TypeScript source (extension)
│   ├── extension.ts        # Extension entry point
│   ├── statusBar.ts        # Status bar HUD
│   ├── sidebarProvider.ts  # Sidebar webview with chart
│   ├── dataWatcher.ts      # Watches .cost-state.json
│   └── types.ts           # Type definitions
├── cli-plugin/            # CLI plugin for Claude Code
│   ├── plugin.json        # Plugin metadata
│   └── statusline.js      # Statusline renderer
├── cost-monitor.py        # Python hook (MUST be deployed to project)
├── media/                 # Icons and images
├── out/                   # Compiled JavaScript (generated)
├── templates/             # Configuration templates
│   └── .codebuddy/
│       └── settings.json  # CodeBuddy settings template
├── test-hook.ps1         # Hook testing script (PowerShell)
├── package.json           # Extension manifest
├── tsconfig.json          # TypeScript config
└── README.md             # This file

Development

Build from Source

npm install
npm run compile
npm run package  # Creates cost-monitor-hud-0.1.0.vsix

Watch Mode (Auto-recompile)

npm run watch

Test the Extension

Build the .vsix
Install to Cursor/CodeBuddy
Reload the IDE
Start a chat to trigger the hook
Check the Cost Monitor panel

Run Tests

# Test hook in CLI mode
echo '{"transcript_path": ""}' | python cost-monitor.py

# Test hook in Cursor mode
echo '{}' | python cost-monitor.py --cursor

# Check generated .cost-state.json
cat .codebuddy/hooks/.cost-state.json
cat .cursor/hooks/.cost-state.json

License

MIT

Contributing

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

Support

Issues: GitHub Issues
Discussions: GitHub Discussions

Made with ❤️ for AI coding assistants

Name		Name	Last commit message	Last commit date
cli-plugin		cli-plugin
media		media
src		src
templates/.codebuddy		templates/.codebuddy
.gitignore		.gitignore
.vscodeignore		.vscodeignore
README.md		README.md
cost-monitor-hud-0.1.0.vsix		cost-monitor-hud-0.1.0.vsix
cost-monitor-hud-0.2.0.vsix		cost-monitor-hud-0.2.0.vsix
cost-monitor-hud-0.2.1.vsix		cost-monitor-hud-0.2.1.vsix
cost-monitor-hud-0.2.2.vsix		cost-monitor-hud-0.2.2.vsix
cost-monitor.py		cost-monitor.py
package.json		package.json
test-hook.ps1		test-hook.ps1
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

Cost Monitor HUD

Quick Start

For Cursor IDE Users

For CodeBuddy IDE Users

For Claude Code CLI Users

What It Does

VS Code Extension (Cursor & CodeBuddy IDE)

CLI Plugin (Claude Code & CodeBuddy CLI)

Detailed Installation Guide

Prerequisites

Build from Source (Optional)

Install Pre-built Extension

Cursor IDE

CodeBuddy IDE

VS Code (Standard)

Detailed Configuration Guide

Cursor IDE Configuration

Step 1: Copy Hook Script

Step 2: Create Hook Configuration

Step 3: Verify Configuration

CodeBuddy IDE Configuration

Step 1: Copy Hook Script

Step 2: Create Hook Configuration

Step 3: Verify Configuration

Claude Code CLI Configuration

Option A: Install via Plugin System

Option B: Manual Setup

Configuration Differences

Troubleshooting

"Waiting for session data..." in IDE

Chart Aspect Ratio Issue (Fixed)

Hook Not Running

Extension Not Loading

Architecture

Project Structure

Development

Build from Source

Watch Mode (Auto-recompile)

Test the Extension

Run Tests

License

Contributing

Support

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages