Codex Usage for Obsidian

An Obsidian plugin for displaying CodexBar-style AI coding usage data using managed local helpers.

This is an independent project. It is not an official CodexBar, Win-CodexBar, Obsidian, or OpenAI project.

Status and platforms

The MVP supports Obsidian Desktop on macOS arm64/x64 and Windows x64. It is desktop-only because managed executables require Node/Electron APIs unavailable to Obsidian Mobile.

The plugin shows a responsive desktop dashboard and maintains a vault-synced dashboard note. Quotas, credits, cost, token analytics, and pace form the clean default; account identity, helper metadata, every normalized field, and raw output can be enabled in settings. Quotas can display remaining or used capacity.

The last successful snapshot is stored locally and displayed immediately on startup. Local Codex session logs are imported into a privacy-first usage ledger with exact token counts, models, sessions, repositories, providers, daily totals, and today/7-day/30-day/year/lifetime windows. Each refresh writes Codex Usage/Dashboard.md, a complete Markdown report that remains readable through normal vault sync on Windows, macOS, and mobile even when Codex or this plugin is not installed on the reading device. Raw output, prompts, logs, credentials, and repository paths are excluded from that note.

The local ledger is stored beside the helper as events.jsonl and import-state.json. Repository names and Git remotes are retained for attribution; full repository paths are opt-in in settings. Use Export JSON in settings to write the tracked events into the vault for backup or analysis.

Managed helper 0.38.1 packages are published separately for all supported targets and pinned by SHA-256 in the bundled manifest.

Managed helpers

Users explicitly choose Install Helper or Update Helper. The plugin then:

1. selects the package for the current platform;
2. downloads it from the controlled URL in helpers/manifest.json;
3. verifies its SHA-256 checksum;
4. extracts it into the platform-native Codex Usage application-data directory;
5. runs it locally through its dedicated adapter.

Helpers are never silently updated. The dashboard currently queries Codex only. Although the managed helper knows about other providers, enabling one does not add it to the dashboard yet.

See Provider support for the exact support boundary, OpenCode requirements, managed CLI paths, and diagnostics.

Development

Requires Bun 1.3.14 or newer.

bun ci
bun run test
bun run check
bun run build

Copy or symlink this repository into:

<vault>/.obsidian/plugins/codex-usage

Ensure main.js, manifest.json, and styles.css are present, enable community plugins, then enable Codex Usage for Obsidian.

Releases

Push a semantic-version tag such as 0.2.0 or v0.2.0. release.yml installs from bun.lock, removes an optional v, synchronizes package.json, manifest.json, and versions.json, commits changed metadata to the default branch, runs tests/checks/build, creates the release ZIP, attests the release assets, and creates or updates the normalized release tag. Helper binaries remain in separate helper releases.

The daily helper watcher checks steipete/CodexBar and Finesssee/Win-CodexBar. For an unambiguous upstream CLI asset it builds a candidate package, calculates SHA-256, uploads it to a draft helper release, updates compatibility metadata, runs checks, and opens a pull request. It never auto-merges. A reviewer must test each target and publish the helper release.

Troubleshooting

• Helper missing: Open plugin settings and choose Install Helper.
• Manifest unavailable: Confirm GitHub is reachable and the plugin version includes a published helper manifest.
• Checksum failed: The helper is not executed. Report the release URL and checksum.
• Command or parse failure: Run Diagnostics, inspect Raw Output, and check Obsidian’s developer console.
• Other providers: Read the provider support guide. The dashboard currently displays Codex only.
• Logs: Use Open Logs in plugin settings. Logs are stored beside the helper in the platform-native application-data directory and never written into notes.
• Application data: macOS uses ~/Library/Application Support/Codex Usage/; Windows uses %LOCALAPPDATA%\Codex Usage\. The cross-device dashboard report is stored at Codex Usage/Dashboard.md inside the vault.
• Stale usage: A refresh failed and the last successful cache entry is being shown with a warning.

Security and attribution

See SECURITY.md. Downloaded executables, caches, raw output, and logs remain in platform-native application data. Only the generated summary note is written into the vault.

CodexBar and Win-CodexBar are separate upstream projects with their own licences. Any redistributed helper release must include its exact upstream licence and notice files under helpers/licences/; this repository does not claim ownership of those components.

The Codex Usage plugin source is available under the MIT License.