codex-computer-use-linux

<p align="center"> <img src="assets/banner.svg" alt="Codex Computer Use for Linux — MCP server and Codex skill" width="100%"> </p>

<h1 align="center">Codex Computer Use for Linux</h1>

<p align="center"> <strong>Safe Linux desktop automation for Codex through a focused MCP server and reusable skill.</strong><br> Inspect, click, type, drag, and verify native applications on Wayland and X11. </p>

<p align="center"> <a href="https://github.com/maxionice/codex-computer-use-linux/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/maxionice/codex-computer-use-linux/ci.yml?branch=main&style=for-the-badge&label=CI" alt="CI status"></a> <a href="https://kernel.org/"><img src="https://img.shields.io/badge/platform-Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black" alt="Linux only"></a> <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.11 or newer"></a> <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-2.x-7C3AED?style=for-the-badge" alt="Model Context Protocol 2.x"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache--2.0-38BDF8?style=for-the-badge" alt="Apache 2.0 license"></a> </p>

<p align="center"> <a href="#quick-start"><strong>Quick start</strong></a>  ·  <a href="#mcp-tools">MCP tools</a>  ·  <a href="#safety-model">Safety model</a>  ·  <a href="docs/architecture.md">Architecture</a>  ·  <a href="CONTRIBUTING.md">Contributing</a> </p>

---

Codex Computer Use for Linux is an open-source Linux computer-use MCP server and Codex skill for controlled desktop GUI automation. It gives Codex a deliberately small tool surface for working with visible native applications while keeping sensitive workflows out of scope.

[!IMPORTANT] This is an independent community project. It is not made, supported, or endorsed by OpenAI and does not claim feature parity with OpenAI Computer Use.

OpenAI's current Computer Use plugin supports macOS and Windows, while Codex can connect to local STDIO MCP servers. This project fills the Linux integration gap with an MCP action layer and a skill that teaches Codex the safe observe → act → verify loop. See the official Computer Use and MCP documentation for the product boundaries.

Why MCP plus a skill?

Layer	Responsibility
MCP server	Executes typed, bounded Linux desktop actions and reports capability errors.
Codex skill	Chooses safe action sequences, verifies UI state, and stops on sensitive flows.
Plugin	Packages the skill and MCP connection for repeatable installation.

A skill alone cannot reliably provide live screenshots or controlled input. An MCP server alone does not teach the model a safe visual workflow. The hybrid plugin follows OpenAI's documented plugin architecture.

What it does

• Linux-only runtime guard; no silent macOS or Windows fallback.
• Wayland input through ydotool; X11 input through xdotool with ydotool fallback.
• Screenshots through grim, gnome-screenshot, scrot, or ImageMagick import.
• Typed MCP tools for status, screenshot, pointer movement, click, drag, text, keys, and scroll.
• No arbitrary shell tool, application launcher, clipboard reader, or secret store access.
• Best-effort blocking of terminals, ChatGPT, and Codex when the active window is discoverable.
• Structured Doctor output and in-memory MCP contract tests.
• Installable Codex plugin plus direct MCP-server setup.

Quick start

Requirements

• Linux with an active graphical session.
• Python 3.11 or newer.
• One screenshot backend.
• One input backend.

Session	Screenshot	Input	Notes
Wayland	grim or gnome-screenshot	ydotool	ydotoold needs access to /dev/uinput.
X11	gnome-screenshot, scrot, or import	xdotool	ydotool is an optional fallback.

Install only the packages relevant to your desktop. Typical package names are:

# Debian / Ubuntu
sudo apt install python3 python3-venv xdotool gnome-screenshot ydotool grim

# Fedora
sudo dnf install python3 xdotool gnome-screenshot ydotool grim

# Arch Linux
sudo pacman -S python xdotool gnome-screenshot ydotool grim

Package availability differs by distribution and desktop environment. On Wayland, configure and start ydotoold according to your distribution. The upstream ydotool documentation explains its /dev/uinput permission model; do not run Codex itself as root.

Install

Install the server CLI with one of these isolated Python tool managers:

uv tool install git+https://github.com/maxionice/codex-computer-use-linux.git

or:

pipx install git+https://github.com/maxionice/codex-computer-use-linux.git

Run the Doctor before connecting Codex:

codex-computer-use-linux --doctor

Option A: install the Codex plugin

codex plugin marketplace add maxionice/codex-computer-use-linux
codex plugin add codex-computer-use-linux@maxionice-linux-tools

Start a new Codex thread after installing so the skill and MCP tools are loaded.

Option B: add only the MCP server

codex mcp add linux-desktop -- codex-computer-use-linux
codex mcp list

For approval on input-producing tools, configure default_tools_approval_mode = "writes" for the server in ~/.codex/config.toml.

Example prompts

Use $use-linux-desktop to open the app's settings and verify that dark mode works.

Inspect the visible calculator app, enter 125 * 8, and report the displayed result.

Reproduce the onboarding bug in the already-open Linux app. Stop before any login prompt.

MCP tools

Tool	Effect
desktop_status	Reports session, available backends, active window, and warnings.
take_screenshot	Returns the current desktop as PNG image content.
move_pointer	Moves the pointer to absolute screenshot coordinates.
click	Moves and clicks left, middle, or right.
drag_pointer	Drags between two absolute coordinates.
type_text	Types bounded plain text into the focused control.
press_key	Presses a named key with optional modifiers.
scroll	Scrolls on X11; Wayland users can use Page Up/Down through press_key.

The server never accepts a command string or invokes a shell. Every native command is constructed from validated typed arguments.

Safety model

Desktop automation can act with your logged-in user's permissions and screenshots may contain sensitive data. Keep the target app visible, close unrelated sensitive apps, and review every approval prompt.

The bundled skill refuses terminal, ChatGPT, Codex, credential, administrator, security, payment, and privacy-setting flows. Active-window blocking is best effort because some Wayland compositors do not expose the focused application. Read the complete safety model before use.

Development

git clone https://github.com/maxionice/codex-computer-use-linux.git
cd codex-computer-use-linux
python -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
python -m ruff format --check .
python -m ruff check .
python -m mypy src
python -m pytest

The project uses the stable MCP Python SDK 2.x, which supports the 2026-07-28 MCP specification. See the official MCP Python SDK.

Uninstall and rollback

codex plugin remove codex-computer-use-linux
codex plugin marketplace remove maxionice-linux-tools
codex mcp remove linux-desktop
uv tool uninstall codex-computer-use-linux

If you installed with pipx, replace the final command with pipx uninstall codex-computer-use-linux. Removing the plugin or MCP entry stops Codex from launching the server; removing the tool installation deletes the local executable. System packages such as ydotool are not removed automatically.

Trademark and affiliation

This is an independent open-source project and is not affiliated with or endorsed by OpenAI. OpenAI, Codex, ChatGPT, and related marks belong to their respective owners.

License

Apache-2.0. See LICENSE.