Merge pull request #6 from dazer1234/codex/ios-app

Release Codex Deck 0.7.0

Author: dazer1234

.gitignore

@@ -15,3 +15,6 @@ codex-deck-launcher-*.zip
 !.env.example
 *.tmp
 .DS_Store
+ios/**/xcuserdata/
+ios/DerivedData/
+ios/Configuration/Local.xcconfig

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.7.0 - 2026-07-21
+
+- Added a source-distributed native SwiftUI iPhone companion that merges authenticated Mac and Windows snapshots while leaving the Stream Deck plugin independent.
+- Added pinned-TLS Nearby Wi-Fi pairing and private Tailscale HTTPS profiles without exposing Chrome DevTools or accepting wildcard/public relay listeners.
+- Added native task details, command receipts, Attention Center, optional notifications, one-task Live Activity follow mode, five WidgetKit experiences, and app-local key layouts.
+- Added circular 5-hour/weekly usage, a two-window overview, optional context rings, and a centered reset-credit action with a deliberate 1.2-second hold.
+- Added portable local iOS signing configuration; personal team, bundle, App Group, relay tokens, and official OpenAI keycap artwork remain outside public artifacts.
+- Fixed empty iPhone agent keys drawing two misaligned plus symbols.
+- Fixed the iPhone dashboard in landscape with a bounded two-column layout instead of stretching the square Micro device across the full screen width.
+- Fixed completed, selected, and mirrored tasks retaining stale working/unread colors across Mac and Windows while preserving fresh approval and active-work signals.
+- Fixed long-running iPhone relays retaining stale Codex version metadata after an app update; host identity remains stable and no Codex restart is required.
+- Updated renderer discovery and active-task detection for Codex macOS `26.715.70719` and Windows `26.715.8383.0` without hardcoding renderer hashes.
+- Added physical-iPhone Swift tests, macOS launcher/watcher self-tests, release privacy audits, and expanded relay, renderer, usage, and project regression coverage.
+- Added beginner installation, same-Wi-Fi verification, and release documentation plus explicit inspiration credit for the mobile companion concept.
+
 ## 0.6.3 - 2026-07-19
 
 - Fix completed tasks remaining stuck in the green finished state after they are opened.

README.md

@@ -16,6 +16,7 @@ The same Stream Deck plugin package works in all three modes. Install only the l
 | Windows only | Windows | Local Windows Codex | [Windows setup](docs/WINDOWS.md) |
 | Mac only | macOS | Local Mac Codex | [macOS setup](docs/MACOS.md) |
 | Windows + Mac | Windows | Both apps; six agents are merged | [Multi-host setup](docs/MULTI_HOST.md) |
+| iPhone companion | iOS 17+ | Private Mac and/or Windows nodes | [iPhone app](docs/IOS.md) · [Install from source](docs/IOS_INSTALL.md) |
 
 Windows-only and Mac-only mode have no relay, no second computer dependency, and no host badges. Multi-host mode is optional and can be disabled without changing the local bridge on either machine.
 
@@ -27,11 +28,14 @@ Windows-only and Mac-only mode have no relay, no second computer dependency, and
 - Native key-down/key-up handling for Micro slots `ACT06` through `ACT12`.
 - Native joystick up, right, down, left, and encoder click.
 - Dedicated reasoning-effort up/down buttons with press-and-hold repeat.
+- Live usage controls: a configurable circular 5-hour/weekly limit key and a two-window overview.
+- A centered reset-credit counter with a deliberate 1.2-second hold before an applicable credit can be consumed.
 - A local `codex://threads/new` action for a new task.
 - Standalone actions for all official single-size keycaps, resolved from the installed Codex build at runtime.
 - Optional local loading of official keycap SVGs; those protected files are never included in this repository or its releases.
 - Optional authenticated SSH/Tailscale relay for one Stream Deck controlling Windows and Mac Codex together.
 - Per-host health on the Windows/Mac target key, with last-known agent tiles visibly marked when native desktop signals are uncertain or the relay is offline.
+- Native SwiftUI iPhone companion with dual-host agents, usage, reset credits, and authenticated Micro controls over pinned-TLS Nearby Wi-Fi or private Tailscale HTTPS.
 
 ## Requirements
 
@@ -53,6 +57,15 @@ Other Stream Deck models may work, but the included layout and physical-device t
 4. In **Codex Settings > Codex Micro**, choose the agent source, action assignments, joystick actions, and encoder behavior.
 5. Build the two Stream Deck pages below.
 
+The iPhone companion is currently source-only: **a Mac with Xcode is required
+to build, sign, and install it**, even when the phone will control only a
+Windows Codex node. There is no App Store, TestFlight, or pre-signed IPA build
+yet. After installation, the Mac does not need to stay online unless it is one
+of the computers being controlled. Nearby pairing works on the same private
+Wi-Fi without Tailscale; add Tailscale for private control away from home. See
+the [beginner installation guide](docs/IOS_INSTALL.md) and the
+[local Wi-Fi test](docs/IOS_LOCAL_WIFI.md).
+
 In Windows + Mac mode, choose the same agent-source mode in both Codex apps when you want both native Pinned lists or both sets of Individual assignments to contribute. Pinned tasks are interleaved fairly. For Individual assignments, the Stream Deck computer wins when both apps assign different tasks to one button, while the other computer fills empty slots. Mirrored copies of the same task are shown only once. See [Multi-host behavior](docs/MULTI_HOST.md#agent-source-modes).
 
 ## Recommended 15-key layout
@@ -81,6 +94,16 @@ The action names describe the default Codex Micro setup. The keys always follow
 
 The page-navigation and profile-switch keys are built-in Stream Deck actions. All other named controls come from Codex Deck. Every official Codex Micro keycap is also exposed as a standalone action, so extra pages can be customized without changing the six synchronized Micro action slots.
 
+### Usage and reset controls
+
+![Usage limit, overview, and reset-credit controls](docs/assets/usage-controls-preview.svg)
+
+Add **Usage Limit** for the existing circular capacity display. Its Stream Deck property inspector can pin the key to **5 hours** or **Weekly**, while **Automatic** prefers 5 hours and falls back to weekly whenever Codex temporarily omits the shorter window. **Usage Overview** shows both windows as separate horizontal bars; a missing window stays visible as unavailable instead of being mistaken for zero capacity.
+
+**Rate Limit Reset** shows the number of credits Codex currently reports. The count remains centered inside the reset arrow and the action is dimmed only when no credit is available. Consuming a credit requires holding the key for 1.2 seconds; a short tap does nothing, and Codex's current applicability check still has to pass. This action uses Codex's current native usage client and is therefore subject to the same undocumented compatibility boundary as the Micro bridge.
+
+Usage and reset credits are account-scoped. In Windows + Mac mode these three keys therefore do not follow the Windows/Mac function-key target: they prefer the healthy local account snapshot and fall back to the paired host only when local usage data is unavailable.
+
 ## Official keycap SVGs are not included
 
 The public source and release intentionally exclude OpenAI's Codex Micro keycap SVG files. The original agent tiles, status marks, glow system, animations, fallback labels, and plugin artwork are included.
@@ -117,7 +140,7 @@ No virtual HID driver is installed and no Codex application file is patched. See
 - The Codex debug endpoint remains loopback-only and is never the multi-host relay endpoint.
 - CDP is privileged: another untrusted process running as the same local user could try to access it.
 - Codex Deck has no telemetry, cloud service, or update service.
-- Single-host mode reads no rollout data. Multi-host mode reads only exact local rollout **filenames**, never their contents, to distinguish a task's owning desktop from a cloud/SSH mirror.
+- Codex Deck reads exact local rollout filenames for ownership and a bounded recent tail for structural status tags plus numeric `token_count` fields. It does not parse or relay prompts, responses, project names, or other conversation content.
 - Optional SVGs stay in the user-local icons directory and are never uploaded.
 - Multi-host mode accepts only authenticated, typed Codex Deck commands over SSH or Tailscale; wildcard and arbitrary public-IP listeners are rejected.
 - Private relay tokens, local host state, logs, and personal paths are excluded by the release audit.
@@ -128,11 +151,12 @@ Do not use the launcher while running untrusted local software. See [SECURITY.md
 
 The current build was locally validated against:
 
-- Codex for Windows `26.715.4045.0`
-- Codex for macOS `26.715.31925`
+- Codex for Windows `26.715.8383.0`
+- Codex for macOS `26.715.70719` (`5650`)
 - Stream Deck `7.4.2.22730`
 - Windows `10.0.26220.0`
 - Node.js `24.13.0`
+- iPhone `iOS 27.0` (physical-device build and tests)
 - Standard 15-key Stream Deck MK.2
 
 The Windows physical-device path and the Windows+Mac relay were exercised on the real setup. The macOS launcher, watcher, native bridge, and plugin package are validated; a Stream Deck physically attached to the Mac has not yet been hardware-tested. These are tested versions, not strict maximums.
@@ -156,6 +180,14 @@ npm run audit:release
 
 Nothing is published automatically. See [CONTRIBUTING.md](CONTRIBUTING.md).
 
+## Acknowledgements
+
+The idea to explore a phone-native Codex Micro companion was inspired in part
+by the public mobile concept shared by [Shikhar (@xikhar)](https://x.com/xikhar).
+Codex Deck Mobile is an independent implementation built on this project's own
+authenticated bridge, native controls, and visual system; no source code or
+artwork from that concept is included.
+
 ## License and trademarks
 
 Code and original artwork are licensed under [MIT](LICENSE). OpenAI, Codex, ChatGPT, Elgato, Stream Deck, and their marks/assets belong to their respective owners; third-party and user-supplied assets are not relicensed.

docs/ARCHITECTURE.md

@@ -53,10 +53,15 @@ The same plugin runs on Windows and macOS. It discovers the local loopback port
 3. read the native six-slot state, layout, agent source, and lighting preference;
 4. dispatch Micro HID and joystick events;
 5. emulate native encoder-rotation HID events for reasoning-effort changes;
-6. resolve standalone keycap actions from Codex's live Micro keycap registry and current official command runner.
+6. resolve standalone keycap actions from Codex's live Micro keycap registry and current official command runner;
+7. read Codex's renderer-owned `rate-limit-status` query and normalize its current 5-hour, weekly, and reset-credit state.
 
 The bridge does not emulate a USB HID device and installs no driver.
 
+Usage data remains part of the same typed host snapshot, but usage and reset credits are account-scoped and therefore do not follow the Mac/Windows function-key target. The controller prefers a healthy local account snapshot and falls back to the paired host only when local usage is unavailable. Window identity is derived from the duration returned by Codex rather than from primary/secondary ordering. A missing 5-hour window is represented as unavailable, and Automatic mode falls back to weekly. The bridge refreshes a stale renderer-owned usage query at most once every 15 seconds, so background-window values do not depend on Codex receiving focus.
+
+Reset consumption is the only mutating usage operation. It is a narrow typed relay command and calls Codex's current native reset-credit client only after the Stream Deck key has been held for 1.2 seconds. The bridge verifies both availability and applicability, selects an available plan-supported credit, uses a unique redemption request ID, and then refreshes the renderer query. No credential, raw endpoint access, or arbitrary request surface is exposed to the relay.
+
 ### Optional multi-host relay
 
 The Mac watcher can host an authenticated WebSocket relay on loopback behind an
@@ -68,15 +73,39 @@ target the host selected by the Windows/Mac toggle.
 Host ownership is resolved from exact local rollout filenames, not from a
 renderer's mirrored recent list. This distinguishes a task's owning desktop
 from a stale cloud or remote-SSH mirror. A bounded rollout tail is searched only
-for structural activity/completion event tags; prompts, responses, project
-names, and other content are neither parsed nor relayed. The relay never reads
-or proxies the remote CLI app-server stream.
+for structural activity/completion event tags and the latest numeric
+`token_count` record. The latter provides optional context-window percentage
+metadata for the small agent-key ring. Prompts, responses, project names, and
+other content are neither parsed nor relayed. The relay never reads or proxies
+the remote CLI app-server stream.
 
 The relay protocol has no arbitrary-evaluation, filesystem, shell, or raw-CDP
 operation. Payloads are capped at 64 KiB, authentication is required before a
 snapshot or command is accepted, and command results use request IDs with
 bounded timeouts.
 
+### Optional iPhone transports
+
+The iPhone consumes the same authenticated protocol through two independent
+transport profiles. Remote mode keeps the relay on loopback and uses private
+Tailscale Serve TLS. Nearby mode binds only the typed relay to one discovered
+RFC 1918 address; Chrome DevTools remains on `127.0.0.1`. Nearby creates a
+per-host P-256 certificate and random token, pins the certificate fingerprint
+in the iPhone profile, and stores the token in Keychain.
+
+Bonjour `_codexdeck._tcp` announces protocol version, stable `hostId`, display
+name, platform, private address, relay port, and certificate fingerprint. It
+never announces the token. The QR deep link carries the initial private
+endpoint, token, and fingerprint. Later Bonjour address changes are accepted
+only for the already-paired `hostId` with the same pinned fingerprint. Config
+and QR files are written atomically with user-only permissions and are excluded
+by the release-state audit.
+
+The nearby and Tailscale listeners are separate, so enabling local discovery
+does not replace or weaken remote access. No public relay is bundled: a
+reliable internet alternative would require operated identity, TURN/push, rate
+limiting, and abuse controls rather than exposing a desktop listener.
+
 An authenticated client may remain connected while the Mac app or its native
 Micro signals are unavailable. Snapshot failures are caught and rate-limited;
 they do not terminate the relay server or watcher. Normal snapshots resume
@@ -104,6 +133,12 @@ Agent keys are original deterministic SVGs generated in memory from task title a
 | `approval` | orange pause/input |
 | `error` | red error |
 
+When Codex exposes token usage for a task, an optional top-left ring shows the
+latest context-window percentage. Orange begins at 80% and red at 92%. Select
+any Agent key in Stream Deck's property inspector to show or hide this ring
+globally for all six agent keys on that computer. The setting is independent on
+Windows and macOS and does not stop context metadata from syncing.
+
 The renderer derives the active Codex appearance from explicit theme tokens when available and falls back to the computed renderer surface luminance. Dark mode uses layered charcoal surfaces rather than pure black, with off-white text and slightly lifted status colors for the Stream Deck display.
 
 Official Codex Micro keycap SVG contents are not part of the source or release. Optional user-local files are loaded from `%LOCALAPPDATA%\CodexDeck\icons` on Windows or `~/Library/Application Support/CodexDeck/icons` on macOS and wrapped in the project's neutral key surface at runtime.