Track AI provider usage quotas in Paperclip ➔ dashboard widget, usage page, and agent tools.

---

A Paperclip plugin that tracks AI provider usage quotas and exposes real-time data to your agents and the dashboard. Agents can check remaining capacity before committing to an expensive call.

Features

• Dashboard widget — current Claude usage (session, weekly, per-model) with color-coded bars
• Full usage page — detailed view with usage history
• Agent tools — get-usage and get-usage-summary so agents can self-throttle
• Scheduled polling — fetches usage every 15 minutes (configurable)
• Auto-detection — reads Claude OAuth tokens from ~/.claude or the macOS Keychain
• Reset times — see when each quota window rolls over

Supported providers

Provider	Method
Claude (Anthropic)	OAuth usage API · CLI fallback

More providers planned. Adding one? See CONTRIBUTING.

Install

Install through your Paperclip instance's Plugin Manager UI, or via the REST API:

# From npm
POST /api/plugins/install
Content-Type: application/json

{ "packageName": "paperclip-plugin-agent-usage" }

# From a local path (development)
POST /api/plugins/install
Content-Type: application/json

{ "packageName": "/path/to/paperclip-plugin-agent-usage", "isLocalPath": true }

Screenshots

Detailed usage page

Per-model quota bars, reset times, and historical usage.

Color-coded bars

Bars shift green → purple → red as usage approaches limits, so you spot trouble at a glance.

Plugin settings

Configuration lives on Paperclip's own generated settings form (Instance Settings → Plugins → Agent Usage Tracker), including a secret picker for the Claude OAuth token — this plugin doesn't ship a custom settings page, so that form is never hidden. Connection status (provider, account, token source) is shown on the main Agent Usage page and the dashboard widget instead.

Configuration

Field	Description	Default
pollIntervalMinutes	How often to refresh usage data	15
providers	Which providers to track	["claude"]
claudeOAuthTokenRef	A Claude Code OAuth token (claude setup-token), stored as a Paperclip secret. Checked first.	(unset)
claudeConfigDir	Absolute path to the Claude Code config directory holding .credentials.json. Leave blank to auto-detect.	""
enableCliFallback	Scrape claude /usage from the terminal when the usage API is unavailable	true

OAuth credentials are auto-detected in this order: the claudeOAuthTokenRef secret, the CLAUDE_CODE_OAUTH_TOKEN environment variable, then your local Claude install (~/.claude, CLAUDE_CONFIG_DIR, or macOS Keychain). Token lifecycle is managed by Paperclip.

If Paperclip runs the plugin worker in its own sandboxed process (the default when Paperclip itself manages the plugin, not just a bare Node process) — the host does not pass its own environment through to plugin workers, by design, so CLAUDE_CODE_OAUTH_TOKEN being set on the Paperclip host/container itself is invisible to the plugin no matter how it's configured there. Set claudeOAuthTokenRef in this plugin's settings instead — it uses Paperclip's own secret store, resolved by the host at call time, and is the only mechanism that reaches the worker process under that sandboxing model. Generate a token with claude setup-token, then paste it into the secret picker for this field.

If Paperclip runs as a different user than the one signed into Claude Code (and you're not using claudeOAuthTokenRef) — a service account, a container, a systemd unit — file-based auto-detection looks in that user's home directory and finds nothing. Set claudeConfigDir to the signed-in user's ~/.claude (for example /home/alice/.claude) and make sure the Paperclip process can read it.

The CLI fallback drives Claude Code's interactive terminal UI, so it only works when the user running Paperclip has completed Claude Code's first-run setup (theme picker, folder trust, sign-in). If it hasn't, the plugin reports which step is blocking rather than hanging. Set enableCliFallback to false to skip the fallback entirely and surface the credential or API error directly.

Agent tools

get-usage

Returns raw quota data (JSON) for a provider. Use this when an agent needs to decide whether to proceed with an expensive operation — call it first, branch on the result.

get-usage-summary

Returns a human-readable summary of remaining capacity across all configured providers, including reset times. Good for narrative responses ("you have 47% of your weekly quota left, resetting in 2 days").

Development

npm install
npm run dev          # esbuild watch
npm run build        # bundle to dist/
npm run typecheck

Releases are managed by shipx:

npm run release           # interactive
npm run release:beta      # pre-release with --tag beta

Related

• Paperclip — the AI agent platform this plugin extends.
• Other projects by the author: shipx.

License

MIT © Lacy Morrow

_{If this saved your agent some quota, consider sponsoring on GitHub, supporting on Patreon, or buying a coffee.}