# Contributing

Thanks for your interest in improving Claude Usage Overlay. This is
a small project but contributions are welcome.

## What's welcome

- Bug reports (especially when the prompt-detection heuristic breaks
  due to claude.ai DOM refactors)
- Parser updates when Anthropic changes the response shape of
  `/api/organizations/{uuid}/usage`
- Localization of the days array (`DAYS_ES`)
- Accessibility improvements
- Small UX polish that doesn't expand the single-purpose scope

## What's out of scope

- Cloud sync, multi-device features, or any backend
- Telemetry or analytics, even opt-in
- Tracking of conversation content
- Synthetic "daily" / "monthly" caps that don't exist in the API
- Anything that requires permissions beyond `storage` and
  `https://claude.ai/*`
- Token counting (deferred — would require a multi-MB bundled
  tokenizer; see [claude-counter](https://github.com/she-llac/claude-counter)
  if you need that)

The extension is intentionally minimal. If a feature needs more
permissions or external services, it likely belongs in a different
project.

## Development setup

No build step. Edit the files in place and reload the unpacked
extension to test.

1. Clone the repo
2. Open `chrome://extensions/` (or `brave://`, `edge://`)
3. Enable Developer mode
4. Click "Load unpacked" and select the repo root
5. Visit `https://claude.ai` to see the strip in the prompt footer
6. After code changes, click the reload icon on the extension card,
   then refresh the claude.ai tab

To enable verbose DOM-detection logging during development, set
`DEBUG_DOM = true` near the top of `content.js`.

## Testing changes

There are no automated tests; verify changes manually:

1. The strip appears in the prompt footer with both percentages
   rendered correctly (including edge cases like 1% and 100%)
2. Session reset shows as `HH:MM` (same day) or `day HH:MM`
3. Weekly reset always shows as `day HH:MM`
4. Color thresholds work: green ≤70%, amber 71-89%, red ≥90%
5. If the strip can't attach, the floating fallback appears
   bottom-right with drag functionality
6. DevTools console shows no errors

## Pull request process

1. Fork the repo
2. Create a branch from `main`
3. Make your changes, keep commits focused
4. Update `CHANGELOG.md` under an `[Unreleased]` section
5. Open a PR explaining what changed and why
6. Be patient — this is a hobby project, reviews may take a few days

## Reporting security issues

If you find a security issue (data leakage, permission abuse, etc.),
email the maintainer directly rather than opening a public issue.
See the address in `PRIVACY_POLICY.md`.

## Code of conduct

Be respectful. Disagreement is fine, hostility is not. Maintainers
reserve the right to close issues or PRs that don't fit the
project's scope or tone.