# Claude Usage

> **Disclaimer:** This plugin is an independent community project and is not affiliated with, endorsed by or supported by Anthropic. It uses an undocumented endpoint of the Claude OAuth API that may change or stop working at any time without notice.

Obsidian plugin that shows your Claude subscription usage in the status bar: the 5-hour window, the weekly window and, if present, the weekly window for top-tier models.

The plugin reads the OAuth token from the Claude Code credentials file (or the login keychain on macOS) and uses it to query the usage endpoint. It never writes the token and never refreshes it itself.

## Display

One 14px ring per window, followed by the percentage and the time left until reset (`47m`, `4h52m`, `4d7h`).

- Below the warning threshold: neutral ring
- At or above the warning threshold (default 75 %): ring in `--text-warning`
- At or above the critical threshold (default 90 %): ring in `--text-error` plus a ⚠ glyph, so the state does not depend on colour alone

Hovering the status bar item shows all windows with their reset time and the timestamp of the last fetch. Clicking it shows the same values as a notice.

## Requirements

- Obsidian 1.13.0 or newer, desktop only
- Claude Code installed and signed in via `/login`. The token needs the `user:profile` scope. A token from `claude setup-token` is not sufficient.
- Linux and Windows: credentials file at `~/.claude/.credentials.json` (path configurable in settings)
- macOS: Claude Code stores the credentials in the login keychain (service `Claude Code-credentials`). The plugin reads them via `/usr/bin/security`; the file is only a fallback. If macOS asks for keychain access, choose "Always Allow".

## Installation

Manual:

1. Copy `main.js`, `manifest.json` and `styles.css` to `<Vault>/.obsidian/plugins/claude-usage/`
2. Reload Obsidian and enable the plugin under *Community plugins*

Via BRAT: add `eightk1ll/obsidian-claude-usage` as a beta plugin.

## Settings

| Option | Default | Meaning |
|---|---|---|
| Credentials path | `~/.claude/.credentials.json` | File the token is read from (Linux, Windows; fallback on macOS) |
| Poll interval | 15 minutes | Time between two API requests |
| Warning threshold | 75 % | Ring switches to warning colour |
| Critical threshold | 90 % | Ring switches to error colour plus glyph |
| Show time until reset | on | Countdown next to the percentage |

The command `Refresh usage now` in the command palette triggers a manual fetch.

## Error handling and backoff

Errors that do not resolve on their own (expired token, 401, 403, 429, network errors) put the plugin on hold. The hold grows with each consecutive failure: 15, 30, 60, 120, 240 minutes. A `Retry-After` header from the server extends the hold but never shortens it. The hold also applies to manual refreshes.

The backoff state is persisted in `data.json`, so restarting Obsidian does not reset it. Without this, a permanent error would produce hundreds of requests overnight and trigger a 429 on its own.

An expired token is detected before the request is sent and shown as a hint. The fix in all cases: run `claude` and execute `/login`.

## Why these permissions

Obsidian's automated review flags three behaviours. All of them are needed for the plugin to work:

- **Filesystem access (`fs`)**: reads `~/.claude/.credentials.json` on Linux and Windows. Nothing is written.
- **Shell execution (`child_process`)**: on macOS only, runs `/usr/bin/security find-generic-password -s "Claude Code-credentials" -w` to read the token from the login keychain. No other command is executed, and only on `darwin`.
- **Network**: one request to `api.anthropic.com/api/oauth/usage` per poll interval.

## Privacy

- The token is read from the local credentials file or the macOS login keychain only. It is sent exclusively to `api.anthropic.com` as a bearer header.
- No telemetry, no third-party services, no data stored outside `data.json` in the plugin folder.
- Network access is limited to the usage endpoint listed below.

## Technical notes

- The usage endpoint is not part of Anthropic's public API. Expect breakage after upstream changes; the plugin fails closed (shows `Claude ?`, backs off) instead of retrying aggressively.
- Endpoint: `https://api.anthropic.com/api/oauth/usage` with header `anthropic-beta: oauth-2025-04-20`
- Requests go through `requestUrl` from the Obsidian API
- No build step: `main.js` runs as is, no dependencies beyond the Obsidian API

## License

MIT