Metadata-Version: 2.4
Name: py3status-claude-usage
Version: 0.1.0
Summary: py3status module showing Claude Code subscription usage
Keywords: py3status,i3,i3status,claude,claude-code,usage
Author: Stepan Henek
Author-email: Stepan Henek <henes5am@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Desktop Environment :: Window Managers
Requires-Dist: requests
Requires-Python: >=3.9
Project-URL: Homepage, https://github.com/shenek/i3status-claude
Project-URL: Repository, https://github.com/shenek/i3status-claude
Project-URL: Issues, https://github.com/shenek/i3status-claude/issues
Project-URL: Changelog, https://github.com/shenek/i3status-claude/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# py3status-claude-usage

py3status module that shows Claude Code subscription usage (5-hour and 7-day
windows) in the i3 bar. One module instance per Claude account.

```
Personal 49%▄2h13m 77%▆2d11h
```

Data comes from `https://api.anthropic.com/api/oauth/usage`, authenticated with
the OAuth token in `<path>/.credentials.json`. The module never refreshes the
token (that would rotate the refresh token and log Claude Code out); if the
token is expired the bar keeps its last values until Claude Code renews it.

## Configuration

```
claude_usage personal {
    name = 'Personal'          # label, {name}
    path = '~/.claude'         # dir with .credentials.json
    cache_timeout = 300        # seconds between queries (keep >= 60)
    # format is optional:
    format = '{name} {hourly_percent}%{hourly_chart}{hourly_time_remain} {weekly_percent}%{weekly_chart}{weekly_time_remain}'
}
claude_usage abc {
    name = 'ABC'
    path = '~/.claude-abc'
}
order += "claude_usage personal"
order += "claude_usage abc"
```

Placeholders: `{name} {hourly_percent} {hourly_chart} {hourly_time_remain}
{weekly_percent} {weekly_chart} {weekly_time_remain}`.

The chart is one glyph from `blocks` (default `_▁▂▃▄▅▆▇█`, as in
`battery_level`), coloured green 0-75, yellow 76-89, red 90-100. Change with
`thresholds` (a list, or a dict keyed by `hourly_percent` / `weekly_percent`)
and `color_good` / `color_degraded` / `color_bad`. See `examples/i3status.conf`.

## Installing into py3status

py3status finds third-party modules in two ways.

**A. Include path (no pip, recommended on Debian with distro py3status).**
```
mkdir -p ~/.config/py3status/modules
cp contrib/py3status_shim.py ~/.config/py3status/modules/claude_usage.py
# edit the sys.path line if the repo is not in ~/projects/i3status-claude
```
Needs only `requests` (`python3-requests`).

**B. Entry point (pip).** Install into the interpreter that runs py3status:
```
pip install py3status-claude-usage                      # from PyPI
uv tool install py3status --with py3status-claude-usage # uv tool, from PyPI
uv pip install --system --break-system-packages -e .   # from a checkout, distro py3status
uv tool install py3status --with /path/to/i3status-claude   # from a checkout
```

Then:
1. Add the blocks and `order +=` lines to `~/.config/i3/i3status.conf`.
2. Check: `py3status modules list | grep claude_usage`
3. Reload: `i3-msg restart`; refresh one instance: `py3-cmd refresh "claude_usage personal"`
4. Debug: `py3status -c ~/.config/i3/i3status.conf -l ~/py3status.log -d`

## Development

```
uv sync                      # creates .venv with pytest + responses
uv run pytest
uv run python -m py3status_claude_usage.claude_usage ~/.claude   # one live query
```

## Releasing

1. Move the `[Unreleased]` changelog entries under a new version heading and bump `version` in `pyproject.toml`.
2. `uv run pytest && uv build`
3. Tag: `git tag vX.Y.Z && git push --tags`
4. Publish: `uv publish` (with a PyPI API token via `UV_PUBLISH_TOKEN`), or let the `Publish` GitHub workflow do it on a published release (PyPI trusted publishing).
