Codex Desktop: expose opt-in local Terminal API for visible terminal tabs #25586

What feature would you like to see?

Expose an opt-in, local-only API for Codex Desktop visible terminal tabs, so trusted local controllers can list/create/write to the terminal tabs that are already visible in the Codex Desktop app without relying on keyboard/Accessibility/PTY input emulation.

Suggested shape:

• Terminal/list: list visible Codex Desktop terminal tabs with stable terminalId, title, cwd, shell, busy/closed state, and owning window/thread metadata where available.
• Terminal/create: create a new visible Codex Desktop terminal tab with optional cwd/profile/title metadata and return its terminalId.
• Terminal/write: write text to a specific visible terminal tab by terminalId; never use implicit focused target semantics. Ideally support submit: true/false instead of requiring clients to append Enter manually.
• Terminal/runAction: bounded terminal actions such as interrupt, clear, resize, close, or restart, again by explicit terminalId.

This is related to #15355, but the request here is specifically for Codex Desktop's integrated terminal tabs, not only the standalone CLI/TUI.

Why this matters

Codex Desktop already provides visible terminal tabs, which makes them a good control surface for local orchestration and cross-tool workflows. The missing piece is a supported local ingress API.

Today, local controllers that want to send a prompt or command to a visible Codex Desktop terminal tab must fall back to brittle UI/input emulation, for example:

• Accessibility focus checks and paste/Return
• AppleScript keyboard events
• terminal multiplexer send-keys
• direct PTY writes in other terminal hosts

Those approaches are unsafe for this workflow because text can land in the wrong place:

• the Codex chat composer instead of the terminal
• the wrong terminal tab
• a shell tab instead of a teammate CLI route
• a teammate CLI route instead of a shell tab
• a non-empty draft or human typing state

A stable terminalId API would let local orchestrators fail closed instead of guessing from focus state.

What I observed

On macOS Codex Desktop codex-cli 0.135.0-alpha.1, the public app-server schema exposes useful process primitives such as command/exec, command/exec/write, and PTY-related output notifications.

Those are useful, but they are app-server-managed processes. They do not address an existing visible Codex Desktop terminal tab by stable tab/session identity.

The Desktop app itself appears to already have internal terminal operations such as terminal-create, terminal-attach, terminal-write, terminal-run-action, terminal-resize, and terminal-close between the renderer and Electron main process. The missing part is a supported external/local API boundary with explicit identity, authorization, and audit semantics.

Why existing paths are close but not enough

• command/exec / command/exec/write: good for managed app-server processes, but not the same UX or evidence surface as writing to an existing visible Codex Desktop terminal tab.
• queued turns / TUI follow-up work such as feat: expose queued turn app-server RPCs #23619 and feat: queue TUI follow-ups through app-server #25258: directionally useful for Codex turn scheduling, but they do not solve arbitrary visible terminal-tab input for local teammate CLIs or shell tabs.
• Accessibility / keyboard emulation: works only as a fragile local workaround and cannot provide reliable target identity, route metadata, or auditability.
• broad remote control: larger than needed. This can be local-only, opt-in, and same-user scoped.

Safety requirements

A supported API should fail closed unless the caller can address a specific terminal session by stable id. Recommended guardrails:

• local-only by default, ideally Unix socket or existing app-server local auth/capability-token model
• explicit terminalId; no focusedTerminal write endpoint
• visible/auditable writes, with payload preview or payload hash in logs/events
• non-empty draft/input-state detection where feasible
• route metadata so a controller can distinguish shell, Codex CLI, Claude Code, OpenCode, or other teammate CLI tabs
• one-writer lock or conflict signal for concurrent writes
• output/closed notifications for transcript and lifecycle tracking

Suggested direction

If this fits the app-server direction, a small first step could be exposing Desktop terminal session enumeration and write by id:

• Terminal/list
• Terminal/write
• Terminal/outputDelta or equivalent audit/output notification

Terminal/create and Terminal/runAction could follow later.

The goal is not to bypass the visible UI. The goal is the opposite: keep the terminal tab visible while replacing focus/keyboard emulation with an explicit, auditable, local API.