feat(usage): show Claude Code's plan limits, read from its own /usage

[tinhthanh]

Why

The Usage plugin shows plan limits only for Codex. Its README says: "Claude Code doesn't write its limits anywhere the plugin can read". Claude Code's own /usage does print them, using the login the CLI already holds:

Current session: 31% used · resets Oct 15 at 3:30am (Asia/Saigon)
Current week (all models): 64% used · resets Oct 19 at 8am (Asia/Saigon)
Current week (Fable): 32% used · resets Oct 19 at 8am (Asia/Saigon)

What

usage.py report. For each signed-in Claude account (default, plus every folder under ~/.berth/accounts/claude), it runs:

claude --print --no-session-persistence --strict-mcp-config "/usage"

• CLAUDE_CONFIG_DIR is set to that account's folder, or removed for default.
• It runs from ~/.cache/berth-usage/claude-usage, so Claude Code files no project per read.
• --print asks no trust question, --no-session-persistence writes no transcript, and --strict-mcp-config starts no MCP server.

Reading the output.

• The session line becomes primary (300 min), the all-models week becomes secondary, and each model-scoped week goes in a new extra[] with its own label.
• No session line means no reading (an API-key login, or a changed format).
• A reset that can't be parsed keeps its percentage with resets_at: null.
• The year is the one nearest now, so a read across New Year lands right.

Caching. At most one read per account every 5 minutes (~/.cache/berth-usage/claude-limits.json, BERTH_USAGE_CLAUDE_LIMITS_TTL). A failed read keeps the last good one. BERTH_USAGE_CLAUDE_LIMITS=0 turns the feature off.

Keying. Limits are now keyed by (agent, account); they were keyed by account alone, and both agents have a default.

UI.

• LimitRows and the home widget show extra windows by their own label and tolerate resets_at: null.
• The "reset since" note no longer says Codex for a Claude window.
• mock-usage.ts gets a Claude example.

Docs. README and changelog are updated. The approach (flags, parsing, year choice) follows Codenotch's ClaudeUsageCLI (MIT), credited in the code.

Tests

• New plugins/usage/box/usage_test.py (9 tests): the real 2.1.296 output, the prose below not counting as limits, no session line, an unreadable reset, 3pm without minutes, 12am/12pm, a zone whose name contains "am", New Year in both directions, and the off switch.
• app/src/lib/usage-py.test.ts runs it from pnpm test (found by the src/lib/**/*.test.ts glob), so CI covers the Python. It is skipped without python3.
• App: typecheck:plugins, check:titles, check:csp, check:themes, test (497/497) and build pass. The docs build passes.

Tried for real

• On a Mac and on a remote box (berth exec, the plugin's own path), report returns Claude limits: session 34–36%, week 69%, Fable week 36%.
• The first read takes about 3.6 s (one Node start and one request to Anthropic, as /usage makes); a cached read takes 0.05 s.

🤖 Generated with Claude Code

[vercel]

@tinhthanh is attempting to deploy a commit to the seanbrydonio's projects Team on Vercel.

A member of the Team first needs to authorize it.

[sean-brydon]

Hey this looks good! Let me know when its not draft!!