Metadata-Version: 2.4
Name: sumonitor
Version: 0.1.1
Summary: Real-time token and cost monitoring overlay for Claude Code CLI with session tracking
Author-email: Srivathsan Sivakumar <sri.skumar05@gmail.com>
Maintainer-email: Srivathsan Sivakumar <sri.skumar05@gmail.com>
License: MIT
Project-URL: homepage, https://github.com/SrivathsanSivakumar/simple-usage-monitor
Project-URL: repository, https://github.com/SrivathsanSivakumar/simple-usage-monitor.git
Project-URL: documentation, https://github.com/SrivathsanSivakumar/simple-usage-monitor#readme
Project-URL: issues, https://github.com/SrivathsanSivakumar/simple-usage-monitor/issues
Project-URL: changelog, https://github.com/SrivathsanSivakumar/simple-usage-monitor/blob/main/CHANGELOG.md
Keywords: ai,anthropic,claude,claude-code,cost-tracking,developer-tools,monitoring,terminal,token-usage,usage-tracking
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
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: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
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.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pexpect>=4.8.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.14.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.3.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.6.0; extra == "dev"
Requires-Dist: freezegun>=1.5.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>=5.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.14.0; extra == "test"
Requires-Dist: pytest-timeout>=2.3.0; extra == "test"
Requires-Dist: freezegun>=1.5.0; extra == "test"
Requires-Dist: pytest-xdist>=3.6.0; extra == "test"
Dynamic: license-file

# simple-usage-monitor

[![PyPI version](https://img.shields.io/pypi/v/sumonitor)](https://pypi.org/project/sumonitor/)
[![License](https://img.shields.io/pypi/l/sumonitor)](https://github.com/SrivathsanSivakumar/simple-usage-monitor/blob/main/LICENSE)
[![codecov](https://codecov.io/gh/SrivathsanSivakumar/simple-usage-monitor/graph/badge.svg)](https://codecov.io/gh/SrivathsanSivakumar/simple-usage-monitor)
![Python](https://img.shields.io/badge/python-3.8+-blue.svg)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)

## In-terminal (HUD) usage monitoring for Claude Code - see your costs without leaving your workflow

Unlike other monitoring tools that require opening separate dashboards or browsers, **sumonitor displays your usage data right in your terminal in real-time** as you work. No context switching.

![sumonitor usage](usage.gif)

- Live token counts (input, output, cache)
- Cost tracking with tiered pricing
- Session limits based on your plan
- Time until session reset

All processing happens locally on your device - your sessions remain completely private.

### Supported Models
1. Opus 4.5
2. Sonnet 4.5
3. Haiku 4.5

Other models will still have accurate token counting, just not dollar cost.

## Installation

### Install from PyPI (Recommended)
`pip install sumonitor`

### Install from source
1. Clone the repo

    `git clone https://github.com/SrivathsanSivakumar/simple-usage-monitor`

2. Then install the tool
    `cd path/to/simple-usage-monitor`
 
    `pip install .`

### Uninstallation
`pip uninstall sumonitor`

### Troubleshooting

**PATH not found:** If you see `WARNING: The script sumonitor is installed in '/home/username/.local/bin' which is not on PATH`, add to your shell config:
```bash
export PATH="$HOME/.local/bin:$PATH"
```

**externally-managed-environment error:** On modern Linux (Ubuntu 23.04+, Debian 12+, Fedora 38+), use one of these alternatives:

- **pipx** (recommended):
  ```bash
  pipx install sumonitor
  ```

- **Virtual environment**:
  ```bash
  python3 -m venv myenv && source myenv/bin/activate
  pip install sumonitor
  ```

## Usage

Simply run:

```bash
sumonitor
```

This will:
1. Auto-detect your Claude Code installation
2. Start Claude Code with the monitoring overlay
3. Show real-time usage at the bottom of your terminal

### Command Line Options

```bash
sumonitor [OPTIONS]
```

**Options:**

- `--plan {pro,max5,max20}` - Your Claude subscription plan (default: `pro`)
  - `pro`: Claude Pro plan limits
  - `max5`: Max 5 plan limits
  - `max20`: Max 20 plan limits

- `--path PATH` - Custom path to Claude Code binary (default: auto-detect)

- `--version` - Show version information

- `-h, --help` - Show help message

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

**Areas for contribution:**
- Support for additional Claude models
- Enhanced error handling
- Additional export formats for usage data
- UI improvements
- Overlay functionality improvements

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.

## Acknowledgments
Big thanks to [Claude Code Usage Monitor](https://github.com/Maciek-roboblog/Claude-Code-Usage-Monitor) for the inspiration and awesome work!
