AI Usage Status

Show remaining Codex and Claude subscription usage limits in the Obsidian desktop status bar. The display stays visible when you switch notes or hide your chat sidebar. No dependency on Claudian or another chat plugin.

This is an independent community project, not an official OpenAI, Anthropic, or Obsidian product. Community-directory submission and approval are separate from the GitHub release.

Features

• Remaining five-hour and weekly allowances, where the provider supplies them.
• Click either indicator for reset dates, last-successful-update time, and manual refresh.
• Automatic checks approximately every five minutes; manual refresh has a 30-second cooldown.
• Missing windows show —, never a guessed 100% or an unlimited allowance.
• Failed/stale updates are clearly marked; values past their reset time are not presented as current.
• Model-specific and additional limit buckets are retained in the detail view.
• Both providers are off by default. Enable each one explicitly after reading its access disclosure.
• Runtime code has no third-party package dependencies; no model prompts or completions are generated.

Example only (not live account data):

Codex 残り 5h:72% / 週:45%    Claude 残り 5h:38% / 週:61%

The initial interface is primarily Japanese, with English access disclosures and enable switches. 残り means remaining, 週 means week, 未取得 means unavailable, 更新停止 means stale/failed update, and 再取得待ち means waiting for refreshed data.

Requirements and compatibility

• Desktop only, Obsidian 1.13.7 or newer. Tested on macOS with Obsidian 1.13.7.
• A separately installed, signed-in Codex CLI for Codex. Tested with CLI 0.153.4. Its App Server must support account/rateLimits/read.
• A separately installed, signed-in Claude Code and an account that exposes subscription usage information for Claude. Tested with Claude Code 2.1.250.
• Account/subscription requirements and possible service charges are set by OpenAI and Anthropic. This plugin is free, but it does not provide a subscription or bypass service limits. API-key billing is not a subscription allowance.
• Windows and Linux have not been tested. Windows currently requires a discoverable codex.exe; a .cmd-only npm shim is not detected. Do not assume the macOS test results apply to other platforms.
• Keep the Obsidian status bar visible. A theme that hides it will also hide these indicators.

Install

Until this plugin is approved in the community directory, use manual installation:

1. Download main.js, manifest.json, and styles.css from the same GitHub release.
2. Place those three files in .obsidian/plugins/ai-usage-status/ inside your vault.
3. In Obsidian, open Settings → Community plugins, refresh the installed-plugin list, and enable AI Usage Status.
4. Click a status indicator to open the detail dialog. Read the access disclosures and turn on Enable Codex and/or Enable Claude.

You do not need a separate core.js file. The release's main.js contains all runtime code.

How to use

• Click a status indicator to see reset timestamps in your computer's time zone.
• Use 今すぐ更新 to refresh. Refreshing does not send an AI prompt.
• The command palette also offers AI Usage Status: 利用枠の詳細を表示 (show details) and AI Usage Status: 利用枠を更新 (refresh).
• Turn either provider off in the detail dialog to stop its requests and discard its in-memory data. Disable the plugin to remove the status items and stop all its timers and active requests.
• The displayed number is a percentage of the provider's subscription limit, not a remaining token count, message count, or model context-window size. Percentages are rounded down.
• A provider may return only a weekly window. The plugin uses the reported duration; it does not assume the first window is always five hours.
• ※ means additional provider/model-specific windows exist; inspect the details before assuming every model has the same remaining allowance.

Privacy, external access, and network disclosure

Read this before enabling a provider. Enabling the plugin alone does not access credentials or query a provider. Per-provider consent flags are the only settings saved by this plugin, in Obsidian's plugin data.json.

Codex

• Finds an already-installed Codex executable through PATH and standard installation locations outside the vault.
• Starts a short-lived local codex app-server --stdio process with the vault as its working directory. It uses the CLI's existing authentication/configuration outside the vault and the CLI communicates with OpenAI's Codex/ChatGPT services to retrieve usage limits.
• The plugin sends only the App Server initialization handshake and account/rateLimits/read. It does not create a thread, read note contents, or send prompts. The Codex CLI controls its own configuration, authentication storage, and network behavior; review those settings independently.
• The owned process is terminated after the request, on timeout, or when the plugin is disabled. No global Codex process is killed.

Claude

• On standard macOS installations, invokes /usr/bin/security to read Claude Code-credentials from your macOS Keychain. The Keychain entry can contain both access and refresh tokens; the plugin uses only the access token and does not refresh or rewrite the entry.
• On other platforms (or with CLAUDE_CONFIG_DIR), reads the existing .credentials.json in Claude Code's configuration directory outside the vault. An existing CLAUDE_CODE_OAUTH_TOKEN environment variable takes precedence.
• Sends that access token in the HTTPS Authorization header only to https://api.anthropic.com/api/oauth/usage, to retrieve your usage-limit percentages/reset times. It does not follow redirects or transmit tokens to this project's author.
• This is an undocumented endpoint used internally by Claude Code, not a supported public integration API. Anthropic may change or restrict it at any time. Availability and acceptance of third-party integrations are not guaranteed. Use only with an account you are authorized to access and in accordance with your service terms.
• Expired/missing credentials produce an error state. Sign in or refresh your session through Claude Code, then retry. Do not paste credentials into an issue, note, or chat. Nonstandard authentication endpoints and custom macOS Keychain service names are not supported.

Data handling

• The plugin does not write credentials, account IDs, raw responses, or quota readings into vault files or logs. Usage state is kept only in memory. Vendor CLIs may separately manage their own authentication/configuration files.
• No telemetry, analytics, advertising, author-operated server, or self-update/download mechanism is included in the plugin.
• No note contents or chat history are read or sent by the plugin.
• Network/account data handled by the providers remains subject to their own policies: OpenAI privacy policy and Anthropic privacy policy.

Troubleshooting

Display / issue	Meaning / next step
未接続 / Off	Open the detail dialog and explicitly enable the desired provider.
—	The service did not supply that window, or its reset time has passed. Not equivalent to 100%.
未取得	No successful response yet. Open details for a sanitized error and verify CLI installation/login.
更新停止	Last update failed or is at least ten minutes old. Old numbers appear only in details, labeled as previous values.
Authentication error	Reauthenticate in the provider's CLI. The plugin does not modify login credentials.
Rate-limit error	Wait before trying again; do not repeatedly toggle the provider or force requests.
macOS permission prompt	Review the request yourself. The plugin needs access to the existing Claude Code Keychain item only if Claude is enabled.

If reporting a problem, include your OS, Obsidian/CLI versions, and the sanitized error. Never include tokens, Keychain output, credential files, raw account responses, or personal vault content.

Development and verification

Requires Node.js 18+ for development. No package installation is necessary.

npm run check
npm test
npm run build

src/core.js contains normalization and read-only provider transports; src/main.js contains the Obsidian UI. scripts/build.cjs creates a readable, deterministic, single-file CommonJS bundle without downloading dependencies. Tests are offline and use synthetic data and mock processes; they do not contact providers or read credentials.

Release tags must exactly match manifest.json (for example 1.0.1, without a v prefix). Attach main.js, manifest.json, and styles.css to the release. Runtime files must not depend on files outside those three assets.

日本語

Obsidian最下部にCodex／Claudeの**契約利用枠の残り％**を常時表示します。ノート切替やClaudianの開閉には依存しません。最初は両方とも未接続です。表示をクリックし、認証情報の読取・通信先の説明を確認して、必要なサービスだけ有効にしてください。

クリックでリセット日時・最終取得日時・手動更新を表示し、約5分ごとに自動更新します。未提供の枠は —、失敗や古い値は「未取得／更新停止」として区別します。Claudeは非公開仕様に依存し、将来動かなくなる可能性があります。認証情報や残量をVaultへ保存せず、ノート内容を送信せず、AIの会話生成も行いません。

License

MIT, Copyright (c) 2026 KKuramochi.