Metadata-Version: 2.4
Name: pacman-token-manager
Version: 3.2.0
Summary: A real-time terminal monitoring tool for Claude Code token usage with advanced analytics and Rich UI
Author: tsuimou
Maintainer: tsuimou
License: MIT
Project-URL: homepage, https://github.com/tsuimou/pacman-token-manager
Project-URL: repository, https://github.com/tsuimou/pacman-token-manager.git
Project-URL: documentation, https://github.com/tsuimou/pacman-token-manager#readme
Project-URL: issues, https://github.com/tsuimou/pacman-token-manager/issues
Keywords: ai,analytics,claude,dashboard,developer-tools,monitoring,rich,terminal,token,usage
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pytz>=2023.3
Requires-Dist: rich>=13.7.0
Requires-Dist: tomli>=1.2.0; python_version < "3.11"
Requires-Dist: tzdata; sys_platform == "win32"
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: isort>=5.13.0; extra == "dev"
Requires-Dist: mypy>=1.13.0; extra == "dev"
Requires-Dist: pre-commit>=4.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.6.0; extra == "dev"
Requires-Dist: ruff>=0.12.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-cov>=6.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.14.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "test"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "test"
Dynamic: license-file

# 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

```bash
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`:

```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

```bash
# 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/`)
