Skip to content

feat(ai-usage): full AI page for local agent usage - #549

Open
nikoelt wants to merge 5 commits into
mactools-app:mainfrom
nikoelt:pr/ai-usage
Open

nikoelt wants to merge 5 commits into
mactools-app:mainfrom
nikoelt:pr/ai-usage

Conversation

@nikoelt

@nikoelt nikoelt commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Closes #545.

Problem and result

AI Usage showed Codex and Claude Code quotas and reset times. It now shows a full AI page for Claude, Codex, OpenCode and GitHub Copilot:

  • Plan limits and resets, including Codex's banked resets.
  • API value at public list prices, and cache savings.
  • Trends, usage by model and by project, and a 13-week activity map.

Changes

  • Rewrite: the plugin is replaced by a port of Vorssaint's AI page (GPL-3.0-or-later). The cc-bar logos are no longer used, so the cc-bar notice is replaced by a Vorssaint notice with its revision and paths.
  • Data:
    • It reads only local session logs and the Claude app's saved limits.
    • It keeps usage counts with each record's model, project and session id, and each log's path and read position, in the plugin's cache folder. It never stores prompts, replies or tool output.
    • It reads no account credentials: account-wide limits come from the agents' own command-line tools.
    • The public price list is fetched only when the person keeps prices up to date.
  • Upgrade: the earlier plugin's Codex and Claude switches carry over once, and a backup in the earlier format restores them. The earlier menu bar item and refresh interval have no successor.
  • Backup and sync: a change to the page's portable choices signals the host again.
  • Stopping: never waits on the main thread; only quitting waits, for up to a second, and a locked OpenCode database no longer holds the reader.
  • Code: builds as Swift 6 with strict concurrency. On-screen parts are main-actor isolated, and the readers say how they are confined (their queue, a lock, or the URL session's delegate queue).
  • Tests: AIUsageLogAndPricingTests covers Claude and Codex log parsing, turn boundaries, the shipped price list, model price families, and cost arithmetic.
  • Docs: docs/plugins/ai-usage.md updated, the backup inventory regenerated (credentials are no longer touched), and one plugin changelog fragment.

Verification

  • AIUsageLogAndPricingTests, AIUsagePreferencesMigrationTests (carry-over, a choice on the page winning, earlier backups) and AIUsageOpenCodeLockTests (a stop with the database locked returns at once), within the full XCTest suite: pass, 3,309 tests, 0 failures (6 skipped by upstream's own settings)
  • make script-tests: pass (changelog, localization, website data, backup inventory, and 275 tooling tests)
  • Checked by hand before the review fixes: the AI page with real Claude and Codex usage on macOS 27.

UI evidence

Before, the current AI Usage:

Current AI Usage

After, the new page with the same accounts (Claude session and week limits, Codex week limit):

The new AI page

Only the limit cards are enabled in these settings; trends, models, projects and activity are further cards the person turns on.

Checklist

  • Core behavior and relevant risks are verified using existing tests, focused additions, or manual checks; results or limitations are recorded.
  • UI evidence is attached where applicable; shared components, themes, localization, and accessibility are respected.
  • User-facing documentation and changelog fragments are updated when required.
  • Plugin metadata, runtime contracts, action policies, and minimum-host compatibility agree.
  • Licensing and third-party notices are complete; no credentials, local configuration, or unrelated generated files are included.

🤖 Generated with Claude Code

AI Usage now shows plan limits, API value, trends, models, projects,
activity and Codex resets for Claude, Codex, OpenCode and GitHub Copilot,
read from this Mac's local logs. Prompts, replies and tool output are
never stored, only counters; MacTools reads no account credentials.

Adapted from Vorssaint (GPL-3.0-or-later), recorded in the third-party
notices in place of the cc-bar logos the plugin no longer uses. Builds as
Swift 6 with strict concurrency, with tests for log parsing and pricing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ggbond268

Copy link
Copy Markdown
Collaborator

Thanks for the work on the expanded AI Usage page! I reviewed f4a23b6 and recommend fixing these three issues before merging:

  1. Avoid blocking the host when stopping the reader. settleArchive() uses queue.sync on the main thread. In a temporary test with a locked OpenCode database, stopping waited about 10.5 seconds, blocking the host UI and other plugins' interactions. Please make cancellation and cleanup asynchronous, allow database waits to be interrupted, and keep shutdown flushing bounded.

  2. Preserve existing settings and backups. The new implementation does not migrate preferences.v1, so a previously disabled provider becomes enabled again. It also rejects the previous portable backup format. Please migrate existing provider choices before starting the reader and support importing the old backup schema into the new settings.

  3. Restore automatic backup and cloud-sync notifications. PluginPersistentPreferencesChangeSignaling was removed. AI settings still persist locally, but changes to them alone no longer notify the host to schedule automatic backup or cloud sync. Please restore the protocol and emit its callback after successfully saving any portable preference, including the page's period and limit-display choices.

Thanks! Happy to take another look after these are addressed.

nikoelt and others added 3 commits November 18, 2026 19:25
Updating from the earlier AI Usage plugin carries its Codex and Claude
switches over once, before anything is read, so an agent turned off stays
off; a choice already made on the page wins, and the old record is kept.
A backup taken before the update restores those two switches.

Changes made in Settings or on the page itself tell the host again, so
automatic backup and sync pick them up.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Stopping no longer waits on the reader's queue: saving progress, or
removing it, runs after whatever the reader is doing. Only quitting waits,
for up to a second, since the process ends right after; a missed save only
makes the next launch's first read longer.

A locked OpenCode database used to hold each query for SQLite's two-second
busy timeout; the wait now ends as soon as reading stops. With the
database locked, a stop took 9.6 seconds before and 0.2 seconds now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The archive keeps each record's model, project and session id and each
log's path and position, not only counters. The guide now says so, and
that the menu bar item and refresh interval of the earlier plugin are
gone while its Codex and Claude switches carry over.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nikoelt

nikoelt commented Nov 18, 2026

Copy link
Copy Markdown
Contributor Author

Thanks, all three are addressed:

  1. Blocking on stop. Stopping no longer waits on the reader's queue: saving progress, or removing it, runs after whatever the reader is doing. Only quitting waits, for up to a second, since the process ends right after. A locked OpenCode database used to hold each query for SQLite's two-second busy timeout; the wait now ends as soon as reading stops. With the database locked by another connection, a stopped read took 9.6 seconds before the change and 0.2 seconds after. (40e3ec4)
  2. Settings and backups. On first launch after the update, the earlier plugin's Codex and Claude switches carry over once from preferences.v1, before anything is read; a choice already made on the new page wins, and the old record is kept. A backup in the earlier format restores those two switches. (b8e0a29)
  3. Change signalling. PluginPersistentPreferencesChangeSignaling is back. Settings and the page both write their own defaults, so the plugin compares its portable choices after each change and signals when they differ; a carried-over migration is signalled through the emitter's buffer. (b8e0a29)

The guide now also says what the archive keeps (each record's model, project and session id, and each log's path and position) and that the earlier plugin's menu bar item and refresh interval are gone. (a87a2c2)

Tests: new unit tests for the one-time carry-over, a choice on the page winning, no earlier record, and restoring an earlier backup, plus a test that holds an OpenCode database locked and stops the read (it fails with the old busy timeout and passes now). The full XCTest suite passes on the branch (3,243 tests, 0 failures; 6 skipped by upstream's own settings), and make script-tests passes.

@ggbond268

Copy link
Copy Markdown
Collaborator

Thanks for the updates! I rechecked 898ca3f and confirmed that stopping no longer blocks the host, existing provider choices migrate correctly, and page preference changes notify the host for backup and sync.

One legacy-backup case still fails. If OpenCode and Copilot are already off, an earlier backup with both Codex and Claude disabled is rejected by the “at least one provider enabled” check. The previous version allowed this configuration, so a valid backup cannot restore its intended disabled state. I reproduced this with synthetic data.

Please allow restoring the all-disabled state and show an appropriate inactive/setup view. Keep all provider choices intact, and ensure the restored state can also be exported and restored in the new format.

For UI consistency, please also replace the hardcoded 8.5–9.5 pt ordinary labels with PluginTypography and use shared theme text colors instead of the separate black/white agentInk styling. Reduce content density where needed rather than shrinking normal text below the project's minimum.

The 11 existing plugin tests and 275 script tests pass; the stop and host-callback checks also pass. Thanks again for addressing the earlier feedback!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] Expand AI Usage into a full AI page

2 participants