Agent Orbs

Agent Orbs is an experimental native iPhone visualization of live Codex task activity. Every active root task is represented by a fluid orb. When it creates child tasks, smaller orbs divide outward from it; nested task trees are supported.

The visual direction is inspired by the ChatGPT Voice orb. This is an independent, unofficial fan project. It is not affiliated with, endorsed by, sponsored by, or otherwise connected to OpenAI. ChatGPT, Codex, and OpenAI are trademarks of their respective owner.

• Azure: the task is working.
• Amber: the task needs approval or user input.
• Slate: the task has stopped but one or more descendant tasks are active.
• When a stopped task has no active descendants, its finished branch disappears.

• macOS with Xcode
• An iPhone running iOS 17 or later
• The Mac and iPhone on the same local network
• Bluetooth enabled on both devices for background Live Activity updates
• The Codex desktop app using its standard local storage under ~/.codex

1. Open AgentOrbs.xcodeproj.
2. Select the Orb Bridge scheme and run it on My Mac. A small orb icon appears in the menu bar. Allow local-network access if macOS asks.
3. Set your Apple development team for the Agent Orbs and OrbActivityWidget targets, then run Agent Orbs on your iPhone.
4. Open the bridge's menu-bar item and scan its pairing QR with the iPhone app. Treat this QR like a password.
5. Allow camera, local-network, and Bluetooth access, then start Codex tasks normally.

The pairing secret is created from 256 bits of secure randomness and is stored in Keychain on both devices. Bonjour discovers only the paired bridge's random identifier. Each TCP connection uses a fresh mutual challenge-response handshake, derives a connection-specific key, and carries only ChaCha20-Poly1305 authenticated ciphertext. Unpaired clients receive no task snapshot.

While the iPhone app is open, the authenticated TCP connection drives the full-screen renderer. In the background, Orb Bridge also sends the same minimal snapshot over an encrypted Bluetooth Low Energy characteristic so iOS can wake the app and refresh its Live Activity without a cloud service or push server when iOS grants background execution.

The bridge reads Codex's local database and session logs to infer task state and relationships. Those session files can contain sensitive prompts, responses, tool calls, and local paths. The bridge parses them locally but sends only opaque task IDs, hierarchy, timestamps, and activity states to the simulator.

The bridge listens on the local network so a physical iPhone can reach it, but task snapshots are not sent before mutual authentication and are never sent as plaintext. The project contains no analytics, telemetry, advertising, or cloud API integration. Read PRIVACY.md and SECURITY.md before running it.

• OrbBridge: read-only SQLite/session-log observer and secure local-network and Bluetooth publisher.
• OrbWatcher: full-screen SwiftUI host with a native Metal renderer.
• Shared: the small wire model and pairing/cryptography code shared by both targets.
• agent-threads.html: the original standalone interaction prototype.

The Metal shader is compiled from bundled source when the app starts. This keeps the project runnable when Xcode's optional offline Metal toolchain is not installed.

• Codex's local database and event formats are undocumented and may change.
• Parent/child detection is inferred from session events.
• The QR is a bearer secret: anyone who scans or photographs it can pair.
• The current prototype uses one shared pairing secret for the bridge rather than separate per-phone credentials.
• Encryption does not prevent local-network denial-of-service, Bonjour interference, Bluetooth interference, or radio blocking.
• iOS controls background execution; updates can be delayed after force-quit, Bluetooth is disabled, or the system declines to relaunch the app.
• The security protocol has tests but has not received an independent audit.
• This is not an App Store-ready product.

MIT. See LICENSE.