A desktop GUI for the Codex CLI

What you get on top of the CLI

• Parallel workspaces. Each workspace is a separate git worktree on its own branch, so parallel Codex runs never write to the same checkout. There is no limit on the number of workspaces.
• A diff review loop. See what each Codex run changed, comment on specific lines, and send the comments back to Codex.
• Pull requests. Open a PR for the workspace branch without leaving the app.
• An editor and a preview. A Monaco-based editor with Jupyter notebook support, a terminal per workspace, and a built-in browser preview with freeze-frame annotations.
• Your phone. Maestro Web mirrors each workspace to a mobile web app, so you can follow a Codex turn, reply, and review the diff away from your desk. Codex keeps running on your own machine.

Codex features Maestro understands

• A model picker that follows your account. The Codex CLI keeps a catalog of the models your account can use in ~/.codex/models_cache.json. Maestro reads that file, so new Codex models show up in the picker without a Maestro update. If the file is missing, it falls back to a built-in list.
• Per-model reasoning effort. Each model shows the reasoning levels its catalog entry lists (Low, Medium, High, Extra High, and more on models that support them). Maestro passes your choice as Codex's model_reasoning_effort setting and clamps it to a level the model supports.
• Plan mode. Codex has no named plan mode, so Maestro's plan toggle runs the turn in Codex's read-only sandbox (--sandbox read-only) and tells Codex to investigate and reply with a plan instead of editing.
• A readable transcript. Codex's JSON events become chat: its messages, reasoning, shell commands with their output, file changes, MCP tool calls, and web searches.
• Your existing sessions. Maestro can import the Codex sessions already in ~/.codex/sessions, put each one in the matching repo, and keep syncing turns you run in a terminal. It only reads those files. If a Codex session is still running elsewhere, Maestro won't resume it at the same time.

How it works

Maestro runs the official codex binary in non-interactive mode, one process per message, in the workspace's worktree. The first message starts a thread with codex exec --json; later messages continue it with codex exec resume <thread-id>. The prompt goes in on stdin.

• Your account, your plan. Codex signs in the way it always does: with your ChatGPT account (codex login) or an OpenAI API key. Settings shows which one is active and, for a ChatGPT login, the plan. Maestro does not proxy or bill your usage. You can also save an API key in Settings; Maestro passes it to Codex as OPENAI_API_KEY.
• What gets installed. Only Maestro. It uses the codex on your PATH, with your existing config. If Codex is missing, Settings → Harnesses can install it and run codex login in an in-app terminal.
• Sandbox and approvals. Each workspace is already isolated in its own worktree, so by default Maestro runs Codex with approvals and the sandbox off, and turns never wait on a prompt. Choose a stricter mode in Settings and Maestro uses --full-auto instead, or the read-only sandbox in plan mode.
• Remote machines. On an SSH project, codex runs on the remote host.

Set it up

What about OpenAI's Codex app?

OpenAI has its own Codex desktop app. As of September 2026 it runs on macOS and Windows, with Linux in preview, and it has its own support for worktrees and code review (OpenAI's docs). If Codex is the only agent you use, it's worth trying.

Maestro makes sense when:

• you want a GUI over the Codex CLI itself, with the same config and sessions you use in the terminal, and to keep using the terminal too;
• you also use Claude Code, Cursor's agent CLI, OpenCode, Kimi Code, or Grok Build, and want them all in one window, one agent per workspace;
• you want every workspace on your phone through Maestro Web.

To do this by hand with plain git, read how to run Codex in parallel.