Moben Codex

Follow and steer the Codex tasks on your computer from a Moben e-ink device, by voice: browse your tasks, start new ones, watch a running task, and approve commands and file changes on the device.

Voice capture and streamed task pages require current Moben protocol 2 firmware and SDK 0.6 or later; update beta clients together.

Requirements

• A Moben device bound to your own Moben account.
• Codex on the computer: the one bundled with the ChatGPT desktop app, or a codex command on your PATH. Set CODEX_BIN to use another one.
• Node.js 20.12 or later.

Usage

npm install -g @moben-ai/codex
moben-codex login     # first time only: approve this computer in the browser
moben-codex           # keep this terminal open; Codex appears in the device's app list

Run moben-codex once after you start the computer. When you close the terminal or press Ctrl-C, the device shows the app as offline.

Only one copy runs on a computer: starting it again says it is already running. moben-codex status shows whether it is running. If you start it on another computer with the same account, the first one disconnects and exits.

Notes

• The app uses your own Codex configuration (approval policy, sandbox, approval reviewer); the model, reasoning effort and speed can be changed per task on the device. Whoever holds the device can have Codex work on this computer, so keep approvals on.
• Approval requests appear on the device when Codex asks you to approve. If your Codex configuration sends approvals to automatic review instead, they are decided on the computer and the device only shows the result.
• A task that is open in the Codex desktop app can only be continued there; the device says so.
• On device app protocol 2 with the optional appPageActivity capability, pending text at the end of the page follows app-server events: reasoning → Thinking, active commands/tools → Executing, approval → Approval, user input → Your input. Unknown phases use Waiting. Approval/input flags take priority; parallel work stays active until its last item completes. Reopening a page preserves current evidence, late events and stale snapshots cannot overwrite newer work, and completion/disconnection clear it. The cloud uses the existing conversation backspace rewrite, erases status before real content and completion, and keeps the footer page counter. The task body has no fixed working line. Older beta clients must update; no protocol 1 page fallback is provided.
• Settings for new tasks chosen on the device are kept in ~/.moben-codex/. Model, reasoning effort and speed menus focus the current choice when opened on firmware with Action Sheet selection support.

Only running task pages request interaction: { autoPage: true } on protocol 2; completed tasks open at the beginning and returning to a retained page preserves its position. On running tasks, new screens follow only while the user is on the last screen. Reading earlier screens, selecting links or opening overlays keeps the current view; returning to the last screen resumes following. Other pages keep manual paging.

All pages use the default SDK stream. Task pages publish completed upstream items as they arrive through the existing message renderer, while the page stays open for later items. Replies appear in full on task and history pages, without a character-limited preview or a “Full text” link; the existing turn and page size budgets still apply. Temporary waiting/thinking/execution status follows upstream events and remains separate from reply text. The cloud uses the existing Markdown line conversion shared with conversation output.

Local images in Codex replies appear as “caption · View image” links, including in older tasks and full-message pages. Opening a link displays just that image; the menu key returns to the retained reply at the same screen and link focus, without refreshing it. Absolute paths, file: URLs and paths relative to the task's directory are supported. Images are loaded on demand, resized to fit within 440×600 pixels and sent as inline grayscale PNGs on their own page. If the source file is missing, unsupported or oversized, the image page explains that it is unavailable. Remote image URLs are not fetched.

Development

This app lives in codex/ in the Moben Apps repository. From the repository root:

cd codex
npm install
npm start                 # runs src/cli.ts with tsx
npm run check            # validates pages locally through tsx (entry app.ts)
npm run typecheck
npm run build             # bundles dist/cli.js

src/app.ts defines the Moben app (pages, actions, voice routes), src/hub.ts tracks tasks through a private codex app-server (src/codex.ts), and src/cli.ts is the command line. src/activity.ts reduces upstream thread/item events into the current temporary status; it never infers reasoning from elapsed time or stores reasoning text. See the Moben app SDK for the page and voice contract.

Run all development commands from codex/. Dependencies and build output stay in this directory; user settings remain in ~/.moben-codex/. The npm package name and moben-codex command are unchanged.

npm run check loads the SDK validator through tsx so extensionless TypeScript imports work on Node.js 20 and 22. To inspect a specific page, use npx tsx node_modules/@moben-ai/app-sdk/dist/cli.js app page / --locale zh-CN.

License

MIT