tibodog 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tibodog contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+# 🐕 tibodog
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/tibodog)](https://www.npmjs.com/package/tibodog)
+
+> 티보가 리셋하면 짖는 개.
+> A dog that barks when Tibo resets the limits.
+
+![tibodog in the notch: usage on both sides, Now Playing, and the dog barking](docs/mockup-collapsed.jpg)
+
+```
+      / \__            _______________
+     (    O\___       |  WOOF! WOOF!  |
+     /         O  <== | RESET! RESET! |
+    /   (_____/       |_______________|
+   /_____/   U
+```
+
+Tibo ([@thsottiaux](https://x.com/thsottiaux)) posts on X whenever the Codex usage limits get reset.
+Run `npx tibodog` and:
+
+- 🏝️ a **notch widget** comes up on macOS: your Claude Code or Codex usage on both sides of the notch,
+  Now Playing next to it, and the dog
+- 👀 it **watches Tibo's feed**, and when a reset post shows up
+- 🐶 the dog **barks in the notch until you read it**, 🔊 barks out loud (a real recording), and 🔔 pops a
+  notification
+
+명령어 하나로 노치 위젯(사용량 · 음악 · 개)이 뜨고, 티보의 X를 감시하다가 리셋 글이 오면 개가 짖어요.
+
+No npm dependencies. Node 18+. The widget needs macOS 14+ and Xcode Command Line Tools to build on first
+run; on Linux and Windows tibodog still watches and barks in the terminal.
+
+## 빠른 시작 / Quick start
+
+```bash
+npx tibodog --test        # 위젯 띄우고 바로 한번 짖어보기 / bring up the widget and bark once
+```
+
+The first run builds the widget into `~/.tibodog` (under a minute). After that it starts instantly and keeps
+running even when you close the terminal. Then pick a way to read X:
+
+### A) 공식 X API / Official X API
+
+```bash
+export X_BEARER_TOKEN=xxxxxxxx
+npx tibodog
+```
+
+Reading a user timeline needs a paid X API tier. The default poll is every 5 minutes to stay
+under rate limits. On a 429 the dog naps until the limit resets (the irony is noted).
+
+### B) RSS 미러 / Any RSS mirror (free)
+
+Any RSS/Atom feed of the account works: a Nitter instance, self-hosted [RSSHub](https://docs.rsshub.app)
+(`/twitter/user/thsottiaux`), rss.app, and so on.
+
+```bash
+npx tibodog --rss "https://your-rsshub.example.com/twitter/user/thsottiaux"
+```
+
+## 옵션 / Options
+
+| flag | default | |
+|---|---|---|
+| `--user <handle>` | `thsottiaux` | 감시할 계정 / account to watch |
+| `--rss <url>` | | use an RSS feed instead of the X API |
+| `--interval <sec>` | 60 (RSS) / 300 (X) | poll interval |
+| `--keyword <text>` | | extra trigger phrase, repeatable |
+| `--barks <n>` | 1 | 짖는 소리 반복 횟수 / times to play the bark |
+| `--sound <file.wav\|synth>` | real recording | bring your own dog, or `synth` for the synthesized bark |
+| `--lang <ko\|en>` | system locale | 표시 언어 / UI language |
+| `--open` | off | open the post in the browser |
+| `--no-widget` | | 노치 위젯 끄기 / don't start the notch widget |
+| `--install-app` | | 위젯을 앱으로 설치 / install the widget as an app (below) |
+| `--bark-old` | off | also bark at reset posts already in the feed on startup |
+| `--once` | off | check once and exit (for cron) |
+| `--test` | | just bark |
+
+You can also set these through env vars: `TIBODOG_USER`, `TIBODOG_RSS`, `TIBODOG_INTERVAL`, `TIBODOG_SOUND`, `TIBODOG_LANG`.
+
+## 언어 / Language
+
+한국어(`ko`)와 영어(`en`)를 지원해요. 따로 지정하지 않으면 시스템 언어(`LANG`)를 따라가요.
+
+```bash
+npx tibodog --lang ko     # 멍! 멍멍! 리셋이다! 리셋!
+npx tibodog --lang en     # WOOF! WOOF! RESET! RESET!
+```
+
+Order: `--lang` → `TIBODOG_LANG` → `LC_ALL` / `LC_MESSAGES` / `LANG` → system locale → `en`.
+To add a language, add an entry to [`src/i18n.js`](src/i18n.js).
+
+## 노치 위젯 / The notch widget (macOS)
+
+![The widget opened: Tibo's post with a check that the reset reached the account, Codex usage, reset credits, Now Playing](docs/mockup-expanded.jpg)
+
+- **Usage**: the 5-hour and weekly windows of Claude Code (the same numbers as `/usage`) or Codex, with
+  reset timers. Hover the notch for details; switch between Claude and Codex there or in the menu.
+- **Now Playing**: album art and dancing bars while music plays; hover for the track and controls. Works with
+  anything that publishes to macOS Now Playing (Spotify, Apple Music, YouTube Music in Chrome, Safari...).
+- **The dog**: on a reset, it barks beside the notch until you read it. Hover to see Tibo's post and a link;
+  keep it open for a second and the dog goes back to sleep. A quick brush doesn't count. It survives restarts,
+  so a reset you missed while away is still waiting for you.
+- **Did the reset reach you?** The dog's card checks it against your Codex account: ✅ when your weekly
+  window started over after Tibo's post, 🎟️ when it came as a reset credit, ⏳ while it hasn't yet. Codex is
+  read every 10 minutes (even with Claude shown) and the changes are kept in `~/.tibodog/codex-history.json`.
+  A new reset credit makes the dog bark too.
+- **Reset credits** (Codex tab): how many you have, and **Use a reset →** to spend one through Codex's own
+  `account/rateLimitResetCredit/consume`, after a confirm. It warns you when there's barely anything to reset.
+- Right-click the island (or use the menu bar icon) for settings: provider, Now Playing, menu bar text,
+  launch at login.
+
+리셋이 오면 노치 옆에서 개가 계속 짖어요. 마우스를 올리면 티보의 글이 보이고, 1초쯤 읽고 떼면 개가 들어가요.
+살짝 스치기만 하면 계속 짖어요. 사용량과 음악은 늘 보여요.
+
+### 앱으로 설치 (선택) / Install as an app (optional)
+
+`npx tibodog` is all you need. If you want the widget to start with your Mac even when tibodog isn't
+running, install it as an app and turn on **Launch at Login** in its menu:
+
+```bash
+npx tibodog --install-app     # → /Applications/TiboDog.app
+```
+
+The X watching still runs in `tibodog`; the app shows usage and music on its own and barks when tibodog
+reports a reset (they talk through `~/.tibodog/alert.json`).
+
+### Usage sources
+
+- **Claude Code**: reuses the Claude Code login already on your Mac (Keychain item `Claude Code-credentials`,
+  read through `/usr/bin/security`, falling back to `~/.claude/.credentials.json`) and calls
+  `api.anthropic.com/api/oauth/usage`. Refreshes an expired token the same way Claude Code does and writes it
+  back; turn that off in the menu. Usage limits are a subscription feature, so API-key logins show nothing.
+- **Codex**: starts the installed `codex app-server`, reads `account/rateLimits/read`, and closes it. Sign in
+  to Codex with ChatGPT first. Set `TIBODOG_CODEX_PATH` if it lives somewhere unusual.
+- **Now Playing** on macOS 15.4+ goes through the bundled
+  [mediaremote-adapter](https://github.com/ungive/mediaremote-adapter) (BSD-3, in `app/Vendor/`). If Apple
+  breaks it, music quietly disappears and the rest keeps working.
+
+## 어떻게 판단하나 / How it decides
+
+A post counts as a reset post when it has a reset word (`reset`, `resetting`, `refreshed`, `리셋`, `초기화`)
+**and** a limits word (`limits`, `usage`, `rate`, `codex`, `weekly`, `사용량`, `한도`, ...).
+See [`src/detect.js`](src/detect.js). If the dog barks at the wrong thing, send a PR with a test case.
+
+On the first run it only records the posts already in the feed, so it won't bark at old ones.
+Seen IDs are stored in `~/.tibodog/<user>.json`.
+
+## 개발 / Development
+
+```bash
+npm test                    # the watcher
+cd app && swift test        # the widget
+cd app && make run          # build app/build/TiboDog.app and open it
+```
+
+Widget flags for development: `TIBODOG_DEBUG=1` (logs to stderr), `TIBODOG_MOCK=1` (sample data, no Keychain
+or network), `TIBODOG_EXPANDED=1` (start expanded), `TIBODOG_SNAPSHOT=/path.png` (render and quit;
+`make shots` in `app/`).
+
+## Privacy
+
+tibodog sends no conversations or files anywhere. It talks to X (or the RSS feed you give it), Anthropic for
+Claude usage and token refresh, and OpenAI through the installed Codex app server. No analytics.
+
+## 소리 출처 / Sound credits
+
+The bundled bark is ["Barking of a dog"](https://commons.wikimedia.org/wiki/File:Barking_of_a_dog.ogg)
+by Amada44 on Wikimedia Commons, licensed [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/).
+The audio file keeps that license. The code is MIT ([`LICENSE`](LICENSE); the widget in `app/` keeps Islet's notice in [`app/LICENSE`](app/LICENSE)). Details in [`sounds/CREDITS.md`](sounds/CREDITS.md).
+The widget grew out of [Islet](https://github.com/aiasapkr-beep/islet), the same author's notch usage app.
+
+The mockups in `docs/` use macOS Sonoma's default wallpaper, © Apple Inc.
+
+## Disclaimer
+
+A fan-made joke project. Not affiliated with OpenAI or X. Be nice to Tibo. 🐶
+
+MIT

package/app/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kim Minsu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/app/Package.swift

@@ -0,0 +1,18 @@
+// swift-tools-version:5.10
+import PackageDescription
+
+let package = Package(
+    name: "TiboDog",
+    platforms: [.macOS(.v14)],
+    targets: [
+        .executableTarget(
+            name: "TiboDog",
+            path: "Sources/TiboDog",
+            linkerSettings: [
+                .linkedFramework("Security"),
+                .linkedFramework("ServiceManagement"),
+            ]
+        ),
+        .testTarget(name: "TiboDogTests", dependencies: ["TiboDog"])
+    ]
+)

package/app/Resources/Info.plist

@@ -0,0 +1,20 @@
+<?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>TiboDog</string>
+    <key>CFBundleIdentifier</key><string>kr.asapai.TiboDog</string>
+    <key>CFBundleInfoDictionaryVersion</key><string>6.0</string>
+    <key>CFBundleName</key><string>TiboDog</string>
+    <key>CFBundleDisplayName</key><string>TiboDog</string>
+    <key>CFBundlePackageType</key><string>APPL</string>
+    <key>CFBundleShortVersionString</key><string>0.1.0</string>
+    <key>CFBundleVersion</key><string>1</string>
+    <key>CFBundleIconFile</key><string>AppIcon</string>
+    <key>LSMinimumSystemVersion</key><string>14.0</string>
+    <key>LSUIElement</key><true/>
+    <key>NSHighResolutionCapable</key><true/>
+    <key>NSHumanReadableCopyright</key><string>MIT License</string>
+</dict>
+</plist>

package/app/Scripts/build-app.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Builds TiboDog.app (release, signed with a local identity or ad-hoc).
+# Output goes to ./build, or $TIBODOG_APP_OUT; intermediate files to ./.build, or $TIBODOG_SCRATCH
+# (`npx tibodog` points both into ~/.tibodog so nothing is written inside the npm cache).
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+CONFIG="${1:-release}"
+OUT="${TIBODOG_APP_OUT:-build}"
+SCRATCH="${TIBODOG_SCRATCH:-.build}"
+APP="$OUT/TiboDog.app"
+
+swift build -c "$CONFIG" --scratch-path "$SCRATCH" 2>&1 | tail -n 3
+BIN="$SCRATCH/$CONFIG/TiboDog"
+
+# Now Playing helper (see Vendor/mediaremote-adapter/README.md). Built once, reused.
+ADAPTER=Vendor/mediaremote-adapter
+ADAPTER_BUILD="${TIBODOG_SCRATCH:+$SCRATCH/mediaremote-adapter}"
+ADAPTER_BUILD="${ADAPTER_BUILD:-$ADAPTER/build}"
+if [ ! -d "$ADAPTER_BUILD/MediaRemoteAdapter.framework" ]; then
+  "$ADAPTER/build-framework.sh" "$ADAPTER_BUILD" 2>&1 | grep -vE "warning:|note:|^\s" || true
+fi
+
+rm -rf "$APP"
+mkdir -p "$APP/Contents/MacOS" "$APP/Contents/Resources"
+cp "$BIN" "$APP/Contents/MacOS/TiboDog"
+cp Resources/Info.plist "$APP/Contents/"
+[ -f Resources/AppIcon.icns ] && cp Resources/AppIcon.icns "$APP/Contents/Resources/"
+cp ../sounds/bark.wav "$APP/Contents/Resources/" # the bark (CC BY-SA 3.0, see ../sounds/CREDITS.md)
+cp "$ADAPTER/bin/mediaremote-adapter.pl" "$APP/Contents/Resources/"
+cp -R "$ADAPTER_BUILD/MediaRemoteAdapter.framework" "$APP/Contents/Resources/"
+echo -n "APPL????" > "$APP/Contents/PkgInfo"
+
+# Signing: use $TIBODOG_SIGN_IDENTITY, else a local "TiboDog Dev" (or older "Islet Dev") certificate if one
+# exists, else ad-hoc. A stable identity keeps the Keychain "Always Allow" grant across rebuilds
+# (ad-hoc signatures change every build, so macOS asks again each time).
+IDENTITY="${TIBODOG_SIGN_IDENTITY:-}"
+for NAME in "TiboDog Dev" "Islet Dev"; do
+  if [ -z "$IDENTITY" ] && security find-identity -p codesigning 2>/dev/null | grep -q "\"$NAME\""; then
+    IDENTITY="$NAME"
+  fi
+done
+codesign --force --deep --sign "${IDENTITY:--}" "$APP"
+echo "Built $APP (signed: ${IDENTITY:-ad-hoc})"

package/app/Scripts/make-icon.swift

@@ -0,0 +1,51 @@
+// Renders Resources/AppIcon.icns: a dark rounded tile with a notch and two usage rings.
+// Run: swift Scripts/make-icon.swift
+import AppKit
+
+func render(size: CGFloat) -> NSImage {
+    let img = NSImage(size: NSSize(width: size, height: size))
+    img.lockFocus()
+    let s = size
+    // Tile
+    let tile = NSBezierPath(roundedRect: NSRect(x: 0, y: 0, width: s, height: s), xRadius: s * 0.22, yRadius: s * 0.22)
+    NSColor(calibratedRed: 0.09, green: 0.09, blue: 0.11, alpha: 1).setFill(); tile.fill()
+    // Screen glow area
+    let screen = NSBezierPath(roundedRect: NSRect(x: s * 0.10, y: s * 0.14, width: s * 0.80, height: s * 0.66), xRadius: s * 0.07, yRadius: s * 0.07)
+    NSColor(calibratedRed: 0.16, green: 0.18, blue: 0.24, alpha: 1).setFill(); screen.fill()
+    // Notch
+    let notch = NSBezierPath(roundedRect: NSRect(x: s * 0.36, y: s * 0.71, width: s * 0.28, height: s * 0.12), xRadius: s * 0.04, yRadius: s * 0.04)
+    NSColor.black.setFill(); notch.fill()
+    // Rings
+    func ring(cx: CGFloat, cy: CGFloat, r: CGFloat, fraction: CGFloat, color: NSColor) {
+        let track = NSBezierPath(); track.appendArc(withCenter: NSPoint(x: cx, y: cy), radius: r, startAngle: 0, endAngle: 360)
+        track.lineWidth = s * 0.055; NSColor.white.withAlphaComponent(0.15).setStroke(); track.stroke()
+        let arc = NSBezierPath(); arc.appendArc(withCenter: NSPoint(x: cx, y: cy), radius: r, startAngle: 90, endAngle: 90 - 360 * fraction, clockwise: true)
+        arc.lineWidth = s * 0.055; arc.lineCapStyle = .round; color.setStroke(); arc.stroke()
+    }
+    ring(cx: s * 0.34, cy: s * 0.44, r: s * 0.13, fraction: 0.42, color: NSColor(calibratedRed: 0.20, green: 0.78, blue: 0.35, alpha: 1))
+    ring(cx: s * 0.66, cy: s * 0.44, r: s * 0.13, fraction: 0.71, color: NSColor(calibratedRed: 1.0, green: 0.62, blue: 0.04, alpha: 1))
+    img.unlockFocus()
+    return img
+}
+
+let fm = FileManager.default
+let outDir = "Resources/AppIcon.iconset"
+try? fm.removeItem(atPath: outDir)
+try! fm.createDirectory(atPath: outDir, withIntermediateDirectories: true)
+for base in [16, 32, 128, 256, 512] {
+    for scale in [1, 2] {
+        let px = CGFloat(base * scale)
+        let img = render(size: px)
+        let rep = NSBitmapImageRep(bitmapDataPlanes: nil, pixelsWide: Int(px), pixelsHigh: Int(px), bitsPerSample: 8, samplesPerPixel: 4, hasAlpha: true, isPlanar: false, colorSpaceName: .deviceRGB, bytesPerRow: 0, bitsPerPixel: 0)!
+        NSGraphicsContext.saveGraphicsState()
+        NSGraphicsContext.current = NSGraphicsContext(bitmapImageRep: rep)
+        img.draw(in: NSRect(x: 0, y: 0, width: px, height: px))
+        NSGraphicsContext.restoreGraphicsState()
+        let name = scale == 1 ? "icon_\(base)x\(base).png" : "icon_\(base)x\(base)@2x.png"
+        try! rep.representation(using: .png, properties: [:])!.write(to: URL(fileURLWithPath: "\(outDir)/\(name)"))
+    }
+}
+let p = Process(); p.launchPath = "/usr/bin/iconutil"; p.arguments = ["-c", "icns", outDir, "-o", "Resources/AppIcon.icns"]
+p.launch(); p.waitUntilExit()
+try? fm.removeItem(atPath: outDir)
+print(p.terminationStatus == 0 ? "Wrote Resources/AppIcon.icns" : "iconutil failed")

package/app/Sources/TiboDog/App.swift

@@ -0,0 +1,163 @@
+import SwiftUI
+import AppKit
+
+@main
+struct TiboDogApp: App {
+    @NSApplicationDelegateAdaptor(AppDelegate.self) private var delegate
+    @ObservedObject private var store = UsageStore.shared
+
+    /// MenuBarExtra writes its isInserted binding back on every configuration pass. Bound
+    /// straight to a @Published property that republishes even for unchanged values, this
+    /// forms an infinite SwiftUI update loop that pins the main thread. Guard on equality.
+    private var menuBarIconInserted: Binding<Bool> {
+        Binding(get: { store.showMenuBarIcon },
+                set: { new in if new != store.showMenuBarIcon { store.showMenuBarIcon = new } })
+    }
+
+    var body: some Scene {
+        MenuBarExtra(isInserted: menuBarIconInserted) {
+            TiboDogMenu()
+        } label: {
+            HStack(spacing: 4) {
+                Image(systemName: "gauge.with.dots.needle.33percent")
+                if store.showMenuBarText { Text(store.menuBarTitle).monospacedDigit() }
+            }
+        }
+    }
+}
+
+/// Shared between the menu bar item and the island's right-click menu.
+struct TiboDogMenu: View {
+    @ObservedObject private var store = UsageStore.shared
+
+    var body: some View {
+        Picker("Usage Provider", selection: $store.provider) {
+            ForEach(UsageProvider.allCases) { Text($0.title).tag($0) }
+        }
+        Divider()
+        if let u = store.usage {
+            Text("\(store.primaryTitle): \(u.fiveHour?.percentText ?? "–")" + resetSuffix(u.fiveHour))
+            Text("\(store.secondaryTitle): \(u.sevenDay?.percentText ?? "–")" + resetSuffix(u.sevenDay))
+            if let o = u.sevenDayOpus { Text("Weekly Opus: \(o.percentText)" + resetSuffix(o)) }
+        } else {
+            Text(store.errorMessage ?? "Loading…")
+        }
+        if store.usage != nil, let error = store.errorMessage { Text(error) }
+        Text(store.planText + (store.lastUpdated.map { " · updated \(clockText($0))" } ?? ""))
+        Divider()
+        Button("Refresh Now") { store.refresh(force: true) }
+            .keyboardShortcut("r")
+        Divider()
+        Toggle("Show in Notch", isOn: $store.showNotch)
+        Toggle("Now Playing Island", isOn: $store.showNowPlaying)
+        Toggle("Menu Bar Icon", isOn: $store.showMenuBarIcon)
+        Toggle("Show % in Menu Bar", isOn: $store.showMenuBarText)
+        if store.provider == .claude { Toggle("Auto-refresh Claude Token", isOn: $store.autoRefreshToken) }
+        Toggle("Launch at Login", isOn: $store.launchAtLogin)
+        Divider()
+        Button("Quit TiboDog") { NSApp.terminate(nil) }
+            .keyboardShortcut("q")
+    }
+
+    private func resetSuffix(_ w: UsageWindow?) -> String {
+        guard let r = w?.resetsAt else { return "" }
+        return "  (resets in \(relativeText(until: r)))"
+    }
+}
+
+@MainActor
+final class AppDelegate: NSObject, NSApplicationDelegate {
+    private var panel: NotchPanel?
+    private var geometry: NotchGeometry?
+    private var observers: [Any] = []
+
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        NSApp.setActivationPolicy(.accessory)
+        let store = UsageStore.shared
+        store.start()
+        rebuildPanel()
+        snapshotIfRequested()
+
+        observers.append(NotificationCenter.default.addObserver(
+            forName: NSApplication.didChangeScreenParametersNotification, object: nil, queue: .main
+        ) { [weak self] _ in self?.rebuildPanel() })
+
+        // Show/hide when the setting flips.
+        let cancellable = store.$showNotch.receive(on: RunLoop.main).sink { [weak self] _ in self?.rebuildPanel() }
+        observers.append(cancellable)
+
+        if !UsageStore.mock {
+            let music = store.$showNowPlaying.removeDuplicates().receive(on: RunLoop.main).sink { on in
+                if on { NowPlayingMonitor.shared.start() } else { NowPlayingMonitor.shared.stop() }
+            }
+            observers.append(music)
+        }
+    }
+
+    /// TIBODOG_SNAPSHOT=/path/out.png renders the island to a trimmed PNG and quits (for README shots).
+    private func snapshotIfRequested() {
+        guard let path = ProcessInfo.processInfo.environment["TIBODOG_SNAPSHOT"] else { return }
+        let delay = Double(ProcessInfo.processInfo.environment["TIBODOG_SNAPSHOT_DELAY"] ?? "1.5") ?? 1.5
+        DispatchQueue.main.asyncAfter(deadline: .now() + delay) { [weak self] in
+            defer { NSApp.terminate(nil) }
+            guard let win = self?.panel, win.isVisible else { Log.error("snapshot: no visible panel"); return }
+            let wid = CGWindowID(win.windowNumber)
+            guard let cg = CGWindowListCreateImage(.null, .optionIncludingWindow, wid,
+                                                   [.boundsIgnoreFraming, .bestResolution]) else {
+                Log.error("snapshot: CGWindowListCreateImage failed"); return
+            }
+            let rep = NSBitmapImageRep(cgImage: cg)
+            guard let trimmed = Self.trimTransparent(rep, padding: 24) ?? rep as NSBitmapImageRep?,
+                  let png = trimmed.representation(using: .png, properties: [:]) else { return }
+            try? png.write(to: URL(fileURLWithPath: path))
+            Log.info("snapshot written to \(path) (\(rep.pixelsWide)x\(rep.pixelsHigh))")
+        }
+    }
+
+    private static func trimTransparent(_ rep: NSBitmapImageRep, padding: Int) -> NSBitmapImageRep? {
+        let w = rep.pixelsWide, h = rep.pixelsHigh
+        var minX = w, minY = h, maxX = -1, maxY = -1
+        for y in 0..<h {
+            for x in 0..<w where (rep.colorAt(x: x, y: y)?.alphaComponent ?? 0) > 0.02 {
+                minX = min(minX, x); maxX = max(maxX, x); minY = min(minY, y); maxY = max(maxY, y)
+            }
+        }
+        guard maxX >= minX else { return nil }
+        let x0 = max(0, minX - padding), y0 = max(0, minY - padding)
+        let x1 = min(w - 1, maxX + padding), y1 = min(h - 1, maxY + padding)
+        let cw = x1 - x0 + 1, ch = y1 - y0 + 1
+        guard let out = NSBitmapImageRep(bitmapDataPlanes: nil, pixelsWide: cw, pixelsHigh: ch, bitsPerSample: 8,
+                                         samplesPerPixel: 4, hasAlpha: true, isPlanar: false,
+                                         colorSpaceName: .deviceRGB, bytesPerRow: 0, bitsPerPixel: 0) else { return nil }
+        NSGraphicsContext.saveGraphicsState()
+        NSGraphicsContext.current = NSGraphicsContext(bitmapImageRep: out)
+        // Bitmap rows are top-down; NSRect drawing is bottom-up, so flip the source rect.
+        let src = NSRect(x: x0, y: h - y1 - 1, width: cw, height: ch)
+        NSImage(cgImage: rep.cgImage!, size: NSSize(width: w, height: h))
+            .draw(in: NSRect(x: 0, y: 0, width: cw, height: ch), from: src, operation: .copy, fraction: 1)
+        NSGraphicsContext.restoreGraphicsState()
+        return out
+    }
+
+    func applicationWillTerminate(_ notification: Notification) {
+        NowPlayingMonitor.shared.stop()
+    }
+
+    private func rebuildPanel() {
+        let store = UsageStore.shared
+        let geo = NotchGeometry.detect()
+        guard store.showNotch else {
+            panel?.orderOut(nil); panel = nil; geometry = nil
+            return
+        }
+        if let p = panel, geometry == geo {
+            p.orderFrontRegardless()
+            return
+        }
+        panel?.orderOut(nil)
+        let p = NotchPanel(geometry: geo, store: store)
+        p.orderFrontRegardless()
+        panel = p
+        geometry = geo
+    }
+}

package/app/Sources/TiboDog/CodexUsageAPI.swift

@@ -0,0 +1,125 @@
+import Foundation
+import Darwin
+
+/// Uses Codex's supported local protocol; authentication stays owned by Codex.
+enum CodexUsageAPI {
+    enum Failure: LocalizedError {
+        case notInstalled, timeout, unavailable, protocolError
+        var errorDescription: String? {
+            switch self {
+            case .notInstalled: return "Codex not found. Install Codex, or set TIBODOG_CODEX_PATH to its executable."
+            case .timeout: return "Codex usage request timed out. Try Refresh Now."
+            case .unavailable: return "Codex usage unavailable. Sign in to Codex with ChatGPT and try again."
+            case .protocolError: return "Unexpected Codex response. Update Codex and try again."
+            }
+        }
+    }
+
+    static func executable() throws -> URL {
+        let env = ProcessInfo.processInfo.environment
+        let home = FileManager.default.homeDirectoryForCurrentUser.path
+        let candidates = [env["TIBODOG_CODEX_PATH"]].compactMap { $0 } + [
+            "/Applications/Codex.app/Contents/Resources/codex",
+            "/Applications/ChatGPT.app/Contents/Resources/codex",
+            "\(home)/Applications/Codex.app/Contents/Resources/codex",
+            "\(home)/Applications/ChatGPT.app/Contents/Resources/codex",
+            "/opt/homebrew/bin/codex", "/usr/local/bin/codex", "\(home)/.local/bin/codex"
+        ] + (env["PATH"] ?? "").split(separator: ":").map { "\($0)/codex" }
+        guard let path = candidates.first(where: { FileManager.default.isExecutableFile(atPath: $0) }) else {
+            throw Failure.notInstalled
+        }
+        return URL(fileURLWithPath: path)
+    }
+
+    // Called off the main actor. poll() bounds every read, including partial JSON lines.
+    static func fetch() throws -> (usage: Usage, plan: String?, resetCredits: Int?) {
+        try decode(call("account/rateLimits/read"))
+    }
+
+    /// Spends one of the account's reset credits on the current windows. Returns Codex's outcome:
+    /// "reset", "nothingToReset", "noCredit" or "alreadyRedeemed". Retrying with the same key never
+    /// spends a second credit.
+    static func consumeResetCredit(idempotencyKey: String) throws -> String {
+        let result = try call("account/rateLimitResetCredit/consume", params: ["idempotencyKey": idempotencyKey])
+        guard let outcome = result["outcome"] as? String else { throw Failure.protocolError }
+        return outcome
+    }
+
+    /// One request to a short-lived `codex app-server`: initialize, send it, return its result.
+    static func call(_ method: String, params: [String: Any]? = nil) throws -> [String: Any] {
+        let process = Process()
+        process.executableURL = try executable()
+        process.arguments = ["app-server"]
+        process.currentDirectoryURL = FileManager.default.homeDirectoryForCurrentUser
+        let input = Pipe(), output = Pipe()
+        process.standardInput = input
+        process.standardOutput = output
+        process.standardError = FileHandle.nullDevice
+        try process.run()
+        let pid = process.processIdentifier
+        defer {
+            try? input.fileHandleForWriting.close()
+            if process.isRunning { process.terminate() }
+            // Do not let a hung child accumulate across refreshes.
+            let deadline = Date().addingTimeInterval(1)
+            while process.isRunning && Date() < deadline { Thread.sleep(forTimeInterval: 0.01) }
+            if process.isRunning { kill(pid, SIGKILL) }
+            process.waitUntilExit()
+            try? output.fileHandleForReading.close()
+        }
+        func send(_ message: [String: Any]) throws {
+            var data = try JSONSerialization.data(withJSONObject: message)
+            data.append(10)
+            try input.fileHandleForWriting.write(contentsOf: data)
+        }
+        try send(["id": 1, "method": "initialize", "params": ["clientInfo": ["name": "tibodog", "version": "0.4.0"]]])
+        let deadline = Date().addingTimeInterval(25)
+        var buffer = Data()
+        while Date() < deadline {
+            var descriptor = pollfd(fd: output.fileHandleForReading.fileDescriptor, events: Int16(POLLIN), revents: 0)
+            let ready = poll(&descriptor, 1, 200)
+            if ready < 0 { if errno == EINTR { continue }; throw Failure.protocolError }
+            if ready == 0 { continue }
+            let chunk = output.fileHandleForReading.availableData
+            guard !chunk.isEmpty else { throw Failure.unavailable }
+            buffer.append(chunk)
+            guard buffer.count < 4 * 1024 * 1024 else { throw Failure.protocolError }
+            while let newline = buffer.firstIndex(of: 10) {
+                let line = buffer.prefix(upTo: newline)
+                buffer.removeSubrange(...newline)
+                guard let message = try JSONSerialization.jsonObject(with: line) as? [String: Any] else { continue }
+                guard let id = message["id"] as? Int else { continue }
+                guard message["error"] == nil else { throw Failure.unavailable }
+                if id == 1 {
+                    try send(["method": "initialized"])
+                    var request: [String: Any] = ["id": 2, "method": method]
+                    if let params { request["params"] = params }
+                    try send(request)
+                } else if id == 2 {
+                    guard let result = message["result"] as? [String: Any] else { throw Failure.protocolError }
+                    return result
+                }
+            }
+        }
+        throw Failure.timeout
+    }
+
+    static func decode(_ result: [String: Any]) throws -> (usage: Usage, plan: String?, resetCredits: Int?) {
+        let buckets = result["rateLimitsByLimitId"] as? [String: Any]
+        // Never substitute an unrelated model bucket for the Codex quota.
+        guard let limits = (buckets?["codex"] as? [String: Any]) ?? (result["rateLimits"] as? [String: Any]) else {
+            throw Failure.unavailable
+        }
+        func window(_ key: String) -> UsageWindow? {
+            guard let raw = limits[key] as? [String: Any],
+                  let used = (raw["usedPercent"] as? NSNumber)?.doubleValue, used.isFinite else { return nil }
+            let reset = (raw["resetsAt"] as? NSNumber).map { Date(timeIntervalSince1970: $0.doubleValue) }
+            return UsageWindow(utilization: used, resetsAt: reset,
+                               durationMinutes: (raw["windowDurationMins"] as? NSNumber)?.intValue)
+        }
+        let primary = window("primary"), secondary = window("secondary")
+        guard primary != nil || secondary != nil else { throw Failure.unavailable }
+        let credits = ((result["rateLimitResetCredits"] as? [String: Any])?["availableCount"] as? NSNumber)?.intValue
+        return (Usage(fiveHour: primary, sevenDay: secondary), limits["planType"] as? String, credits)
+    }
+}