Codex(W)UI

Follow the work, not just the final answer. Codex(W)UI offers two frontends: CodexUI, a native Qt desktop application, and CodexWUI, a browser application connecting over WebSocket. They bring conversations, commands, plans, approvals and file changes into a visual coding workspace.

Built on AISuite and SNode.C, both frontends connect through AISuite's codex-bridge. Codex app-server remains responsible for agent execution and persistent history; both applications give you the controls and visibility around it.

1. Install: prepare the native or browser frontend.
2. Use: connect your chosen frontend and send a prompt.
3. Configure: review runtime settings and access controls before deployment.

Actual native application, captured during an isolated qualification session with a disposable demonstration thread. Click the image to inspect it at full resolution. Image provenance.

• Organize the work: browse threads, search titles, archive work and return to retained history. In the native app, group threads by projects and shared sections.
• Follow execution: read streamed responses, reasoning summaries and command output in one conversation. Send prompts, steer an active turn, stop work and respond to approval requests.
• Inspect results: keep plans, agent activity, requests, changes and timing details beside the conversation. Review repository diffs, copy output and inspect the protocol when diagnosing a problem.

• Rich, distinct activity cards. Markdown, commands, file changes, plans, images and agent activity keep their own controls and presentation.
• History without loading every widget. Paginated history and virtualized native rendering keep offscreen content as data rather than another renderer.
• Input beyond plain text. The native composer accepts image paste and local file drag/drop, alongside the attachment picker and multiline editing. Pasted images are stored as durable local PNG files with no automatic expiry; review retained files when handling sensitive material.
• Context when you need it. Supplied timestamps, durations, token information and detailed Inspector views make execution easier to understand.

In the native threads panel, projects contain the visual grouping; sections organize the threads within it. A section can appear in multiple projects because project and section memberships are independent. Standalone sections and ungrouped threads remain visible too.

To create a project or section, click the current grouping label—Projects, Sections or Ungrouped—above the thread list. Use a thread's context menu to assign its project and section. Creation and assignment require controller access and server support.

CodexUI integrates with the Linux desktop for local workspaces, project/section organization and desktop file interaction. Installation provides codex-ui, a desktop entry and an icon. Available transports depend on the build.

CodexWUI (build/install component CodexWebUI) connects through AISuite's frontend SDK without installing the Qt application. codex-bridge serves the built web assets; no Node runtime is required.

The frontends share protocol and lifecycle meaning, not an identical feature inventory. Native project/section management is not yet a browser feature. See the native-only features and browser limitations before choosing a deployment.

Build the native Qt desktop or browser assets served by codex-bridge. Both are source-installation routes, not binary releases; running the browser assets requires neither Qt nor a Node runtime.

You need: the native build, a configured Codex executable available to the bridge user, and AISuite's codex-bridge. The bridge's generated protocol targets Codex 0.154.0; use the AISuite entry page to check compatibility before changing Codex versions.

Start codex-bridge --config-file /dev/null as your own user in one terminal. In a second terminal, run from this checkout:

./build/codex-ui

The default native transport is Unix JSONL, using the same private socket as the bridge: a valid private XDG_RUNTIME_DIR plus /codex-bridge.sock, otherwise /tmp/codex-bridge-<uid>/codex-bridge.sock. In Connection, select the built transport, verify its Socket path (or host/port for a network transport), and choose Apply and connect. Dialog changes apply to this UI session; command-line/SNode.C configuration supplies startup defaults.

Wait for the provider to become ready. If you are an observer and no controller owns the session, choose Claim control. Controller ownership authorizes mutations on this bridge connection; it is not a login or a replacement for Codex approval/sandbox settings. Choose or create a thread and send a prompt in a disposable workspace.

Expected result: the thread list loads, the UI identifies your controller role, and a submitted prompt receives streamed activity and a response. A connection without provider readiness is not a successful agent run. Model requests may incur provider charges; avoid private workspaces while trying the example.

After building the browser assets, run this from the checkout root with AISuite's WebSocket support enabled and port 8080 free:

codex-bridge --config-file /dev/null codex --bridge-web-root "$PWD/web/app-dist" \
  codex-bridge-websocket-ipv4 --disabled=false \
  local --host 127.0.0.1 --port 8080

Open http://127.0.0.1:8080/. The page and /codex WebSocket share that loopback listener. Connect, claim control if it is vacant, and use a disposable thread for a first prompt. Expect the thread list and streamed response, as with the native route. For installed assets, endpoint overrides and remote deployment, use the browser deployment guide; no Node server is required.

If the first run fails, check connection and controller ownership before retrying the prompt.

For native endpoints, use Connection as described in First run; startup defaults come from command-line/SNode.C settings, while the dialog applies to the current session. Browser endpoints and retained URL settings are documented in browser deployment.

Controller/observer roles are routing permissions, not authentication or tenant isolation. Observers can receive session broadcasts and read approved workspace data, including files. Keep the Unix socket private and browser/network listeners on loopback unless an external authenticated TLS boundary protects them. App-server configuration remains authoritative for model selection, approvals and sandbox permissions.

See Connection and controller ownership for endpoint and startup configuration; see Using CodexUI for interaction details and Architecture for component ownership.

CodexUI / CodexWUI ↔ AISuite bridge ↔ Codex app-server

The bridge allows multiple frontends to follow the same app-server session, with one controller at a time and policy-limited observers. Controller status is distinct from the agent's approval and sandbox settings.

On the native side, a SNode.C worker owns protocol processing and writes one shared NodeGraph; Qt projects that state into widgets. The browser uses AISuite's TypeScript SDK and its own presentation state. Neither frontend replaces app-server's persistent history or tool execution.

For the detailed state, threading and protocol boundaries, see the architecture guide.

For bug reports, include the revision, Qt version, connection type and the smallest reproducible sequence. Remove credentials and private conversation content from logs and screenshots.

The documented native platform is Linux with Qt 6.6+ Widgets. Browser frontend scope, coverage and limitations are defined by the browser contract; they are not a promise of native/browser feature parity. Review the known limitations before relying on approval handling or native performance.

No GitHub release or shared binary-package distribution is published yet; the documented installation routes build from source. Future release notes belong on the releases page. The web release process describes development qualification, not a downloadable product release.

Report an issue using the sanitized information in Documentation; read the existing agent/engineering instructions and build/qualification guide.

SNode.C organization · Depends on AISuite and SNode.C

Choose either MIT or LGPL-3.0-or-later.

Built with Qt. Codex(W)UI is an independent project; neither frontend is an official OpenAI application.

Maintainer: Volker Christian. Organization · Contributing · Security