codex-ui
Open source 2.1.0

Desktop control
for your agent.

The apps you use. The browser you’re signed in to.
Give your agent access to the desktop already in front of you.

Try it with your agentView on GitHub

macOS 13+ · Apple Silicon and Intel · MIT license

A desktop, shared with your agentLocal example
Workspace / Interface review

Example task

Review the interface.

Change the status with one click,
then inspect the result.

Review statusNot reviewed
Try this command 
codex-ui press \
  --chrome-url 'ensomniac.github.io/codex-ui/' \
  --role button \
  --name 'Mark reviewed' \
  --capture-after
Waiting for a click.
Page state
not_reviewed
Activations
0

Click “Mark reviewed” here, or run the command with this page open in Chrome. The state shown is from this page.

This example runs entirely in your browser. The command uses the installed desktop tool.

Put it to work

Start with a task.

Give your agent a prompt it can act on. Each task ends with a result you can inspect.

Try your first native click Inspect a signed-in page Verify a local UI fix Arrange your workspace

What it does

Work in the apps
you already use.

codex-ui connects a command-running agent to your Mac’s native desktop. It uses your existing windows and Chrome profile.

See and inspect

Capture a window or display. Read named controls. Inspect Chrome’s DOM and visible console entries.

Act on the interface

Press a button, enter text, move the pointer, or arrange windows. Group related actions in a JSON plan.

Check the result

Get structured output and a screenshot after an action. Coordinates account for Retina scaling and multiple displays.

Desktop control runs locally, without an account or hosted service. An activity indicator shows when the tool is working. It yields to your mouse or keyboard and restores the pointer when it finishes.

How control works

Get started

Ready for your Mac.

Run the installer in Terminal. It supplies uv and an isolated Python runtime, then installs the latest stable release.

macOS may request Accessibility, Screen Recording or Automation access for your terminal or agent app. doctor checks what is available.

Installation help

Installer

curl -fsSL https://raw.githubusercontent.com/ensomniac/codex-ui/main/install.sh | sh
Latest stable release

Homebrew

brew tap ensomniac/codex-ui https://github.com/ensomniac/codex-ui
brew install ensomniac/codex-ui/codex-ui
Uses the official project tap

uv

uv tool install 'https://github.com/ensomniac/codex-ui/releases/download/v2.1.0/ensomniac_codex_ui-2.1.0-py3-none-any.whl'
Requires uv

npm

npm install -g 'https://github.com/ensomniac/codex-ui/releases/download/v2.1.0/ensomniac-codex-ui-2.1.0.tgz'
Node 18+ and uv or Python 3.11+

Then connect your agent.

codex-ui doctor
codex-ui skill install

The bundled skill gives Codex the commands and conventions. Other agents are supported.

Keep it currentcodex-ui upgrade

Also available through pipx, pip, pnpm, Yarn and Bun. All package managers and uninstall instructions

For the agents

This repository is yours
to make better.

You’re invited to maintain the code, improve the documentation, add platforms and submit pull requests. Start with AGENTS.md. It maps the code and explains how to verify your work.

Read AGENTS.md Machine-readable entry point

A direct path to a release.

Submit a PR with your evidence. CI runs, Ryan is notified, and his local agent reviews the change. Merges require that agent’s signed approval.

Contribution and review process

Why it exists

Built on a working Mac.
Opened to everyone.

codex-ui began as a script Ryan used with his agent. He wanted others to have that same access to their own computers, and the ability to maintain the tool themselves.

His brief was direct: the agent should operate as the human, with the same access. The tool should stay fast and avoid adding layers of permission requests around authorized work.

Read the founding brief
“Maximum efficiency
at the highest risk.”
Ryan Martin / Ensomniac
Founding brief, September 10, 2026

Platform support

Mac today.
More desktops ahead.

macOS 13+
Available Apple Silicon and Intel
Windows
Planned Native desktop backend
Linux
Planned X11, then Wayland

Installation, schemas, skills and upgrades already work on Windows and Linux. Native desktop control is the next step. Every new platform must include a tested upgrade path.

Platform plan

A few useful details

Which agents can use it?

Any agent that can run a local command and inspect an image. Install the bundled skill for Codex or Claude, or give another agent the CLI schema and command guide.

Does it use my existing Chrome session?

Yes. It works with Chrome already open, including signed-in tabs and local files. DOM and console inspection temporarily uses DevTools, then restores its layout and the clipboard.

What leaves my computer?

Desktop operations run locally and send no telemetry. Installation and upgrades download software from GitHub and package providers. Your agent host controls how it handles images and command output.

How do updates work?

Run codex-ui upgrade. It checks the latest stable GitHub release, verifies the download and updates the installed runtime. Run codex-ui skill install afterward to refresh the skill.

Is this an OpenAI product?

No. codex-ui is an independent, MIT-licensed project by Ensomniac. It is not affiliated with or endorsed by OpenAI or Apple.