<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&amp;style=for-the-badge&amp;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&amp;logo=linux&amp;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&amp;logo=python&amp;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>
  &nbsp;&middot;&nbsp;
  <a href="#mcp-tools">MCP tools</a>
  &nbsp;&middot;&nbsp;
  <a href="#safety-model">Safety model</a>
  &nbsp;&middot;&nbsp;
  <a href="docs/architecture.md">Architecture</a>
  &nbsp;&middot;&nbsp;
  <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](https://learn.chatgpt.com/docs/computer-use) and
[MCP](https://learn.chatgpt.com/docs/extend/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](https://developers.openai.com/plugins/concepts/plugins).

## 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:

```bash
# 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](https://github.com/ReimuNotMoe/ydotool) 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:

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

or:

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

Run the Doctor before connecting Codex:

```bash
codex-computer-use-linux --doctor
```

#### Option A: install the Codex plugin

```bash
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

```bash
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

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

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

```text
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](docs/safety.md) before use.

## Development

```bash
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](https://github.com/modelcontextprotocol/python-sdk).

## Uninstall and rollback

```bash
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](LICENSE).