pacman-token-manager 3.1.0__tar.gz

pacman_token_manager-3.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 tsuimou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pacman_token_manager-3.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: pacman-token-manager
+Version: 3.1.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                                        │
+├──────────────────────────────────────────────────────────────┤
+│  Halfway there · Resets in 4h 25m (started 10:00 AM)         │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  TKN █████░░░░░░░░░░░░░░░  27%  193,920 / 728,474            │
+│  534k left · Resets in 4h 25m                                │
+│                                                              │
+├─ Usage over time ────────────────────────────────────────────┤
+│                                                              │
+│  Period             Usage              TKN                   │
+│  Current session    ███░░░░░░░░░  27%   193k                 │
+│  Resets in 4h 25m                                            │
+│                                                              │
+│  Current week                      4.6m                      │
+│  (7-day rolling total)                                       │
+│                                                              │
+├─ Breakdown ──────────────────────────────────────────────────┤
+│                                                              │
+│  By Model           Usage        TKN                         │
+│  Opus               ████████████ 183k                        │
+│  Sonnet             ░░░░░░░░░░░░ 10k                         │
+│                                                              │
+├─ Guidance ───────────────────────────────────────────────────┤
+│                                                              │
+│  Opus is handling 75% of your work. Sonnet is often          │
+│  sufficient and more economical.                             │
+│                                                              │
+│  → Switch to Sonnet?  [Y]es  [N]o thanks                     │
+│                                                              │
+│  Ctrl+C to exit                                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Installation
+
+```bash
+# From PyPI (after publishing)
+pip install pacman-token-manager
+
+# Or install from GitHub
+pip install git+https://github.com/tsuimou/pacman-token-manager.git
+
+# Or local development
+pip install -e .
+```
+
+## 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/`)

pacman_token_manager-3.1.0/README.md

@@ -0,0 +1,133 @@
+# Pacman Token Manager
+
+Tool for monitoring more detail info on token usage in your terminal.
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Pacman Token Manager                                        │
+├──────────────────────────────────────────────────────────────┤
+│  Halfway there · Resets in 4h 25m (started 10:00 AM)         │
+├──────────────────────────────────────────────────────────────┤
+│                                                              │
+│  TKN █████░░░░░░░░░░░░░░░  27%  193,920 / 728,474            │
+│  534k left · Resets in 4h 25m                                │
+│                                                              │
+├─ Usage over time ────────────────────────────────────────────┤
+│                                                              │
+│  Period             Usage              TKN                   │
+│  Current session    ███░░░░░░░░░  27%   193k                 │
+│  Resets in 4h 25m                                            │
+│                                                              │
+│  Current week                      4.6m                      │
+│  (7-day rolling total)                                       │
+│                                                              │
+├─ Breakdown ──────────────────────────────────────────────────┤
+│                                                              │
+│  By Model           Usage        TKN                         │
+│  Opus               ████████████ 183k                        │
+│  Sonnet             ░░░░░░░░░░░░ 10k                         │
+│                                                              │
+├─ Guidance ───────────────────────────────────────────────────┤
+│                                                              │
+│  Opus is handling 75% of your work. Sonnet is often          │
+│  sufficient and more economical.                             │
+│                                                              │
+│  → Switch to Sonnet?  [Y]es  [N]o thanks                     │
+│                                                              │
+│  Ctrl+C to exit                                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Installation
+
+```bash
+# From PyPI (after publishing)
+pip install pacman-token-manager
+
+# Or install from GitHub
+pip install git+https://github.com/tsuimou/pacman-token-manager.git
+
+# Or local development
+pip install -e .
+```
+
+## 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/`)

pacman_token_manager-3.1.0/pyproject.toml

@@ -0,0 +1,205 @@
+# Automatically refactored pyproject.toml with best practices
+
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pacman-token-manager"
+version = "3.1.0"
+description = "A real-time terminal monitoring tool for Claude Code token usage with advanced analytics and Rich UI"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "tsuimou" }]
+maintainers = [{ name = "tsuimou" }]
+keywords = [
+  "ai", "analytics", "claude", "dashboard",
+  "developer-tools", "monitoring", "rich",
+  "terminal", "token", "usage"
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Console",
+  "Environment :: Console :: Curses",
+  "Intended Audience :: Developers",
+  "Topic :: Software Development :: Debuggers",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: System :: Monitoring",
+  "Topic :: Terminals",
+  "Topic :: Utilities",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Operating System :: POSIX :: Linux",
+  "Operating System :: MacOS",
+#  "Operating System :: Microsoft :: Windows",
+  "Typing :: Typed"
+]
+dependencies = [
+  "numpy>=1.21.0",
+  "pydantic>=2.0.0",
+  "pydantic-settings>=2.0.0",
+  "pyyaml>=6.0",
+  "pytz>=2023.3",
+  "rich>=13.7.0",
+  "tomli>=1.2.0; python_version < '3.11'",
+  "tzdata; sys_platform == 'win32'"
+]
+
+[project.optional-dependencies]
+dev = [
+  "black>=24.0.0",
+  "isort>=5.13.0",
+  "mypy>=1.13.0",
+  "pre-commit>=4.0.0",
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.24.0",
+  "pytest-benchmark>=4.0.0",
+  "pytest-cov>=6.0.0",
+  "pytest-mock>=3.14.0",
+  "pytest-xdist>=3.6.0",
+  "ruff>=0.12.0",
+  "build>=0.10.0",
+  "twine>=4.0.0"
+]
+test = [
+  "pytest>=8.0.0",
+  "pytest-cov>=6.0.0",
+  "pytest-mock>=3.14.0",
+  "pytest-asyncio>=0.24.0",
+  "pytest-benchmark>=4.0.0"
+]
+
+
+[project.urls]
+homepage = "https://github.com/tsuimou/pacman-token-manager"
+repository = "https://github.com/tsuimou/pacman-token-manager.git"
+documentation = "https://github.com/tsuimou/pacman-token-manager#readme"
+issues = "https://github.com/tsuimou/pacman-token-manager/issues"
+
+[project.scripts]
+pacman-token-manager = "pacman.__main__:main"
+pacman = "pacman.__main__:main"
+pactkn = "pacman.__main__:main"
+chomp = "pacman.__main__:main"
+pac = "pacman.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["pacman*"]
+exclude = ["tests*", "src/tests*"]
+
+[tool.setuptools.package-data]
+pacman = ["py.typed"]
+
+[tool.black]
+line-length = 88
+target-version = ["py39", "py310", "py311", "py312"]
+skip-string-normalization = false
+include = '\.pyi?$'
+extend-exclude = '''
+/(
+  \.eggs
+  | \.git
+  | \.hg
+  | \.tox
+  | \.venv
+  | build
+  | dist
+)/
+'''
+
+[tool.isort]
+profile = "black"
+line_length = 88
+known_first_party = ["pacman"]
+force_single_line = true
+atomic = true
+include_trailing_comma = true
+lines_after_imports = 2
+lines_between_types = 1
+use_parentheses = true
+src_paths = ["src"]
+skip_glob = ["*/migrations/*", "*/venv/*", "*/build/*", "*/dist/*"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I"]  # pycodestyle + Pyflakes + isort
+ignore = ["E501"]              # Line length handled by formatter
+
+[tool.ruff.format]
+quote-style = "double"
+
+
+[tool.mypy]
+python_version = "3.9"
+warn_return_any = true      # Catch unintended Any returns
+warn_no_return = true       # Ensure functions return as expected
+strict_optional = true      # Disallow None where not annotated
+
+disable_error_code = [
+  "attr-defined",   # Attribute existence
+  "name-defined",   # Name resolution
+  "import",         # Import errors
+  "misc",           # Misc issues
+]
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+testpaths = ["src/tests"]
+python_files = ["test_*.py","*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+  "--strict-markers","--strict-config","--color=yes","--tb=short",
+  "--cov=pacman","--cov-report=term-missing","--cov-report=html",
+  "--cov-report=xml","--cov-fail-under=70","--no-cov-on-fail","-ra","-q",
+  "-m","not integration"
+]
+markers = [
+  "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+  "unit: marks tests as unit tests",
+  "integration: marks tests as integration tests",
+  "benchmark: marks tests as benchmarks",
+  "network: marks tests as requiring network access",
+  "subprocess: marks tests as requiring subprocess"
+]
+filterwarnings = [
+  "error",
+  "ignore::UserWarning",
+  "ignore::DeprecationWarning",
+  "ignore::PendingDeprecationWarning"
+]
+
+[tool.coverage.run]
+branch = true
+source = ["src/pacman"]
+omit = ["*/tests/*","*/test_*","*/__main__.py","*/conftest.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "pragma: no cover",
+  "def __repr__",
+  "if self.debug:",
+  "if settings.DEBUG",
+  "raise AssertionError",
+  "raise NotImplementedError",
+  "if 0:",
+  "if __name__ == .__main__.:",
+  "class .*\\bProtocol\\):",
+  "@(abc\\.)?abstractmethod"
+]
+show_missing = true
+skip_empty = false
+precision = 2
+
+[tool.coverage.html]
+directory = "htmlcov"
+
+[tool.coverage.xml]
+output = "coverage.xml"

pacman_token_manager-3.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pacman_token_manager-3.1.0/src/pacman/__init__.py

@@ -0,0 +1,5 @@
+"""Claude Monitor - Real-time token usage monitoring for Claude AI"""
+
+from pacman._version import __version__
+
+__all__ = ["__version__"]

pacman_token_manager-3.1.0/src/pacman/__main__.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+"""Module execution entry point for Claude Monitor.
+
+Allows running the package as a module: python -m pacman
+"""
+
+import sys
+from typing import NoReturn
+
+from .cli.main import main
+
+
+def _main() -> NoReturn:
+    """Entry point that properly handles exit codes and never returns."""
+    exit_code = main()
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    _main()