This plugin displays a numbered Codex task on a Stream Deck key. Its property inspector deliberately has one option: Task Number. Task 1 is the most recent shared Codex session, task 2 is the next most recent, and so on.
The key header is <project>: <session>. Session numbers are assigned in
creation order among each project's currently open shared-server sessions;
they reset to 1 after that project's sessions close. Task positions are
ordered by most recent activity. Project colours are generated deterministically,
so a given project keeps its colour.
The plugin starts a local Codex app-server at ws://127.0.0.1:45999 and
connects to it. Start Codex sessions through that same server and explicitly
pass the project working directory:
codex --remote ws://127.0.0.1:45999 --cd "$PWD"The explicit --cd matters because the app-server runs inside the Stream
Deck plugin directory; without it, Codex records that plugin directory as the
thread's working directory.
This shared-server connection is required for live status. The app-server
reports WORK, WAIT, and DONE reliably for threads it owns; it correctly
marks separately started CLI sessions as notLoaded, so the plugin excludes
them rather than showing an incorrect state. WAIT covers both approvals and
interactive user-input requests.
The plugin caches loaded-thread metadata and applies status and lifecycle
notifications immediately. Every 30 seconds it reconciles using
thread/loaded/list and thread/read without turns, so missed events recover
without repeatedly scanning historical sessions. With no loaded sessions, each
reconciliation needs only one request. A key press also requests a refresh.
To use an app-server you manage yourself, launch it separately and set the
Stream Deck plugin process environment variable CODEX_APP_SERVER_URL to its
localhost WebSocket URL. This does not add a Stream Deck configuration option.
npm run build
node --test tests/*.test.mjs
streamdeck link com.falcon.falcon
streamdeck restart com.falcon.falconThe generated plugin is in com.falcon.falcon.sdPlugin.
