feat(ui): implement usage statistics badge for top bar (ACS-228)

[StillKnotKnown]

Base Branch

• This PR targets the `develop` branch (required for all feature/fix PRs)
• This PR targets `main` (hotfix only - maintainers)

Description

Implements a real-time usage statistics badge in the top navigation bar that displays current Claude API usage with color-coded status indicators and countdown timer functionality.

Key features:

• Multi-provider support: Works with Anthropic OAuth, API key profiles (Z.ai and custom endpoints)
• Color-coded status: Green (<71%), Yellow (71-90%), Orange (91-94%), Red (95%+)
• Countdown timer: Shows live countdown when usage reaches 99%+
• Provider-specific labels: "Session/Weekly Usage" for Anthropic, "Token/Monthly Tool Usage" for Z.ai
• Comprehensive tooltip: Displays detailed breakdown of usage percentages, reset times, and active account
• Hybrid fetching: Uses OAuth API endpoints with CLI /usage command fallback for API key profiles

Related Issue

Closes #ACS-228

Type of Change

• 🐛 Bug fix
• ✨ New feature
• 📚 Documentation
• ♻️ Refactor
• 🧪 Test

Area

• Frontend
• Backend
• Fullstack

Commit Message Format

Follow conventional commits: `: `

Types: feat, fix, docs, style, refactor, test

Example: `feat: add user authentication system`

Checklist

• I've synced with `develop` branch
• I've tested my changes locally
• I've followed the code principles (SOLID, DRY, KISS)
• My PR is small and focused (< 400 lines ideally)

CI/Testing Requirements

• All CI checks pass
• All existing tests pass
• New features include test coverage (42 tests added)
• Bug fixes include regression tests

Screenshots

Before	After

Feature Toggle

• Behind localStorage flag: `use_feature_name`
• Behind settings toggle
• Behind environment variable/config
• N/A - Feature is complete and ready for all users

Breaking Changes

Breaking: No

Details: No breaking changes. The feature is additive and does not modify existing behavior.

Summary by CodeRabbit

• New Features

  • Provider-aware multi-profile usage monitoring (API profiles, OAuth, CLI fallback), provider metadata, session/weekly reset timestamps, countdown and pulsing clock when usage ≥99%; CLI and API usage paths with improved fallback behavior.

• Accessibility

  • Improved ARIA labels for the usage indicator.

• Internationalization

  • Added English and French usage-related UI strings.

• Tests

  • Expanded unit tests for provider detection, usage parsing, countdown, and UI behavior.

• Bug Fixes

  • Safer IPC forwarding with guards and new proactive-swap notification events.

• Chores

  • Added exported constants/types to support reset handling and auth error signaling.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[AndyMik90]

🤖 Auto Claude PR Review

🟠 Follow-up Review: Needs Revision

🟠 Needs revision - 1 blocking issue(s) require fixes.

Resolution Status

• ✅ Resolved: 0 previous findings addressed
• ❌ Unresolved: 0 previous findings remain
• 🆕 New Issues: 3 new findings in recent changes

Finding Validation

• 🔍 Dismissed as False Positives: 1 findings were re-investigated and found to be incorrect
• ✓ Confirmed Valid: 1 findings verified as genuine issues
• 👤 Needs Human Review: 0 findings require manual verification

🚨 Blocking Issues

• quality: useApiMethod flag permanently disabled on first API failure

Verdict

CI Status: ✅ All 18 checks passing - no CI blockers.

Finding Analysis:

• 1 MEDIUM severity finding CONFIRMED VALID (NEW-002: useApiMethod flag never reset after API failure)
• 1 MEDIUM severity finding DISMISSED as false positive (NEW-001: NaN timestamps - protected by falsy checks)
• 2 LOW severity suggestions (bounds validation for API percentages)

Why NEEDS_REVISION: Per quality gates, MEDIUM severity findings that are CONFIRMED_VALID (not dismissed as false positive) block merge. NEW-002 is a legitimate logic issue where the UsageMonitor singleton permanently falls back to CLI after a single transient API failure. While the functionality still works via CLI, this is suboptimal behavior that should be addressed with a retry mechanism.

To resolve: Add logic to periodically retry the API method after it has been disabled, such as resetting useApiMethod to true after N successful CLI calls or implementing exponential backoff.

Review Process

Agents invoked: new-code-reviewer, finding-validator

---

This is an AI-generated follow-up review using parallel specialist analysis with finding validation.

Findings (2 selected of 3 total)

🔵 [NEW-003] [LOW] Z.ai API percentage values used without bounds validation

📁 apps/frontend/src/main/services/profile/profile-usage.ts:159

The Z.ai API response's percentage field is used directly without validating it's within expected bounds (0-100). If the API returns malformed data, this could cause unexpected UI behavior.

Suggested fix:

Add bounds clamping: Math.max(0, Math.min(100, tokensLimit?.percentage ?? 0))

🔵 [NEW-004] [LOW] Anthropic OAuth utilization values used without bounds validation

📁 apps/frontend/src/main/services/profile/profile-usage.ts:250

The Anthropic OAuth API utilization values (0.0-1.0) are multiplied by 100 without bounds validation. Out-of-range API responses could cause incorrect percentage displays.

Suggested fix:

Add bounds clamping after multiplication: Math.max(0, Math.min(100, ...))

---

This review was generated by Auto Claude.

[coderabbitai]

Actionable comments posted: 3

🤖 Fix all issues with AI agents

In @apps/frontend/src/main/claude-profile/usage-monitor.ts:
- Around line 406-413: Wrap each parseResetTime call separately so a thrown
error for one reset string doesn't discard the whole snapshot: when computing
sessionResetTimestamp and weeklyResetTimestamp from usageData.sessionResetTime
and usageData.weeklyResetTime, catch errors per-call (e.g., try/catch or small
self-invoking helper) and return undefined on failure so parseResetTime
exceptions only affect that timestamp and not the other fields or the overall
snapshot.
- Around line 229-235: The code calls profilesFile.profiles.find(...) without
ensuring profilesFile.profiles exists or is an array; add a defensive guard
(e.g., check Array.isArray(profilesFile.profiles) or default to an empty array)
before using .find so that activeProfile assignment is safe, and if the guard
fails return null (or handle accordingly) instead of allowing a runtime
exception in the activeProfile lookup.

In @apps/frontend/src/main/ipc-handlers/terminal-handlers.ts:
- Around line 764-794: The handlers for monitor.on('proactive-swap-completed')
and monitor.on('proactive-swap-failed') use data: any — replace these with
explicit typed payloads (e.g., ProactiveSwapCompletedData and
ProactiveSwapFailedData) defined in a shared types file and import them into
terminal-handlers.ts, then update the event listener signatures to use those
interfaces (and likewise type the show-swap-notification parameter if you have a
Notification type); keep the existing mainWindow.isDestroyed() guards and ensure
the typed payloads match the IPC shape you send via
IPC_CHANNELS.PROACTIVE_SWAP_NOTIFICATION.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 023b6e8 and 5506449.

📒 Files selected for processing (3)

• apps/frontend/src/main/claude-profile/usage-monitor.ts
• apps/frontend/src/main/ipc-handlers/terminal-handlers.ts
• apps/frontend/src/main/services/profile/profile-usage.ts

🧰 Additional context used

📓 Path-based instructions (2)

apps/frontend/src/**/*.{tsx,ts}

📄 CodeRabbit inference engine (CLAUDE.md)

apps/frontend/src/**/*.{tsx,ts}: Use i18n translation keys for all user-facing text in the frontend. All labels, buttons, messages must use translation keys from react-i18next with namespace:section.key format (e.g., 'navigation:items.githubPRs').
Never use hardcoded strings for UI text in JSX/TSX files. Always use translation keys via useTranslation() hook.

Files:

• apps/frontend/src/main/claude-profile/usage-monitor.ts
• apps/frontend/src/main/ipc-handlers/terminal-handlers.ts
• apps/frontend/src/main/services/profile/profile-usage.ts

apps/frontend/**/*.{ts,tsx}

⚙️ CodeRabbit configuration file

apps/frontend/**/*.{ts,tsx}: Review React patterns and TypeScript type safety.
Check for proper state management and component composition.

Files:

• apps/frontend/src/main/claude-profile/usage-monitor.ts
• apps/frontend/src/main/ipc-handlers/terminal-handlers.ts
• apps/frontend/src/main/services/profile/profile-usage.ts

🧠 Learnings (2)

📚 Learning: 2026-01-12T13:47:32.539Z

Learnt from: CR
Repo: AndyMik90/Auto-Claude PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-12T13:47:32.539Z
Learning: Applies to apps/frontend/src/**/*.{tsx,ts} : Never use hardcoded strings for UI text in JSX/TSX files. Always use translation keys via useTranslation() hook.

Applied to files:

• apps/frontend/src/main/services/profile/profile-usage.ts

📚 Learning: 2026-01-12T13:47:32.539Z

Learnt from: CR
Repo: AndyMik90/Auto-Claude PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-12T13:47:32.539Z
Learning: Applies to apps/frontend/src/**/*.{tsx,ts} : Use i18n translation keys for all user-facing text in the frontend. All labels, buttons, messages must use translation keys from react-i18next with namespace:section.key format (e.g., 'navigation:items.githubPRs').

Applied to files:

• apps/frontend/src/main/services/profile/profile-usage.ts

🧬 Code graph analysis (2)

apps/frontend/src/main/claude-profile/usage-monitor.ts (2)

apps/frontend/src/main/services/profile/index.ts (4)

• loadProfilesFile (10-10)
• detectProvider (36-36)
• fetchUsageForProfile (39-39)
• fetchAnthropicOAuthUsage (38-38)

apps/frontend/src/main/services/profile/profile-usage.ts (3)

• detectProvider (87-113)
• fetchUsageForProfile (291-312)
• fetchAnthropicOAuthUsage (207-277)

apps/frontend/src/main/ipc-handlers/terminal-handlers.ts (1)

apps/frontend/src/shared/constants/ipc.ts (1)

• IPC_CHANNELS (6-524)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Seer Code Review
• GitHub Check: CodeQL (javascript-typescript)
• GitHub Check: CodeQL (python)

🔇 Additional comments (11)

apps/frontend/src/main/services/profile/profile-usage.ts (6)

22-30: LGTM on ApiAuthError class.

Clean implementation of a custom error class with readonly properties and proper inheritance.

---

87-113: Provider detection logic is well-structured.

The function correctly handles:

• Z.ai domain and subdomains
• Anthropic OAuth tokens (by prefix check)
• Graceful fallback for invalid URLs and unknown providers

---

123-192: Solid implementation with proper timeout handling and defensive guards.

Good practices observed:

• AbortController for timeout management
• Bounds validation on percentages (Math.max(0, Math.min(100, ...)))
• Guard against malformed response (Array.isArray check on line 152)
• Proper error handling for AbortError and general exceptions

---

291-312: Clean routing implementation.

The switch-based dispatch is clear and handles all provider types appropriately with consistent null returns for unsupported cases.

---

322-340: LGTM on the reset time formatter.

The function correctly handles edge cases (past timestamps, short durations) and produces human-readable output. The RESETTING_SOON sentinel for imminent resets aligns with the UI requirements.

---

219-227: Verify the Anthropic API version header is current.

The anthropic-version: 2023-06-01 header may be outdated. Confirm this is the correct version for the OAuth usage endpoint.

What is the latest Anthropic API version header value?

apps/frontend/src/main/claude-profile/usage-monitor.ts (5)

36-39: Good addition of retry mechanism constants.

The CLI fallback retry threshold (5 consecutive successes before retrying API) is a reasonable heuristic to avoid permanent fallback while not thrashing between methods.

---

136-176: Appropriate scoping of proactive swap to OAuth profiles only.

The check at line 138 correctly ensures that automatic profile switching only occurs for anthropic-oauth providers, as Z.ai and other API profiles don't support multi-account switching. The threshold logic is sound.

---

309-323: LGTM on the CLI fallback retry mechanism.

The implementation correctly tracks consecutive CLI successes and re-enables API attempts after the threshold, preventing permanent fallback while avoiding excessive API retry attempts.

---

366-373: Environment sanitization is a good practice.

Filtering out undefined values from process.env before passing to spawn prevents potential issues with some spawn implementations that don't handle undefined env values gracefully.

---

455-507: Well-structured proactive swap implementation.

Good practices:

• Uses Set for efficient exclusion checking
• Profiles are pre-sorted by availability
• Detailed event emissions for both success and failure cases
• Comment on line 505-506 correctly notes the intentional delay to prevent cascading swaps

[coderabbitai]

🧹 Nitpick | 🔵 Trivial

Consider graceful handling of individual reset time parsing failures.

If parseResetTime throws for one value (e.g., malformed session reset), the entire snapshot is discarded. You could wrap each call individually to preserve partial data.

♻️ Optional: Individual error handling

const sessionResetTimestamp = (() => {
  try {
    return usageData.sessionResetTime 
      ? parseResetTime(usageData.sessionResetTime).getTime() 
      : undefined;
  } catch { return undefined; }
})();

const weeklyResetTimestamp = (() => {
  try {
    return usageData.weeklyResetTime 
      ? parseResetTime(usageData.weeklyResetTime).getTime() 
      : undefined;
  } catch { return undefined; }
})();

🤖 Prompt for AI Agents

In @apps/frontend/src/main/claude-profile/usage-monitor.ts around lines 406 -
413, Wrap each parseResetTime call separately so a thrown error for one reset
string doesn't discard the whole snapshot: when computing sessionResetTimestamp
and weeklyResetTimestamp from usageData.sessionResetTime and
usageData.weeklyResetTime, catch errors per-call (e.g., try/catch or small
self-invoking helper) and return undefined on failure so parseResetTime
exceptions only affect that timestamp and not the other fields or the overall
snapshot.

[coderabbitai]

🧹 Nitpick | 🔵 Trivial

Good defensive guards, but consider typing the event data.

The mainWindow.isDestroyed() checks are a good safeguard against sending IPC messages to destroyed windows, preventing potential crashes.

However, the data: any parameter types on lines 770 and 780 could be replaced with proper interfaces for better type safety.

♻️ Optional: Add typed event payloads

// Define in shared types
interface ProactiveSwapCompletedData {
  fromProfile: { id: string; name?: string };
  toProfile: { id: string; name: string };
  limitType: 'session' | 'weekly';
  timestamp: Date;
}

interface ProactiveSwapFailedData {
  reason: string;
  currentProfile: string;
  excludedProfiles: string[];
}

Then use these types instead of any in the event handlers.

🤖 Prompt for AI Agents

In @apps/frontend/src/main/ipc-handlers/terminal-handlers.ts around lines 764 -
794, The handlers for monitor.on('proactive-swap-completed') and
monitor.on('proactive-swap-failed') use data: any — replace these with explicit
typed payloads (e.g., ProactiveSwapCompletedData and ProactiveSwapFailedData)
defined in a shared types file and import them into terminal-handlers.ts, then
update the event listener signatures to use those interfaces (and likewise type
the show-swap-notification parameter if you have a Notification type); keep the
existing mainWindow.isDestroyed() guards and ensure the typed payloads match the
IPC shape you send via IPC_CHANNELS.PROACTIVE_SWAP_NOTIFICATION.

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

apps/frontend/src/main/ipc-handlers/terminal-handlers.ts (1)

785-822: Consider cleaning up event listeners when window is destroyed.

The event listeners on the UsageMonitor singleton are never removed. If mainWindow is destroyed and recreated (e.g., on macOS when app is reactivated), old listeners pointing to destroyed window references will accumulate. Consider using mainWindow.on('closed', ...) to clean up listeners.

♻️ Suggested approach

 export function initializeUsageMonitorForwarding(mainWindow: BrowserWindow): void {
   const monitor = getUsageMonitor();

+  const usageHandler = (usage: ClaudeUsageSnapshot) => {
+    if (!mainWindow.isDestroyed()) {
+      mainWindow.webContents.send(IPC_CHANNELS.USAGE_UPDATED, usage);
+    }
+  };
+
+  const swapCompletedHandler = (data: any) => {
+    if (!mainWindow.isDestroyed()) {
+      mainWindow.webContents.send(IPC_CHANNELS.PROACTIVE_SWAP_NOTIFICATION, {
+        type: 'completed',
+        ...data
+      });
+    }
+  };
+
+  // ... similar for other handlers
+
+  monitor.on('usage-updated', usageHandler);
+  monitor.on('proactive-swap-completed', swapCompletedHandler);
+  // ... other listeners
+
+  // Cleanup listeners when window is closed
+  mainWindow.on('closed', () => {
+    monitor.off('usage-updated', usageHandler);
+    monitor.off('proactive-swap-completed', swapCompletedHandler);
+    // ... other cleanup
+  });

   debugLog('[terminal-handlers] Usage monitor event forwarding initialized');
 }

🤖 Fix all issues with AI agents

In @apps/frontend/src/main/claude-profile/usage-monitor.ts:
- Around line 402-407: The timeout handler currently calls proc.kill() (which
sends SIGTERM) causing possible delayed shutdown; update the timeout callback in
UsageMonitor where timeoutId/timedOut are set to call proc.kill('SIGKILL') to
force immediate termination (and keep the existing timedOut = true and
resolve(null) behavior); ensure the change targets the anonymous timeout
function that uses UsageMonitor.CLI_USAGE_TIMEOUT_MS so the process is
hard-killed on timeout.
- Around line 378-381: The cleanEnv creation filters out only undefined values
from mergedEnv, but nulls remain and may become the string "null" downstream;
update the filter used in
Object.fromEntries(Object.entries(mergedEnv).filter(...)) to exclude both
undefined and null (e.g., value !== undefined && value !== null) so cleanEnv
contains only real string values before it's used in spawn or other APIs.

In @apps/frontend/src/main/ipc-handlers/terminal-handlers.ts:
- Around line 796-802: Event handlers use untyped parameters; define interfaces
(e.g., ProactiveSwapCompletedPayload and ProactiveSwapFailedPayload) describing
the expected fields, then replace the any types in the monitor.on callbacks
(e.g., the handler registered for 'proactive-swap-completed' and the one for
'proactive-swap-failed') with the new interfaces; ensure the payload shapes
match what you spread into the IPC message and update imports/exports as needed
so TypeScript enforces the event payload shape.

In @apps/frontend/src/renderer/components/UsageIndicator.tsx:
- Around line 95-107: The periodic refresh ignores failures from
window.electronAPI.getAPIProfileUsage(); update the setInterval callback in
UsageIndicator to handle errors: add a .catch to the promise and handle
non-success responses (result.success === false) by logging the error (console
or existing logger) and updating component state to reflect an error (e.g.,
introduce setUsageError or setUsage(null) so the UI can show stale/errored state
or a toast). Ensure you still call setUsage(result.data) only on success, and
leave the unsubscribe() and clearInterval(intervalId) cleanup unchanged.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 5506449 and a2a4d0b.

📒 Files selected for processing (9)

• apps/frontend/src/main/claude-profile/usage-monitor.ts
• apps/frontend/src/main/ipc-handlers/terminal-handlers.ts
• apps/frontend/src/main/services/profile/index.ts
• apps/frontend/src/main/services/profile/profile-usage.ts
• apps/frontend/src/preload/api/profile-api.ts
• apps/frontend/src/renderer/components/UsageIndicator.tsx
• apps/frontend/src/renderer/lib/browser-mock.ts
• apps/frontend/src/shared/constants/ipc.ts
• apps/frontend/src/shared/types/ipc.ts

🧰 Additional context used

📓 Path-based instructions (2)

apps/frontend/src/**/*.{tsx,ts}

📄 CodeRabbit inference engine (CLAUDE.md)

apps/frontend/src/**/*.{tsx,ts}: Use i18n translation keys for all user-facing text in the frontend. All labels, buttons, messages must use translation keys from react-i18next with namespace:section.key format (e.g., 'navigation:items.githubPRs').
Never use hardcoded strings for UI text in JSX/TSX files. Always use translation keys via useTranslation() hook.

Files:

• apps/frontend/src/renderer/components/UsageIndicator.tsx
• apps/frontend/src/main/services/profile/index.ts
• apps/frontend/src/shared/constants/ipc.ts
• apps/frontend/src/preload/api/profile-api.ts
• apps/frontend/src/main/ipc-handlers/terminal-handlers.ts
• apps/frontend/src/main/services/profile/profile-usage.ts
• apps/frontend/src/shared/types/ipc.ts
• apps/frontend/src/renderer/lib/browser-mock.ts
• apps/frontend/src/main/claude-profile/usage-monitor.ts

apps/frontend/**/*.{ts,tsx}

⚙️ CodeRabbit configuration file

apps/frontend/**/*.{ts,tsx}: Review React patterns and TypeScript type safety.
Check for proper state management and component composition.

Files:

• apps/frontend/src/renderer/components/UsageIndicator.tsx
• apps/frontend/src/main/services/profile/index.ts
• apps/frontend/src/shared/constants/ipc.ts
• apps/frontend/src/preload/api/profile-api.ts
• apps/frontend/src/main/ipc-handlers/terminal-handlers.ts
• apps/frontend/src/main/services/profile/profile-usage.ts
• apps/frontend/src/shared/types/ipc.ts
• apps/frontend/src/renderer/lib/browser-mock.ts
• apps/frontend/src/main/claude-profile/usage-monitor.ts

🧠 Learnings (4)

📓 Common learnings

Learnt from: MikeeBuilds
Repo: AndyMik90/Auto-Claude PR: 661
File: apps/frontend/src/renderer/components/onboarding/OllamaModelSelector.tsx:176-189
Timestamp: 2026-01-04T23:59:48.743Z
Learning: In the AndyMik90/Auto-Claude repository, pre-existing i18n issues (hardcoded user-facing strings that should be localized) can be deferred to future i18n cleanup passes rather than requiring immediate fixes in PRs that don't introduce new i18n violations.

📚 Learning: 2026-01-12T13:47:32.539Z

Learnt from: CR
Repo: AndyMik90/Auto-Claude PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-12T13:47:32.539Z
Learning: Applies to apps/frontend/src/**/*.{tsx,ts} : Use i18n translation keys for all user-facing text in the frontend. All labels, buttons, messages must use translation keys from react-i18next with namespace:section.key format (e.g., 'navigation:items.githubPRs').

Applied to files:

• apps/frontend/src/renderer/components/UsageIndicator.tsx
• apps/frontend/src/main/services/profile/profile-usage.ts

📚 Learning: 2026-01-12T13:47:32.539Z

Learnt from: CR
Repo: AndyMik90/Auto-Claude PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-12T13:47:32.539Z
Learning: Applies to apps/frontend/src/**/*.{tsx,ts} : Never use hardcoded strings for UI text in JSX/TSX files. Always use translation keys via useTranslation() hook.

Applied to files:

• apps/frontend/src/renderer/components/UsageIndicator.tsx
• apps/frontend/src/main/services/profile/profile-usage.ts

📚 Learning: 2026-01-04T23:59:45.209Z

Learnt from: MikeeBuilds
Repo: AndyMik90/Auto-Claude PR: 661
File: apps/frontend/src/renderer/components/onboarding/OllamaModelSelector.tsx:176-189
Timestamp: 2026-01-04T23:59:45.209Z
Learning: In the AndyMik90/Auto-Claude repository, pre-existing i18n issues (hardcoded user-facing strings) can be deferred for future i18n cleanup passes. Do not fix such issues in PRs that do not introduce new i18n violations, especially in frontend TSX components (e.g., apps/frontend/**/*.tsx). If a PR adds new i18n violations, address them in that PR.

Applied to files:

• apps/frontend/src/renderer/components/UsageIndicator.tsx

🧬 Code graph analysis (4)

apps/frontend/src/renderer/components/UsageIndicator.tsx (2)

apps/frontend/src/shared/types/agent.ts (2)

• ClaudeUsageSnapshot (42-65)
• RESETTING_SOON (14-14)

apps/frontend/src/main/services/profile/index.ts (1)

• RESETTING_SOON (57-57)

apps/frontend/src/preload/api/profile-api.ts (2)

apps/frontend/src/shared/types/agent.ts (1)

• ClaudeUsageSnapshot (42-65)

apps/frontend/src/__mocks__/electron.ts (1)

• ipcRenderer (53-61)

apps/frontend/src/main/services/profile/profile-usage.ts (1)

apps/frontend/src/shared/types/agent.ts (2)

• ClaudeUsageSnapshot (42-65)
• RESETTING_SOON (14-14)

apps/frontend/src/shared/types/ipc.ts (3)

apps/frontend/src/shared/types/task.ts (1)

• ImageAttachment (117-125)

apps/frontend/src/shared/types/terminal.ts (1)

• TerminalWorktreeConfig (146-163)

apps/frontend/src/shared/types/agent.ts (1)

• ClaudeUsageSnapshot (42-65)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Seer Code Review

🔇 Additional comments (20)

apps/frontend/src/shared/types/ipc.ts (1)

45-46: LGTM!

The new IPC type definitions are well-structured and properly typed:

• ImageAttachment import and submitReview signature extension correctly support image attachments in reviews
• New terminal event listeners (onTerminalWorktreeConfigChange, onTerminalClaudeExit) align with the types in terminal.ts
• getAPIProfileUsage returns IPCResult<ClaudeUsageSnapshot> matching the usage service implementation
• Claude Code CLI operations are consistently typed with the existing patterns

Also applies to: 162-162, 223-225, 244-245, 309-309, 598-598, 777-780

apps/frontend/src/shared/constants/ipc.ts (1)

91-91: LGTM!

The new IPC channel constants follow the established naming conventions and align with the corresponding type definitions in ipc.ts. The channel names are descriptive and consistent with the existing codebase patterns.

Also applies to: 98-98, 135-135, 484-484, 512-515

apps/frontend/src/main/services/profile/profile-usage.ts (5)

1-14: Well-structured module with proper separation of concerns.

The imports are clean and the module organization with clear section headers improves readability. Good use of the shared RESETTING_SOON constant for consistency across frontend and backend.

---

88-114: LGTM!

Provider detection logic is sound:

• Proper URL parsing with error handling
• Correct domain matching for Z.ai (including subdomains)
• OAuth token identification via sk-ant-oat01- prefix
• Safe fallback to 'other' for invalid URLs or unknown providers

---

124-193: Z.ai usage fetching looks good with proper timeout and error handling.

One observation on the limitType determination at line 181:

limitType: tokenPercent > toolPercent ? 'session' : 'weekly',

For Z.ai, sessionPercent represents token usage and weeklyPercent represents tool/time usage. These are distinct quota types rather than the same metric over different time windows (unlike Anthropic's 5-hour vs 7-day). The comparison is technically valid for determining which limit is higher, but the semantic meaning differs from Anthropic's model.

This appears intentional for UI consistency—flagging for verification that the downstream UI correctly interprets this for Z.ai.

---

208-278: LGTM!

The Anthropic OAuth usage fetching is well-implemented:

• Proper AbortController timeout pattern
• Correct re-throwing of ApiAuthError for auth failures
• Bounds validation on percentages with Math.max(0, Math.min(100, ...))
• Appropriate anthropic-version header included

---

334-381: LGTM!

The fetchActiveProfileUsage function properly orchestrates the usage fetching flow with appropriate error handling and structured result types.

apps/frontend/src/renderer/components/UsageIndicator.tsx (4)

9-11: Good i18n setup and imports.

The useTranslation('navigation') hook and RESETTING_SOON import are correctly configured. All user-facing text properly uses translation keys as per coding guidelines.

Also applies to: 19-19, 22-22

---

28-77: Well-implemented countdown logic.

The calculateCountdown and formatResetTime callbacks are correctly memoized with useCallback. The per-second interval for countdown updates is properly cleaned up and only runs when usage is at 99% or higher—avoiding unnecessary timers.

---

129-132: Provider-specific labels and tooltip content are correctly internationalized.

All labels use appropriate i18n keys with the namespace:section.key format:

• usageIndicator.tokenUsage / usageIndicator.sessionUsage for session label
• usageIndicator.monthlyToolUsage / usageIndicator.weeklyUsage for weekly label
• usageIndicator.resets, usageIndicator.activeAccount, usageIndicator.ariaLabel

This follows the coding guidelines for frontend i18n compliance.

Also applies to: 160-170, 187-196, 214-218

---

143-155: Nice UX touch with the pulsing clock icon for high usage states.

The conditional rendering of Clock with animate-pulse when countdown is active provides clear visual feedback. The countdown text display alongside the percentage is well-integrated.

apps/frontend/src/main/services/profile/index.ts (1)

34-57: LGTM!

The barrel exports are well-organized and follow the existing patterns in the file. Re-exporting RESETTING_SOON from the shared types provides convenient access for consumers of the profile service module.

apps/frontend/src/main/claude-profile/usage-monitor.ts (3)

34-40: LGTM on swap loop protection and retry mechanism.

The auth failure cooldown tracking and CLI fallback retry threshold are good additions to prevent swap loops and gracefully recover API access after temporary failures.

---

114-220: LGTM on checkUsageAndSwap logic.

The concurrent check prevention, provider-specific swap logic, and auth failure tracking with cooldown cleanup are well-implemented. The isChecking flag in finally ensures proper state reset even on exceptions.

---

467-519: LGTM on proactive swap logic.

Good use of Set for deduplication, proper exclusion handling for auth-failed profiles, and the deliberate decision to not immediately check the new profile to prevent cascading swaps is well-documented.

apps/frontend/src/preload/api/profile-api.ts (1)

33-34: LGTM on getAPIProfileUsage addition.

The new method follows the established IPC pattern in this file and correctly types the return value as IPCResult<ClaudeUsageSnapshot>.

Also applies to: 79-81

apps/frontend/src/main/ipc-handlers/terminal-handlers.ts (2)

55-72: LGTM on async settings read wrapper.

Wrapping the Claude invocation in an async IIFE to avoid blocking the main process during settings read is the right approach. The error is properly caught and logged.

---

610-633: LGTM on PROFILES_GET_USAGE handler.

The handler correctly validates both result.success and result.usage before returning, with appropriate error fallback messages. The dynamic import pattern for the profile service is consistent with the codebase.

apps/frontend/src/renderer/lib/browser-mock.ts (2)

149-164: LGTM on getAPIProfileUsage mock.

The mock provides reasonable default values for browser testing. The structure aligns with the ClaudeUsageSnapshot type from apps/frontend/src/shared/types/agent.ts.

---

270-297: LGTM on Claude Code management mocks.

The new mocks for getClaudeCodeVersions, installClaudeCodeVersion, getClaudeCodeInstallations, and setClaudeCodeActivePath provide sensible default data for browser-based UI development and testing.

[coderabbitai]

🧹 Nitpick | 🔵 Trivial

Consider also filtering null values from environment.

The filter removes undefined but not null. While env vars should typically be strings, null values would be stringified to "null" by the spawn API, which could cause unexpected behavior.

♻️ Suggested change

         // Remove undefined values
         const cleanEnv = Object.fromEntries(
-          Object.entries(mergedEnv).filter(([_, value]) => value !== undefined)
+          Object.entries(mergedEnv).filter(([_, value]) => value != null)
         ) as Record<string, string>;

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	// Remove undefined values
	const cleanEnv = Object.fromEntries(
	Object.entries(mergedEnv).filter(([_, value]) => value !== undefined)
	) as Record<string, string>;
	// Remove undefined values
	const cleanEnv = Object.fromEntries(
	Object.entries(mergedEnv).filter(([_, value]) => value != null)
	) as Record<string, string>;

🤖 Prompt for AI Agents

In @apps/frontend/src/main/claude-profile/usage-monitor.ts around lines 378 -
381, The cleanEnv creation filters out only undefined values from mergedEnv, but
nulls remain and may become the string "null" downstream; update the filter used
in Object.fromEntries(Object.entries(mergedEnv).filter(...)) to exclude both
undefined and null (e.g., value !== undefined && value !== null) so cleanEnv
contains only real string values before it's used in spawn or other APIs.

[coderabbitai]

🧹 Nitpick | 🔵 Trivial

Consider typing event data parameters.

The data: any parameters in the event handlers could be typed for better maintainability. Consider defining interfaces for swap completion/failure event payloads.

Also applies to: 806-812

🤖 Prompt for AI Agents

In @apps/frontend/src/main/ipc-handlers/terminal-handlers.ts around lines 796 -
802, Event handlers use untyped parameters; define interfaces (e.g.,
ProactiveSwapCompletedPayload and ProactiveSwapFailedPayload) describing the
expected fields, then replace the any types in the monitor.on callbacks (e.g.,
the handler registered for 'proactive-swap-completed' and the one for
'proactive-swap-failed') with the new interfaces; ensure the payload shapes
match what you spread into the IPC message and update imports/exports as needed
so TypeScript enforces the event payload shape.

[coderabbitai]

🧹 Nitpick | 🔵 Trivial

Consider handling errors in the periodic refresh.

The 30-second refresh interval silently ignores failures. If getAPIProfileUsage() starts failing (e.g., network issues, auth expiry), the user sees stale data without indication.

Optional: Add error handling for refresh failures

     // Set up interval to refresh usage every 30 seconds
     const intervalId = setInterval(() => {
       window.electronAPI.getAPIProfileUsage().then((result) => {
         if (result.success && result.data) {
           setUsage(result.data);
+        } else if (!result.success) {
+          // Optionally hide stale data or show error state
+          // setIsVisible(false);
+          console.warn('[UsageIndicator] Refresh failed:', result.error);
         }
       });
     }, 30000); // 30 seconds

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	// Set up interval to refresh usage every 30 seconds
	const intervalId = setInterval(() => {
	window.electronAPI.getAPIProfileUsage().then((result) => {
	if (result.success && result.data) {
	setUsage(result.data);
	}
	});
	}, 30000); // 30 seconds
	return () => {
	unsubscribe();
	clearInterval(intervalId);
	};
	// Set up interval to refresh usage every 30 seconds
	const intervalId = setInterval(() => {
	window.electronAPI.getAPIProfileUsage().then((result) => {
	if (result.success && result.data) {
	setUsage(result.data);
	} else if (!result.success) {
	// Optionally hide stale data or show error state
	// setIsVisible(false);
	console.warn('[UsageIndicator] Refresh failed:', result.error);
	}
	});
	}, 30000); // 30 seconds
	return () => {
	unsubscribe();
	clearInterval(intervalId);
	};

🤖 Prompt for AI Agents

In @apps/frontend/src/renderer/components/UsageIndicator.tsx around lines 95 -
107, The periodic refresh ignores failures from
window.electronAPI.getAPIProfileUsage(); update the setInterval callback in
UsageIndicator to handle errors: add a .catch to the promise and handle
non-success responses (result.success === false) by logging the error (console
or existing logger) and updating component state to reflect an error (e.g.,
introduce setUsageError or setUsage(null) so the UI can show stale/errored state
or a toast). Ensure you still call setUsage(result.data) only on success, and
leave the unsubscribe() and clearInterval(intervalId) cleanup unchanged.

[sentry]

Bug: fetchActiveProfileUsage doesn't check for OAuth profiles, causing the usage badge to fail on initial load for OAuth users.
_{Severity: MEDIUM}

Suggested Fix

Modify fetchActiveProfileUsage to also check for an active OAuth profile, likely via ClaudeProfileManager, when no active API key profile is found. This will ensure usage data is fetched immediately on load for both authentication methods.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: apps/frontend/src/main/services/profile/profile-usage.ts#L334-L337

Potential issue: The `fetchActiveProfileUsage` function is intended to support both
OAuth and API key profiles, as indicated by code comments. However, its implementation
only checks for an active profile in the API profiles file via `loadProfilesFile()`. It
does not check for active OAuth profiles managed by `ClaudeProfileManager`.
Consequently, for OAuth users, `file.activeProfileId` will be `null` on initial load,
causing the function to return an error. This prevents the usage badge from being
displayed until the `UsageMonitor` provides an update, which can be delayed by up to 30
seconds.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

[StillKnotKnown]

Branch diversion, will recreate PR