pacman-token-manager 3.2.0

A real-time terminal monitoring tool for Claude Code token usage with advanced analytics and Rich UI

Pacman Token Manager

Tool for monitoring more detail info on token usage in your terminal.

┌──────────────────────────────────────────────────────────────┐
│  Pacman Token Manager                                        │
├──────────────────────────────────────────────────────────────┤
│  Running low · Resets in 2h 14m (started 5:00 PM)            │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│  TKN ████████████░░░░░░░░  58%  580,000 / 1,000,000          │
│  420k left before you have to wait                           │
│                                                              │
├─ Usage over time ────────────────────────────────────────────┤
│                                                              │
│  Period             Usage              TKN                   │
│  Current session    ████████████  58%  580k                  │
│  Resets in 2h 14m                                            │
│                                                              │
│  Current week                          1.2m                  │
│  (7-day rolling total)                                       │
│                                                              │
├─ Breakdown ──────────────────────────────────────────────────┤
│                                                              │
│  By Model           Usage              TKN                   │
│  Opus               ████████████       580k                  │
│                                                              │
│  By Project         Usage              TKN                   │
│  subagents          ████████████       302k                  │
│  my-project         ██████████░░       278k                  │
│                                                              │
├─ Guidance ───────────────────────────────────────────────────┤
│                                                              │
│  Opus is handling 100% of your work. Sonnet is often         │
│  sufficient and more economical.                             │
│                                                              │
│  → Switch to Sonnet?  [Y]es  [N]o thanks                     │
│                                                              │
│  Ctrl+C to exit                                              │
└──────────────────────────────────────────────────────────────┘

Installation

pip install pacman-token-manager

Method	Command	What You Get
PyPI (Recommended)	pip install pacman-token-manager	Stable release
GitHub (Latest)	pip install git+https://github.com/tsuimou/pacman-token-manager.git	Latest code
Local Development	pip install -e .	Editable install

Claude Code Integration (MCP)

To use inside Claude Code, add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "pacman": {
      "command": "python3",
      "args": ["-m", "pacman.mcp.server"]
    }
  }
}

Then restart Claude Code. Ask "check my tokens" or "chomp" and Claude will show your usage.

Usage

# Pick your favorite command
chomp
pac
pacman
pactkn
pacman-token-manager

Features

• Accurate token tracking - Counts only billable tokens (excludes free cache reads)
• All projects view - Tracks usage across ALL your Claude Code projects
• Matches Claude /usage - Shows the same percentage as Claude's built-in /usage
• Human-first design - No technical jargon, just clear status
• Smart alerts - Warns you at 50%, 75%, and 90% usage
• Model breakdown - See which models are eating your tokens
• Project breakdown - See which projects are using your quota
• Usage over time - Track 5hr window and weekly usage
• Contextual guidance - Smart recommendations based on your usage patterns
• Interactive actions - Press Y/N to execute suggested actions
• Zero token cost - Pacman reads local files, doesn't call the API

Display Information

Section	Data Shown
Token Status	Progress bar + % + tokens used/limit + reset time
Usage Over Time	Current session (% + reset time) and Current week (7-day total)
Breakdown	By Model and By Project with token counts
Guidance	Context-aware recommendation + optional Y/N action

Smart Guidance

Pacman provides contextual guidance based on your usage:

Condition	Guidance	Action
≥90% usage	"You're almost at your limit..."	→ Run /compact? [Y/N]
High burn + ≥70%	"Using tokens quickly..."	→ Run /compact? [Y/N]
Heavy Opus (>60%)	"Opus is handling X%..."	→ Switch to Sonnet? [Y/N]
≥75% usage	"Running low on tokens..."	→ Run /compact? [Y/N]
High burn rate	"High token velocity..."	(informational)
50-74% usage	"Halfway through..."	(informational)
<50% usage	"You're in good shape."	(none needed)

Interactive Actions

When a Y/N prompt appears, you can:

• Press Y to execute the suggested command
• Press N to dismiss (won't show again this session)
• Press Ctrl+C to exit

Token Calculation

Pacman correctly calculates billable tokens that count toward your rate limit:

Token Type	Counts Toward Limit?
Input tokens	Yes
Output tokens	Yes
Cache creation	Yes
Cache reads	No (FREE)

This matches how Claude's /usage calculates your usage.

Alerts

Threshold	Color	Alert
50%	Yellow	Halfway there
75%	Orange	Running low
90%	Red	ALMOST OUT!

Requirements

• Python 3.9+
• Claude Code CLI (creates the usage data files in ~/.claude/projects/)