feat(macos): menu bar companion + widget, with CodexBar-style usage monitor integrated into Usage

.github/workflows/ci.yml

@@ -34,6 +34,7 @@ on:
       - "bin/**"
       - "tests/**"
       - "scripts/**"
+      - "app/**"
       - "gui/**"
       - "assets/**"
       - ".gitattributes"
@@ -213,6 +214,7 @@ jobs:
               - 'bin/**'
               - 'tests/**'
               - 'scripts/**'
+              - 'app/**'
               - 'gui/**'
               - 'assets/**'
               - '.gitattributes'
@@ -1147,14 +1149,40 @@ jobs:
   # `if: always()` is load-bearing. Without it, a failed or skipped dependency
   # skips this job too — and GitHub reports a skipped job as success, so the gate
   # would go green precisely when something went wrong.
+  macos-app:
+    name: macos app
+    needs: [changes, gates]
+    if: github.event_name != 'pull_request' || needs.changes.outputs.ci == 'true'
+    runs-on: macos-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: 1.3.14
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Test macOS menu bar app
+        run: bun run test:macos
+
+      - name: Build macOS menu bar app
+        run: bun run build:macos
+
   ci:
     name: ci
     if: always()
     # Every producer, including the ones that only feed other jobs. `needs` holds
     # direct dependencies only, so a failing `select-windows-runner` would
     # otherwise reach this gate as nothing at all while its dependents report
     # `skipped`, which is the shape the step below is written to catch.
-    needs: [changes, select-windows-runner, test, storage-policy, api-usage, gates, platform-macos, macos-control, platform-windows, keyring-smoke, docker-smoke, docs-site-build, structure-gate, npm-global-smoke]
+    needs: [changes, select-windows-runner, test, storage-policy, api-usage, gates, platform-macos, macos-control, platform-windows, keyring-smoke, docker-smoke, docs-site-build, structure-gate, npm-global-smoke, macos-app]
     runs-on: ubuntu-latest
     timeout-minutes: 5
     permissions:
@@ -1220,12 +1248,12 @@ jobs:
           GATED_JOBS="changes select-windows-runner test storage-policy api-usage gates"
           GATED_JOBS="$GATED_JOBS platform-macos keyring-smoke docker-smoke npm-global-smoke"
           GATED_JOBS="$GATED_JOBS macos-control platform-windows docs-site-build"
-          GATED_JOBS="$GATED_JOBS structure-gate"
+          GATED_JOBS="$GATED_JOBS structure-gate macos-app"
 
           expected_for() {
             case "$1" in
               changes|select-windows-runner) echo requested ;;
-              test|storage-policy|api-usage|gates|platform-macos|keyring-smoke|docker-smoke)
+              test|storage-policy|api-usage|gates|platform-macos|keyring-smoke|docker-smoke|macos-app)
                 echo "$scoped" ;;
               npm-global-smoke) echo "$packaging" ;;
               docs-site-build) echo "$docs" ;;

.github/workflows/release.yml

@@ -69,6 +69,75 @@ jobs:
             process.exit(1);
           }
           NODE
+  package-macos:
+    needs: validate-dispatch
+    runs-on: macos-latest
+    timeout-minutes: 20
+    permissions:
+      contents: read
+    outputs:
+      archive_name: ${{ steps.package.outputs.archive_name }}
+      checksum_name: ${{ steps.package.outputs.checksum_name }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+
+      - name: Package the macOS companion
+        id: package
+        env:
+          RELEASE_VERSION: ${{ inputs.version }}
+          UNIVERSAL: "1"
+          # A monotonic numeric CFBundleVersion. Preview versions carry a suffix that
+          # Apple does not accept in that field, so the script uses the numeric core
+          # plus this run number.
+          MACOS_BUILD_NUMBER: ${{ github.run_number }}
+          # NOTE: intentionally no MACOS_SIGN_IDENTITY here. The build script honours
+          # it, but an identity NAME alone cannot sign on a hosted runner — the
+          # certificate and private key are never imported into a keychain, so codesign
+          # fails with "no identity found". Real Developer ID signing needs a protected
+          # P12 import, a temporary keychain, notarytool credentials, and stapling, all
+          # as one security-reviewed change. Until then the asset is ad-hoc signed and
+          # the docs carry the Gatekeeper first-launch path.
+        run: bash scripts/package-macos-release.sh
+
+      - name: Upload the release asset
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: macos-release
+          path: dist/release/
+          if-no-files-found: error
+          retention-days: 7
+
+  attach-macos:
+    runs-on: ubuntu-latest
+    needs: [publish, package-macos]
+    if: ${{ inputs.dry-run != true }}
+    timeout-minutes: 10
+    permissions:
+      contents: write
+    steps:
+      - name: Download the packaged asset
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: macos-release
+          path: dist/release
+
+      - name: Verify the checksum before uploading
+        run: |
+          cd dist/release
+          shasum -a 256 -c ./*.sha256
+
+      - name: Attach to the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          # Workflow inputs reach shell code through env, never by interpolation into
+          # run: source. tests/ci-workflows.test.ts enforces this repo-wide.
+          RELEASE_VERSION: ${{ inputs.version }}
+        run: |
+          gh release upload "v${RELEASE_VERSION}" dist/release/* --clobber
+
   publish:
     needs: validate-dispatch
     runs-on: ubuntu-latest

.gitignore

@@ -70,3 +70,5 @@ go/
 
 # Rust native helpers keep their reproducible sources and lockfile in git, never local artifacts.
 native/**/target/
+dist/macos/
+dist/release/

AGENTS.md

@@ -27,6 +27,11 @@ Bun-native TypeScript with no separate server compile step.
   seeds in `layout.json` place a conventionally named file until then.
   History: `devlog/_fin/260905_test_modularization_and_windows/`.
 - `gui/` — React + Vite dashboard; packaged output is served from `gui/dist`.
+- `app/` — native macOS menu bar companion (Swift + AppKit, no third-party
+  dependencies). `MenuBarCore` is the testable transport/model layer,
+  `MenuBarUI` the AppKit views, `MenuBarApp` the entry point. Its tests are
+  executables, not XCTest bundles — Command Line Tools ships neither a usable
+  XCTest module nor the swift-testing runtime.
 - `docs-site/` — public docs (Astro + Starlight), deployed to GitHub Pages.
 - `go/` — retired Go native-runtime experiment; kept only where the TypeScript
   runtime still references it. New work does not go here.

README.md

@@ -90,6 +90,21 @@ Use `ocx service` to run it in the background.
 Open **http://localhost:10100** and configure everything in the web dashboard — add providers
 (40+ built-ins, or any OpenAI-compatible endpoint), pick models, manage accounts. `ocx gui`
 re-opens the dashboard at any time.
+
+### macOS menu bar app
+
+A native companion for proxy status, usage, and provider quotas without opening the
+dashboard. The source lives in [`app/`](./app) (Swift + AppKit, no third-party
+dependencies). Download it from the
+[releases page](https://github.com/lidge-jun/opencodex/releases) or build it locally with
+`bun run build:macos`.
+
+The first launch needs a right-click → Open, because the app is ad-hoc signed rather
+than notarized. See the [macOS Menu Bar App guide](https://lidge-jun.github.io/opencodex/guides/macos-menu-bar/)
+for the full explanation.
+
+The app also includes a macOS 14+ widget for proxy status, today's usage, and quotas.
+
 It can also manage a **ChatGPT account pool** for Codex auth. Add multiple ChatGPT / Codex accounts,
 refresh their 5h / weekly / 30d quota in the dashboard. Under quota routing, new sessions can use
 the lowest-usage healthy account; round-robin and fill-first use their own policies. Existing Codex

app/.gitignore

@@ -0,0 +1,4 @@
+.build/
+.swiftpm/
+*.xcodeproj
+DerivedData/

app/Info.plist

@@ -0,0 +1,42 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleDevelopmentRegion</key>
+  <string>en</string>
+  <key>CFBundleExecutable</key>
+  <string>OpenCodexMenuBar</string>
+  <key>CFBundleIdentifier</key>
+  <string>com.opencodex.menubar</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleName</key>
+  <string>OpenCodex</string>
+  <key>CFBundleDisplayName</key>
+  <string>OpenCodex</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleIconFile</key>
+  <string>OpenCodex</string>
+  <key>CFBundleShortVersionString</key>
+  <string>0.0.0</string>
+  <key>CFBundleVersion</key>
+  <string>0.0.0</string>
+  <key>LSUIElement</key>
+  <true/>
+  <key>LSMinimumSystemVersion</key>
+  <string>13.0</string>
+  <!-- macOS 14 stopped allowing IP-address loads under App Transport Security by
+       default. The proxy is always plain HTTP on loopback, so without this the
+       packaged bundle cannot reach it at all — while `swift run` stays green because
+       it does not run under this plist. Local networking only; ATS stays enforced
+       for every non-local destination. -->
+  <key>NSAppTransportSecurity</key>
+  <dict>
+    <key>NSAllowsLocalNetworking</key>
+    <true/>
+  </dict>
+  <key>NSHumanReadableCopyright</key>
+  <string>MIT — opencodex contributors</string>
+</dict>
+</plist>

app/Package.swift

@@ -0,0 +1,55 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "OpenCodexMenuBar",
+    platforms: [.macOS(.v13)],
+    products: [
+        .executable(name: "OpenCodexMenuBar", targets: ["MenuBarApp"]),
+        .executable(name: "OpenCodexWidget", targets: ["OpenCodexWidget"]),
+        .executable(name: "MenuBarCoreTests", targets: ["MenuBarCoreTests"]),
+        .executable(name: "MenuBarUITests", targets: ["MenuBarUITests"]),
+        .executable(name: "UIProbe", targets: ["UIProbe"]),
+        .executable(name: "IconProbe", targets: ["IconProbe"]),
+    ],
+    targets: [
+        .target(name: "MenuBarCore", path: "Sources/MenuBarCore"),
+        // AppKit views live in a library so both the app and the visual-QA probe can
+        // build the same surface. An executable target cannot be imported.
+        .target(name: "MenuBarUI", dependencies: ["MenuBarCore"], path: "Sources/MenuBarUI"),
+        .executableTarget(
+            name: "MenuBarApp",
+            dependencies: ["MenuBarCore", "MenuBarUI"],
+            path: "Sources/MenuBarApp"
+        ),
+        .executableTarget(
+            name: "OpenCodexWidget",
+            dependencies: ["MenuBarCore"],
+            path: "Sources/OpenCodexWidget",
+            linkerSettings: [
+                // Widget extensions must enter through NSExtensionMain or chronod tears down
+                // the process before the WidgetBundle connects.
+                .linkedFramework("Foundation"),
+                .unsafeFlags(["-Xlinker", "-e", "-Xlinker", "_NSExtensionMain"]),
+            ]
+        ),
+        // An executable rather than a .testTarget: Xcode Command Line Tools ships
+        // neither a usable XCTest module nor the swift-testing runtime, so a test bundle
+        // cannot run without a full Xcode install. See Sources/MenuBarCoreTests/Harness.swift.
+        .executableTarget(
+            name: "MenuBarCoreTests",
+            dependencies: ["MenuBarCore"],
+            path: "Sources/MenuBarCoreTests"
+        ),
+        // UI-layer tests need AppKit and an NSApplication, so they are a separate
+        // executable from the dependency-free core suite.
+        .executableTarget(
+            name: "MenuBarUITests",
+            dependencies: ["MenuBarCore", "MenuBarUI"],
+            path: "Sources/MenuBarUITests"
+        ),
+        .executableTarget(name: "UIProbe", dependencies: ["MenuBarCore", "MenuBarUI"], path: "Sources/UIProbe"),
+        .executableTarget(name: "IconProbe", dependencies: ["MenuBarCore", "MenuBarUI"], path: "Sources/IconProbe"),
+    ],
+    swiftLanguageVersions: [.v5]
+)

app/Sources/IconProbe/main.swift

@@ -0,0 +1,32 @@
+// Renders every menu bar glyph state to one sheet so the state signal can be verified
+// visually. The notch previously did not render at all, which made protected and
+// at-risk indistinguishable.
+import AppKit
+import MenuBarCore
+import MenuBarUI
+
+let states: [(String, ProxyState)] = [
+    ("protected", .running(StartupHealth(status: "protected"))),
+    ("at-risk", .running(StartupHealth(status: "at-risk"))),
+    ("loading", .loading),
+    ("stopped", .unreachable),
+]
+
+let scale: CGFloat = 6
+let cell = NSSize(width: 17 * scale, height: 17 * scale)
+let sheet = NSImage(size: NSSize(width: cell.width * CGFloat(states.count), height: cell.height))
+sheet.lockFocus()
+NSColor.white.setFill()
+NSRect(origin: .zero, size: sheet.size).fill()
+for (i, entry) in states.enumerated() {
+    let img = StatusIcon.image(for: entry.1)
+    let rect = NSRect(x: CGFloat(i) * cell.width, y: 0, width: cell.width, height: cell.height)
+    NSGraphicsContext.current?.imageInterpolation = .none
+    img.draw(in: rect.insetBy(dx: 8, dy: 8))
+}
+sheet.unlockFocus()
+if let tiff = sheet.tiffRepresentation, let rep = NSBitmapImageRep(data: tiff),
+   let png = rep.representation(using: .png, properties: [:]) {
+    try? png.write(to: URL(fileURLWithPath: "/tmp/glyphs.png"))
+}
+print("wrote /tmp/glyphs.png:", states.map(\.0).joined(separator: ", "))

app/Sources/MenuBarApp/main.swift

@@ -0,0 +1,11 @@
+import AppKit
+import MenuBarUI
+
+let app = NSApplication.shared
+// .accessory keeps it out of the Dock; LSUIElement in Info.plist does the same for the
+// packaged bundle, and this covers `swift run` during development.
+app.setActivationPolicy(.accessory)
+
+let delegate = AppDelegate()
+app.delegate = delegate
+app.run()