usage-runway — usage-aware work planning for Claude Code

A small Claude Code skill that closes an instrumentation gap: Claude cannot see your account's plan usage limits, so budgeting expensive work against a weekly cap is manual guesswork. With this skill, Claude reads your real usage numbers from your own logged-in claude.ai settings page, estimates the work you're about to start, and tells you whether it fits — before spending the tokens.

Verdicts are one of: proceed, proceed with checkpoints (land work in small committed increments), downshift (this is mechanical — use a lighter model), or defer (won't fit before your reset).

Requirements

Dependencies are per-tier — the skill degrades gracefully to whatever you have:

Tier	Needs	Without it
Ask-me fallback	Nothing	Always works: Claude asks for your /usage numbers
Live reads	Chrome + the Claude in Chrome extension, signed into your Claude account	Falls back to the relay or asking
Snapshot relay (cloud/headless)	gh CLI installed and authenticated (gh auth login) on the machine that publishes; plain curl on the machine that reads	Cloud sessions fall back to asking

A claude.ai subscription with the Settings → Usage page is assumed — that page is the gauge everything reads.

Quick start

1. Install the skill — pick whichever fits how you use Claude:

   Claude Code (recommended) — install as a plugin, one command each:

   claude plugin marketplace add hulin42/usage-runway
   claude plugin install usage-runway@usage-runway

   (Or /plugin marketplace add hulin42/usage-runway then /plugin install from inside a session. Plugin installs get updates when the repo does.)

   Manual copy — clone this repo and copy the skill folder into your user skills directory:

   cp -r skills/usage-runway ~/.claude/skills/

   Teams can install per-project in .claude/skills/ instead.

   claude.ai — grab usage-runway.skill from the latest GitHub release, open it in a Claude conversation, and use its Save button.

   New sessions pick the skill up automatically either way.

2. Connect Claude in Chrome — the skill reads claude.ai/settings/usage through your logged-in browser:

   • Install the extension: https://chromewebstore.google.com/detail/fcoeoabgfenejglbffodgkkbkcdhcgfn
   • Open the Claude side panel in Chrome and sign in with the same account as your Claude Code app.
   • Keep Chrome running when you want the check to work.

3. Verify — in a new Claude Code session, say /usage-runway. First run, expect a permission prompt to let Claude drive a browser tab; approve it. Success looks like a short report: percent used and reset time for your session meter, weekly all-models meter, and weekly per-tier meter, plus a verdict. Under a minute, read-only, tab closed afterward.

Troubleshooting

• "Claude in Chrome is not connected" — the extension isn't reachable. Check: Chrome is running, the extension is installed, and the side panel is signed into the same account as the app. Then retry; the first attempt after Chrome starts can be transient.
• Login wall on claude.ai — the browser profile isn't signed in. Sign in yourself; the skill is instructed never to touch credentials or login forms.
• No browser tools in this session — some environments (SSH, headless, cloud runs) have no bridge to your Chrome. That's expected: the skill falls back to asking for your numbers — run /usage in a Claude Code terminal or read claude.ai → Settings → Usage, and paste what it shows.

Cloud and headless sessions: the snapshot relay

Cloud sandboxes and headless runs have no bridge to your browser, so they can't read the usage page directly. The relay closes the gap: your local sessions publish a small usage snapshot to a secret GitHub gist, and any session anywhere reads it back by URL — no credentials needed, since secret gist raw URLs are unguessable but public.

Setup (once). You need GitHub's gh CLI installed and authenticated — brew install gh (or see cli.github.com), then gh auth login; the default auth includes the gist scope this uses:

1. Create the gist with a seed snapshot:

   printf '{"schema":"usage-runway-snapshot-v1","read_at":"1970-01-01T00:00:00Z","source":"seed","meters":[]}' > /tmp/usage-runway.json
   gh gist create /tmp/usage-runway.json --desc "usage-runway snapshot"

2. Save the config so the skill finds it — ~/.claude/usage-runway.json:

   {
     "gist_id": "<id from the gist URL>",
     "snapshot_url": "https://gist.githubusercontent.com/<your-user>/<id>/raw/usage-runway.json"
   }

   (That raw-URL form, without a revision SHA, always serves the latest snapshot.) For cloud sessions, expose the URL as the USAGE_RUNWAY_SNAPSHOT_URL environment variable or drop it in the project's CLAUDE.md — cloud sandboxes don't see your home directory.

3. Done. Every successful live read now refreshes the gist as a side effect (write-through), so the cache stays as fresh as your last local check — no scheduled job burning tokens on a timer. Ask any session to "refresh the snapshot" to update it on demand.

Cloud sessions report relayed numbers with their age ("as of 2 hours ago…") and warn when the snapshot is stale. Honest limitation: the cache can't see usage burned since it was written, including by the session reading it — good for start/defer decisions, not for minute-by-minute throttle tracking.

Expect a permission prompt the first time a session runs gh gist edit for the write-through — approve it, or add an allow rule scoped to your gist so refreshes run silently (in ~/.claude/settings.json):

{ "permissions": { "allow": ["Bash(gh gist edit <your-gist-id>*)"] } }

Privacy: the snapshot contains only meter percentages and reset times, at an unguessable URL on your own GitHub account. Delete the gist to revoke.

Make it proactive

The skill triggers on request. To have Claude check runway before starting big work without being asked, tell Claude once:

Remember: before starting any medium-or-larger batch of work, run the usage-runway skill and give me the verdict first.

Claude Code's persistent memory carries that instruction into future sessions.

Privacy and safety

• Read-only: the skill navigates to the usage page, reads it, and closes the tab. It never changes settings, clicks controls, or navigates elsewhere.
• It never enters credentials or completes a login — a login wall is always handed back to you.
• Your usage numbers appear only in the conversation reply, nowhere else.

Limitations

• It reads the same gauge you can see — no more granular than the settings page itself.
• If Anthropic redesigns the usage page, the read may need a nudge; the skill is instructed to report what it actually found rather than guess.

The real fix is native: Claude Code injecting plan usage into the agent's context. That's filed as anthropics/claude-code#90479 — this skill is the userland shim until then, and becomes disposable the day it ships.

License

MIT