Repository navigation
Add notch hover usage overlay - #3164
wdmitchelluk wants to merge 72 commits into
Conversation
|
🦞👀 Pull request received. I will update this pull request when review starts. ClawSweeper review completeClawSweeper finished reviewing this revision. The review result is being finalized. |
|
Codex review: needs real behavior proof before merge. What this changesAdds an opt-in notch dashboard with provider usage, configurable summaries, agent sessions, and hover or keyboard activation. Example: On a notched MacBook, enable the overlay and hover over the camera housing for 350 milliseconds.
Review scores
ProductKind: Feature · Worth it: Needs a maintainer decision Merge readiness⛔ Blocked before merge - 2 items remain Keep open: this PR contains useful, owner-engaged feature work absent from main, but its later ears and independent-session additions need a scoped product decision. Priority: P3 Decision needed
Before merge
FindingsNone. Tests
Agent review detailsHow this fits togetherThe AppKit overlay controller receives hover, shortcut, settings, and display events, then renders SwiftUI content from the existing usage and agent-session stores. flowchart TD
A[Settings and shortcuts] --> B[Overlay controller]
C[Notch hover and display events] --> B
D[Usage store] --> E[Overlay model]
F[Shared agent session store] --> E
E --> G[SwiftUI dashboard and ears]
B --> G
Technical reviewBest possible solution: Retain the shared-store, opt-in dashboard and settle the later ears and independent-session scope with the owner before landing. Do we have a high-confidence way to reproduce the issue? This PR adds a new interaction surface rather than addressing a reported current-main failure. Is this the best way to solve the issue? Reusing shared provider presentation and the existing session scanner is appropriate; expanding into interactive menu-bar space requires a separate owner choice. AGENTS.md: found and applied where relevant. Codex review notes: model internal, reasoning medium; reviewed against 3eda0841d85f. Provenance checked
TestingProof path: shipped entry point. SecurityNone. EvidenceWhat I checked:
Likely related people:
LabelsLabel changes:
Label justifications:
Rank-up movesOptional improvements that raise the rating; they are not merge blockers.
Rating scale6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior. WorkflowClawSweeper edits this one comment on every review. Comment HistoryReview history (45 earlier review cycles; latest 8 shown)
Reviewed October 21, 2026, 7:13 PM ET / 23:13 UTC (Revision 46). |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d2f342ed97
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
d2f342e to
74e3b41
Compare
|
Both review findings are fixed in f3b6fec, and the branch is rebased onto current main (merge state is clean now):
|
|
Fixed in ab83688: all three bar factories (
|
steipete
left a comment
There was a problem hiding this comment.
Really nice work overall — the self-reported sizing approach and the no-global-monitor/no-AX design are exactly right, and the focused suites plus make check all pass on a merge with latest main. Four findings before this can land, two of them blocking:
P1 — Disabled feature still registers a global shortcut. NotchUsageOverlayController.swift:54 installs the KeyboardShortcuts handlers unconditionally, and the dependency registers any saved shortcut system-wide the moment a handler is attached. Disabling the overlay never unregisters it, and PreferencesNotchPane.swift:38 allows recording a shortcut while the feature is off. That breaks the off-by-default guarantee and can steal shortcuts from other apps. Handlers should only exist while the overlay is enabled.
P1 — Any settings change destroys an expanded overlay. The activation observation (NotchUsageOverlayController.swift:123) reads a computed property backed by the whole observable defaults struct, so unrelated preference changes re-fire it; at line 143 an existing panel is preserved only when collapsed — an expanded panel is closed and recreated, losing hover/shortcut state. Please narrow the observation to the fields that actually affect activation, and preserve an expanded panel across benign changes.
P2 — Controller restarts accumulate shortcut handlers. Handlers registered at line 71 are never removed on stop; each stop/start adds another callback, and in Toggle mode two callbacks make one press open-and-immediately-close the panel. The dependency ships KeyboardShortcuts.removeHandler(for:) for exactly this lifecycle.
P2 — Codex credits aren't actually a fallback. NotchUsageOverlayModel.swift:191 appends monthly credits whenever fewer than four bars exist, even when the extra window/spend bar was already chosen — a Codex account with two ordinary windows shows both, contradicting the documented mutually-exclusive fallback. Gate the append on the fallback slot being unfilled.
Happy to merge once these are addressed — the feature itself is a great addition.
4521c61 to
8fb9030
Compare
|
Addressed all four findings in 8fb9030 (rebased onto current main):
Verification on the rebased head:
@clawsweeper please re-review the current head. |
# Conflicts: # Sources/CodexBar/Resources/ar.lproj/Localizable.strings # Sources/CodexBar/Resources/ca.lproj/Localizable.strings # Sources/CodexBar/Resources/de.lproj/Localizable.strings # Sources/CodexBar/Resources/en.lproj/Localizable.strings # Sources/CodexBar/Resources/es.lproj/Localizable.strings # Sources/CodexBar/Resources/fa.lproj/Localizable.strings # Sources/CodexBar/Resources/fr.lproj/Localizable.strings # Sources/CodexBar/Resources/gl.lproj/Localizable.strings # Sources/CodexBar/Resources/id.lproj/Localizable.strings # Sources/CodexBar/Resources/it.lproj/Localizable.strings # Sources/CodexBar/Resources/ja.lproj/Localizable.strings # Sources/CodexBar/Resources/ko.lproj/Localizable.strings # Sources/CodexBar/Resources/nl.lproj/Localizable.strings # Sources/CodexBar/Resources/pl.lproj/Localizable.strings # Sources/CodexBar/Resources/pt-BR.lproj/Localizable.strings # Sources/CodexBar/Resources/ru.lproj/Localizable.strings # Sources/CodexBar/Resources/sv.lproj/Localizable.strings # Sources/CodexBar/Resources/th.lproj/Localizable.strings # Sources/CodexBar/Resources/tr.lproj/Localizable.strings # Sources/CodexBar/Resources/uk.lproj/Localizable.strings # Sources/CodexBar/Resources/vi.lproj/Localizable.strings # Sources/CodexBar/Resources/zh-Hans.lproj/Localizable.strings # Sources/CodexBar/Resources/zh-Hant.lproj/Localizable.strings
|
@steipete Do you want me to close this PR / you don't plan on adding this functionality?, or should I just leave it open to be looked at for a future release? |
Bring the opt-in notch overlay forward without changing the status-item lifecycle. Use shared provider visibility, reset labels, and icon resources; reuse the settings recorder and inject shortcut registration in tests. Fit both scrolling sections inside the screen-clamped content window and add isolated synthetic renders and regression coverage. Keep the existing native interaction review hold explicit. Co-authored-by: William Mitchell <wdmitchell.uk@gmail.com>
|
Thanks @wdmitchelluk. The overlay has been reviewed and improved in place at 7fa0df8 (your commits are preserved): it is opt-in, self-contained, uses public AppKit APIs, installs no shortcuts and performs no screen lookups while disabled, and the focused and full local suites pass. What remains is the native interaction proof the owner asked for earlier in this thread, which synthetic renders cannot provide; the PR stays open until that hover check on a notch Mac is done. |
|
@steipete — I merged current The PR description now includes eight native screenshots and five short recordings from a notched Mac: ears on/off, provider-grouped ear options, independent session settings/columns, hover and both shortcut modes, native click ownership, independent scrolling, disablement, and shutdown. Providers are real; extra QA agent sessions were inert local processes. The updated design intentionally changes the earlier click-through requirement: optional notch ears extend the same opaque popover and animation into the space beside the camera. They own the covered menu-bar pixels only while the panel is expanded by hover or shortcut; dismissal releases that area. This makes room for reset credits and expiry without consuming the main dashboard. Independent notch/Menu session toggles let the two surfaces serve different purposes without forced duplication, with separate session columns or one column per harness. Validation passed: The description also records the limits: native click delivery was checked with controlled underlying windows; fullscreen/external-display/light-appearance checks were not run. The Claude reset screenshots now use the earlier verified live |
What this adds
An opt-in usage dashboard at the MacBook camera notch, configured in Settings → Notch. Hover or an optional Toggle/Hold shortcut shows real provider usage and an optional agent-session section. The feature is off by default. Disabled mode creates no windows, performs no screen lookup, and installs no shortcut handlers.
Optional notch ears
The Notch ears toggle extends the same popover to the top of the screen, using the space on either side of the camera. Ears and dashboard share one opaque background and one animation, with square top corners. Turning ears off removes only that upper row; the main dashboard remains available.
The ears intentionally cover and receive clicks in the menu-bar area they occupy while expanded. This is a deliberate, optional tradeoff: the popover appears only after hovering the notch or using the shortcut, and the extra space provides useful at-a-glance information without taking space from provider tiles. Covered menu items become accessible again when the panel closes or ears are disabled. Collapse disables mouse handling immediately, including during the closing animation. The camera-sized hover trigger never widens.
Each ear has its own picker, grouped by provider. Codex and Claude offer Limit Reset Credits and Limit Reset Credits + Expiry separately. Expiry includes days when space permits, falls back to the count in narrower layouts, and retains full details for accessibility/help. Explicit selections keep the provider logo and 0 available for a known empty inventory; missing data remains Unavailable. Claude already had live reset-inventory fetching; this change preserves a valid empty/spent/expired inventory as known zero while still rejecting malformed-only data. The menu's existing zero-hiding behavior is unchanged.
Independent agent sessions
Agent sessions can be enabled in the notch while disabled in Settings → Menu. This lets the menu focus on usage and the notch focus on running work, avoiding forced duplication. Both surfaces use the same session store and scanner. Current main's separate remote-sessions consent still governs discovery and SSH polling.
The agent section has its own column setting: Match providers by default, 1–4 columns, or Column per harness (one column per tool). It also has independent height/scrolling and above/below placement. Provider columns, order, visibility, and height remain separately configurable.
Provider tiles continue to use shared first-party presentation, provider-owned labels, visibility preferences, account-scoped data, reset formatting, error redaction, and the existing brand/monochrome logo assets. No synthetic providers or second scanner were introduced.
Integration and verification
Updated to upstream main
8928b6ee4c8069f283d4621486ffbeaf8086cb12in merge commit935420784af5e5611dd7e7a9e93d181a237f7370, preserving the existing contributor and maintainer commits. Main gained nine commits after the previous update. The only manual conflict was in the changelog: all upstream entries were retained, and the notch entry was moved lower in the same Unreleased section to reduce repeated conflicts when main prepends entries. The auto-merged translation catalogs retain main's Ukrainian corrections and the notch strings.8928b6ee4.make check: passed, zero violations across 3,105 Swift files, including localization and repository checks. The merged app compiled successfully.git diff --checkpasses and the worktree is clean.The preceding head
95e5707c3passed 322 Swift Testing tests in 30 suites, plus 1 XCTest check (2 opt-in render exports skipped). It also fixed a test-only dependency on the host's Low Power Mode: both scheduler test factories inject normal power and nominal thermal state through the existing seam. Production behavior and system settings are unchanged. Final test commands use the BashScripts/test_environment.shwith Keychain suppression and session-file isolation explicitly checked.Main also includes #4576's clearer guidance for a temporarily unavailable Keychain cache. It changes no credential read path or prompt policy.
Earlier integration and validation (
21b143b25)The earlier main integration resolved shared settings, launch lifecycle, agent-session, changelog, and localization conflicts.
That earlier main integration also exposed a Swift Charts overload/availability error with the current SDK. Moving conditional bar styling into an explicit
@ChartContentBuilderhelper preserves rendering and the macOS 14 deployment target; the OpenAI live-usage tests are included in verification.The following full-suite and native-bundle results are for the earlier head
21b143b25aa8805b7c774c69d282e520adbd6c5e, not the latest main update:make check: passed, zero violations across 3,084 Swift files, including localization and repository checks../Scripts/test.sh --swift-command <native-wrapper> --direct-workers 4; the wrapper forwards build/test to Swift with--build-system native --jobs 4 -Xswiftc -gnone.Scripts/test_environment.shfor credential scrubbing, session-file isolation, and Keychain suppression.git diff --checkpasses and the worktree is clean.CI for that earlier head was started at the previous publication: run 39689208838. At that publication, change detection passed; macOS tests, Linux builds, lint, and GitGuardian were in progress. No final CI conclusion is claimed.
Native evidence
Native captures from signed bundles on a notched Mac, using real provider accounts. These captures predate the latest main update; the post-merge captures below are from
21b143b25. The ears-enabled and single-session-column screenshots use the earlier verified live Claude 0 available state, captured before the main-branch merge. The settings screenshots, ears-disabled screenshot, and interaction recordings are from the merged build. Additional QA agent sessions are inert local test processes. Screenshots and recordings are cropped to the relevant UI.Ears enabled and disabled
Ears enabled: one opaque panel, square top corners, provider logos, Codex reset credits, Claude 0 available, and sessions grouped by harness. This is the earlier live capture before the main-branch merge.
Ears disabled: the same dashboard begins below the camera/menu-bar row.
Separate post-merge native window inspection confirms the same expanded window ID in both states: enabled
(679, 0, 690, 408)at layer 26; disabled(679, 40, 690, 368)at layer 25. Enabling ears adds exactly the 40-point camera row while preserving the dashboard's bottom edge. The separate nonactivating trigger remains camera-sized(913, 0, 222, 40).Ear values, grouped by provider
Independent agent-session controls
The notch screenshots above have sessions enabled while Menu sessions are disabled:
Two provider columns with one independently configured session column and Claude 0 available. This is the earlier live capture before the main-branch merge:
Native interaction recordings
Earlier live Claude zero-credit state
This is an earlier native capture after an explicitly approved credential refresh, before the main-branch merge. It proves the live known-zero presentation with the Claude logo. The merged-build interaction recordings retain Unavailable after restart under the no-prompt credential policy. The replacement screenshots use the actual earlier live zero-credit state.
Remaining review scope
This updates the previous click-through design: enabled ears intentionally own the covered pixels; ears-off and collapsed states release them. The native evidence documents that boundary for maintainer review. This PR remains open for the owner's normal review and merge decision.
Native checks used the built-in notched display in dark appearance. Fullscreen apps, additional displays, display hot-plugging, and light appearance were not exercised. The observed Claude
Unavailablestate after restart came from the preview launcher forcing Never prompt (and manual refresh), rather than demonstrating a reset-refresh bug. Reset inventory is intentionally live-only; the CLI fallback supplies usage but no reset inventory. Never prompt prevents OAuth-cache recovery/delegated refresh, so absent inventory correctly remains unknown instead of being displayed as zero. The normal app default is Only on user action. No new live credential/restart check was performed for this diagnosis, and no authentication-policy change was added. Temporary QA processes were stopped and the chosen preview settings restored. CI status is reported separately from local verification.