AGENTS.md

1# Repository Guidelines
2 
3## Project Structure & Module Organization
4- Core code lives in `src/claude_statusbar`: `core.py` handles usage calculation and model lookup, `cli.py` provides the entrypoint (`claude-statusbar`, `cstatus`, `cs`), and `updater.py` manages self-upgrades.
5- Packaging metadata is in `pyproject.toml`; built artifacts land in `dist/` (keep generated wheels/sdists out of commits unless releasing).
6- Installer helpers: `install.sh` and `web-install.sh` for one-line setup, `uninstall.sh` for cleanup, and `publish.sh` for PyPI uploads. Demo and promotional assets sit in `demo/`, `img.png`, and `promotion/`.
7 
8## Build, Test, and Development Commands
9- Install for development (editable): `python -m pip install -e .`
10- Run locally: `claude-statusbar` (or `python -m claude_statusbar.cli --version` to verify wiring).
11- Build distribution: `python -m build` (requires `build`/`wheel`).
12- Publish to PyPI: `./publish.sh` (expects `PYPI_API_TOKEN` or `~/.pypirc`; offers TestPyPI first).
13- Install optional dependency for richer data: `python -m claude_statusbar.cli --install-deps` then follow prompts for `claude-monitor`.
14 
15## Coding Style & Naming Conventions
16- Python 3.9+; follow PEP 8 with 4-space indentation and short, imperative helper names (`get_current_model`, `try_original_analysis`).
17- Keep dependencies minimal (stdlib only by default); guard optional imports and subprocess calls.
18- Prefer pure functions with clear return types; add `typing` hints where missing and keep logging quiet (current default ERROR).
19 
20## Testing Guidelines
21- No automated suite exists yet; add targeted `pytest` cases around `core.main`, calculation helpers, and file parsing when you touch logic.
22- For manual checks: place sample Claude JSONL data under `~/.claude/projects/`, run `claude-statusbar`, and confirm token/cost figures and reset timer behave as expected across empty/malformed files.
23- If introducing flags, verify CLI help stays readable: `python -m claude_statusbar.cli --help`.
24 
25## Commit & Pull Request Guidelines
26- Match existing history: concise lowercase prefixes (`fix: ...`, `feat: ...`, `chore: ...`) with imperative summaries.
27- PRs should describe behavior changes, note data sources used (`claude-monitor` vs direct file scan), and include sample output before/after when altering the status line.
28- Keep diffs small and focused; avoid committing generated `dist/` or `build/` outputs unless intentionally releasing.
29 
30## Security & Configuration Tips
31- The tool reads from user-local Claude data under `~/.claude/`; avoid logging or committing any captured traces.
32- Publishing requires secrets (`PYPI_API_TOKEN`); export them locally and never bake into scripts. Use TestPyPI when unsure about release artifacts.
33