Skillget

paperclip-plugin-agent-usage

agent
Security Audit
Fail
Health Warn
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 6 GitHub stars
Code Fail
  • rm -rf — Recursive force deletion command in package.json
Permissions Pass
  • Permissions — No dangerous permissions requested

No AI report is available for this listing yet.

SUMMARY

Track AI provider usage quotas in Paperclip — dashboard widget, usage page, agent tools

README.md
paperclip-plugin-agent-usage

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

npm version npm downloads CI License Paperclip

Dashboard widget showing Claude usage bars

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.

Usage page

Color-coded bars

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

Color-coded quota bars

Plugin settings

Auto-detects your Claude OAuth credentials and shows current connection status.

Plugin settings

Configuration

Field Description Default
pollIntervalMinutes How often to refresh usage data 15
providers Which providers to track ["claude"]

OAuth credentials are auto-detected from your local Claude install (~/.claude or macOS Keychain). Token lifecycle is managed by Paperclip.

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.

Reviews (0)

No results found