Imported from leeguooooo/claude-code-usage-bar (AGENTS.md). Install upstream with npx skills add leeguooooo/claude-code-usage-bar. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

• 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.
• Packaging metadata is in pyproject.toml; built artifacts land in dist/ (keep generated wheels/sdists out of commits unless releasing).
• 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/.

Build, Test, and Development Commands

• Install for development (editable): python -m pip install -e .
• Run locally: claude-statusbar (or python -m claude_statusbar.cli --version to verify wiring).
• Build distribution: python -m build (requires build/wheel).
• Release: bump the version in pyproject.toml (plus both .claude-plugin manifests) and add the CHANGELOG section — merging that to main triggers .github/workflows/release.yml, which tags, releases, builds binaries and uploads to PyPI. ./publish.sh is the manual fallback (expects PYPI_API_TOKEN or ~/.pypirc; offers TestPyPI first).
• Install optional dependency for richer data: python -m claude_statusbar.cli --install-deps then follow prompts for claude-monitor.

Coding Style & Naming Conventions

• Python 3.9+; follow PEP 8 with 4-space indentation and short, imperative helper names (get_current_model, try_original_analysis).
• Keep dependencies minimal (stdlib only by default); guard optional imports and subprocess calls.
• Prefer pure functions with clear return types; add typing hints where missing and keep logging quiet (current default ERROR).

Testing Guidelines

• No automated suite exists yet; add targeted pytest cases around core.main, calculation helpers, and file parsing when you touch logic.
• 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.
• If introducing flags, verify CLI help stays readable: python -m claude_statusbar.cli --help.

Commit & Pull Request Guidelines

• Match existing history: concise lowercase prefixes (fix: ..., feat: ..., chore: ...) with imperative summaries.
• 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.
• Keep diffs small and focused; avoid committing generated dist/ or build/ outputs unless intentionally releasing.

Security & Configuration Tips

• The tool reads from user-local Claude data under ~/.claude/; avoid logging or committing any captured traces.
• Publishing requires secrets (PYPI_API_TOKEN); export them locally and never bake into scripts. Use TestPyPI when unsure about release artifacts.