Miqyas

مقياس — Arabic for gauge. Claude Code session and weekly API usage, always visible in your VS Code status bar.

Miqyas reads the OAuth credentials that Claude Code writes to your machine, makes a minimal probe call to api.anthropic.com on each poll tick, and extracts your rate-limit utilisation from the response headers. No login flow. No server. No clipboard access. The status bar item updates silently in the background.

Status bar

☁ 5h ██▒▒▒▒▒▒▒▒ 24% 3h12m  │  7d ███▒▒▒▒▒▒▒ 31% 4d6h

Hover the item for a full tooltip:

Session — 24% used · resets in 3h 12m
██▒▒▒▒▒▒▒▒

Weekly — 31% used · resets in 4d 6h
███▒▒▒▒▒▒▒

Threshold colours

The entire item — cloud, cells, and text — recolours together. Higher severity wins when the two windows differ.

Thresholds are configurable (see Configuration).

Prerequisites

1. VS Code 1.85 or later
2. Claude Code installed and authenticated — run claude auth login once in any terminal if you have not already done so

Miqyas reads the credentials that Claude Code writes to the OS credential store. It never asks you to log in separately.

Installation

From the VS Code Marketplace

Search Miqyas in the Extensions panel (⇧⌘X) or install from the command line:

code --install-extension MiftahInc.miqyas

From a .vsix file

Download the latest .vsix from the Releases page, then:

code --install-extension miqyas-<version>.vsix

Configuration

All settings live under the miqyas namespace in VS Code settings (⌘,).

settings.json example:

{
  "miqyas.pollInterval": 60,
  "miqyas.warningThreshold": 80,
  "miqyas.criticalThreshold": 95
}

pollInterval is clamped to a minimum of 10 seconds regardless of the stored value. Setting it below 10 has no effect.

How it works

Credential source

Claude Code stores OAuth tokens in the OS credential store after claude auth login:

Miqyas reads credentials once at startup, then re-reads only when a 401 response is received or when the expiresAt timestamp is within 60 seconds of expiry. It never writes, rotates, or revokes credentials.

Usage data

Claude's API returns rate-limit utilisation in response headers on every call. Miqyas makes a minimal 1-token probe call on each poll tick:

POST https://api.anthropic.com/v1/messages
Authorization: Bearer <accessToken>
Content-Type: application/json
anthropic-version: 2023-06-01

{ "model": "claude-haiku-4-5-20251001", "max_tokens": 1, "messages": [{"role":"user","content":"."}] }

The response headers carry the utilisation data:

anthropic-ratelimit-unified-5h-utilization: 0.24   ← session % used (0–1)
anthropic-ratelimit-unified-5h-reset: 1780743600   ← session reset (Unix seconds)
anthropic-ratelimit-unified-7d-utilization: 0.31   ← weekly % used (0–1)
anthropic-ratelimit-unified-7d-reset: 1780815600   ← weekly reset (Unix seconds)

Token consumption from probe calls is negligible — roughly 2 tokens per call, every 30 seconds.

Poll cycle

1. Check expiresAt; re-read credentials if within 60 s of expiry
2. POST to api.anthropic.com/v1/messages with a 10 s AbortController timeout
3. Parse the four utilisation headers
4. Update the status bar item text, tooltip, and colour
5. On 429: multiply the poll interval by 2 (up to 4× the configured value); reset on the next successful response
6. On 401: re-read credentials and retry once before showing an error state

Error states

When Miqyas cannot display usage data it shows ☁ — in the status bar. Hovering explains why.

All diagnostic output is written to the Miqyas output channel (View → Output → Miqyas). Token values are never logged.

Troubleshooting

The item shows ☁ — immediately after install

Claude Code has not been authenticated yet. Run claude auth login in a terminal and follow the browser prompt.

macOS: a Keychain access dialog appears

The first read may trigger a system prompt asking whether VS Code can access the Claude Code-credentials keychain entry. Click Allow. Subsequent reads are silent.

The percentages never change

Check the Miqyas output channel for error messages. A persistent FETCH_FAILED usually means a corporate proxy is blocking api.anthropic.com.

The item disappears

miqyas.enabled may have been set to false. Open Settings, search Miqyas, and re-enable it.

Development

Requirements

• Node.js 18+
• VS Code

Setup

git clone https://github.com/miftahv-inc/miqyas.git
cd miqyas
npm ci

Verification (all three must pass before any change is considered complete)

npm test            # → 33 tests, 0 failures
npm run lint        # → 0 errors, 0 warnings
npm run format:check # → no diff

Run in VS Code

Open the project folder in VS Code and press F5. A new Extension Development Host window opens with Miqyas loaded. Look for the ☁ item in the status bar bottom-right.

Build

npm run compile   # TypeScript → out/
npm run package   # produces miqyas-<version>.vsix

Architecture

src/
  extension.ts       — activation, poll loop, config change listener
  config.ts          — single getConfiguration wrapper; enforces poll floor
  credentialReader.ts — OS keychain / file read; returns Result<Credentials>
  usageFetcher.ts    — probe POST, header parse; returns Result<UsageData>
  formatter.ts       — bar glyphs, countdown strings, status bar text
  display.ts         — writes to StatusBarItem; maps error codes to tooltips
  types.ts           — shared interfaces and Result<T> type

media/
  cub.woff           — custom icon font (cloud, full cell, empty cell glyphs)

src/__tests__/
  formatter.test.ts
  credentialReader.test.ts
  usageFetcher.test.ts

All I/O functions return Result<T> — they never throw. extension.ts is the only file that calls VS Code APIs directly.

Security

• Credentials are read from the OS credential store and held in memory only for the current session. They are never written to disk, logged, or sent anywhere other than api.anthropic.com.
• execFile (not exec) is used for the macOS Keychain read — no shell injection surface.
• All header values from the API go through parseInt/parseFloat before use — no injection into status bar text.
• No webview, no HTML surface, no script execution.
• The extension requests no VS Code permissions beyond vscode.env.openExternal.

Changelog

0.0.1

• Initial release
• Session (5 h) and weekly (7 d) usage meters
• Custom icon font for crisp status bar rendering
• Yellow/red threshold colours
• 429 back-off, credential refresh on 401

License

MIT — see LICENSE.