Codex Micro: expose a stable read-only Agent Key status/lighting API in app-server

What variant of Codex are you using?

Codex desktop app (macOS), Codex Micro, and Codex App Server

What feature would you like to see?

I’m building an unofficial, local-only visualizer for Codex Micro. The official device docs describe the Agent Key colors and behavior, but there is no documented interface for a companion app to read the same semantic state the Codex desktop app uses to drive the device.

Please expose a versioned, read-only capability through Codex App Server for the six configured Agent Key slots and their normalized display state.

A minimal contract could include:

• capability/schema version
• active agent source (recent, pinned, priority, or custom)
• six slots in display order, each with an opaque thread identifier or null
• normalized status (off, idle, working, completed, requiresInput, or error)
• selected/focused slot
• perimeter or voice-light semantic state
• a current snapshot method and change notifications

The interface should be local-only, explicitly opt-in, and must not expose titles, prompts, messages, transcripts, typed text, or other conversation content. A supported App Server transport such as stdio or a Unix socket would fit the existing architecture.

This would let accessibility tools, OBS/stream visualizers, and hardware companion apps integrate without inspecting private desktop-app bundles or relying on version-specific binary fingerprints.

Additional information

The documented thread/status/changed, turn lifecycle events, and approval/server requests are useful, but they do not expose the six-slot assignment/order, source selection, unread/completed distinction, selected Agent Key, or exact perimeter state.

At present, an exact local mirror has to requalify each desktop release because generated bundle names and private symbols are not a compatibility contract. A capability-discovered, versioned projection would allow clients to fail safely when the schema changes and remove coupling to private implementation details.

A generic semantic status projection is preferable to exposing raw internal lighting bytes; companion apps can derive their own visuals from a stable, privacy-preserving contract.