@agent-sh/computer-use-linux 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avi Fenesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,312 @@
+# computer-use-linux
+
+Linux desktop control for any MCP host — AT-SPI accessibility trees, portal screenshots, Wayland/X11 input, and multi-compositor window targeting for GNOME, KDE/KWin, Hyprland, i3, and COSMIC.
+
+[![CI](https://github.com/avifenesh/computer-use-linux/actions/workflows/ci.yml/badge.svg)](https://github.com/avifenesh/computer-use-linux/actions/workflows/ci.yml)
+[![crates.io](https://img.shields.io/crates/v/computer-use-linux.svg)](https://crates.io/crates/computer-use-linux)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Current release: [`v0.2.1`](https://github.com/avifenesh/computer-use-linux/releases/tag/v0.2.1). The Rust crate is published as [`computer-use-linux`](https://crates.io/crates/computer-use-linux), and the npm wrapper is published as [`@agent-sh/computer-use-linux`](https://www.npmjs.com/package/@agent-sh/computer-use-linux).
+
+## What this is
+
+`computer-use-linux` is a Rust MCP server and CLI for Linux desktop control. The crate ships the main `computer-use-linux` binary plus a small `computer-use-linux-cosmic` helper used only for COSMIC Wayland window management. Any MCP host — Codex Desktop's Linux build, Claude Desktop, [Hermes Agent](https://github.com/NousResearch/hermes-agent), or your own client — can spawn it and gain full control of the local Linux desktop: read accessibility trees, list and focus windows, take screenshots, click, drag, scroll, type, and invoke semantic accessibility actions.
+
+Most computer-use MCP servers are macOS-only (they rely on AppKit, AXUIElement, CGEvent). The few that target Linux either drive `xdotool` against an X11 root window or shell out to OCR over screenshots. This crate is different on four points worth caring about:
+
+- **Wayland actually works.** Pointer actions can use the `org.freedesktop.portal.RemoteDesktop` interface on Wayland, with `ydotool` / `ydotoold` (uinput) as the deterministic fallback and keyboard/text path. Screenshots use the GNOME Shell DBus screenshot method when present and `org.freedesktop.portal.Screenshot` otherwise.
+- **Window targeting is compositor-aware.** The window registry tries GNOME Shell extension, GNOME Shell Introspect, COSMIC Wayland helper, KWin DBus scripting, Hyprland `hyprctl`, and i3 IPC in order, then reports exactly which backend won or why each backend failed.
+- **Semantic selectors, not pixel coordinates.** Tools like `click`, `perform_action`, and `set_value` accept `role` / `name` / `text` / `states` selectors backed by AT-SPI. Pixel coordinates remain available as a fallback for rendering-only surfaces (canvas, games, X clients without ATK).
+- **One JSON readiness report.** `computer-use-linux doctor` returns a structured document covering platform, portals, AT-SPI, windowing, input, and a `readiness` summary with explicit blockers and a recommended next step. MCP hosts can render or surface that to the user without parsing prose.
+
+The crate was extracted from [`codex-desktop-linux`](https://github.com/avifenesh/codex-desktop-linux) (the Linux distribution of Codex Desktop), which still bundles this binary as a built-in plugin. This standalone repo is the upstream.
+
+## Features
+
+15 MCP tools exposed by the current `v0.2.1` server:
+
+**Diagnostics**
+- `doctor` — single-shot JSON readiness report (platform, portals, accessibility, windowing, input, readiness summary)
+- `setup_accessibility` — enables GNOME's `org.gnome.desktop.interface toolkit-accessibility` setting so toolkit apps expose AT-SPI trees
+- `setup_window_targeting` — installs and enables the bundled GNOME Shell extension when `org.gnome.Shell.Introspect` is locked down
+
+**Discovery**
+- `list_apps` — running desktop apps visible to the AT-SPI registry
+- `list_windows` — compositor windows with title, app id, wm_class, focus state, client type (Wayland/X11), and bounds
+- `focused_window` — the window currently holding keyboard focus
+- `get_app_state` — combined screenshot + accessibility tree for a chosen app, with element indices that the input tools accept
+
+**Input**
+- `click` — by element index, semantic selector, or pixel coordinates
+- `drag` — pixel-coordinate drag (start / end)
+- `scroll` — page-based scroll on an element or at a pixel location
+- `press_key` — keys / chords; can focus a window or terminal first
+- `type_text` — literal text input, optionally targeted at a window or terminal
+
+**Semantic actions**
+- `perform_action` — invoke any AT-SPI action exposed by an element (`Press`, `Activate`, `Toggle`, …); defaults to the primary action
+- `set_value` — write to a settable accessibility element (text fields, sliders, spinners)
+
+**Navigation**
+- `activate_window` — focus a window by `window_id`, `pid`, `app_id`, `wm_class`, `title`, or terminal selectors
+
+### MCP safety contract
+
+`computer-use-linux` is not a read-only data source. It can observe the local desktop and, when a mutating tool is called, can change real application state. The `tools/list` response includes MCP `ToolAnnotations` so hosts can surface this distinction before invocation:
+
+| Class | Tools | Contract |
+| --- | --- | --- |
+| Read-only observation | `doctor`, `list_apps`, `list_windows`, `focused_window`, `get_app_state` | `readOnlyHint=true`; may reveal app, window, accessibility, and screenshot contents. `get_app_state` may trigger the desktop screenshot portal prompt. |
+| Local setup mutators | `setup_accessibility`, `setup_window_targeting` | `readOnlyHint=false`, `destructiveHint=false`, `idempotentHint=true`; modifies user desktop configuration by enabling accessibility or installing/enabling the GNOME window-targeting extension. |
+| UI state mutators | `activate_window`, `scroll` | `readOnlyHint=false`, `destructiveHint=false`; changes focus or scroll position in the live desktop. |
+| Desktop action mutators | `click`, `drag`, `press_key`, `type_text`, `perform_action`, `set_value` | `readOnlyHint=false`, `destructiveHint=true`, `openWorldHint=true`; can trigger arbitrary actions in whatever local application is targeted. |
+
+Annotations are safety hints, not an authorization system. MCP hosts should still ask the user before calls that could submit, delete, send, purchase, overwrite, or otherwise commit state.
+
+The binary also exposes the same capabilities from the CLI for scripting and debugging:
+
+```
+computer-use-linux mcp                                  # stdio MCP server
+computer-use-linux doctor                               # JSON readiness report
+computer-use-linux setup                                # enable AT-SPI
+computer-use-linux setup-window-targeting               # install GNOME Shell extension
+computer-use-linux apps
+computer-use-linux state [APP_NAME]
+computer-use-linux screenshot                           # JSON screenshot summary
+computer-use-linux windows
+```
+
+## Support matrix
+
+Validated manually on Ubuntu 25.10 (GNOME Shell 50.1, Wayland). Other compositor backends are implemented and covered by parser / contract tests, but real desktop behavior still depends on each session exposing its expected control API.
+
+| Desktop/session | Window backend | Notes |
+| --- | --- | --- |
+| GNOME Wayland | GNOME Shell extension first, `org.gnome.Shell.Introspect` fallback | Full target. The extension provides exact window activation when GNOME blocks native introspection; Introspect can list windows and focus apps by `app_id` when allowed. |
+| GNOME X11 | `org.gnome.Shell.Introspect` when allowed | AT-SPI and `ydotool` work; the bundled GNOME Shell extension is only needed for GNOME Wayland. Exact per-window focus may be unavailable without the extension backend. |
+| KDE Plasma / KWin | temporary KWin DBus scripting | Lists and focuses windows through `org.kde.KWin` scripting when the session bus exposes it. |
+| Hyprland | `hyprctl clients -j` and `hyprctl dispatch focuswindow` | Requires `hyprctl` in the desktop session. |
+| i3 | `i3-msg`; optional `xprop` for PID hydration | Lists and focuses i3 windows over the active i3 IPC socket. |
+| COSMIC Wayland | `computer-use-linux-cosmic` helper | Installed automatically by `./install.sh`, `cargo install`, and npm. For custom/manual layouts, put the helper next to the main binary, on `PATH`, or point `COMPUTER_USE_LINUX_COSMIC_HELPER` at it. |
+| Sway / generic wlroots | no dedicated backend yet | AT-SPI, screenshots, and global `ydotool` input can still work; exact window list/focus is currently unavailable unless another backend applies. |
+| Generic X11 / XFCE / other WMs | no dedicated backend yet | AT-SPI plus `ydotool` global input only, unless running under i3. |
+
+If you run on a desktop not covered above, or a covered backend does not come up cleanly, please open an issue with the output of `computer-use-linux doctor` so we can extend the matrix honestly.
+
+## Install
+
+COSMIC users do not need a second package or a separate helper install when using `./install.sh`, `cargo install`, or the npm wrapper. Those paths install `computer-use-linux-cosmic` alongside the main binary automatically. Only manual prebuilt-binary installs need you to copy both release assets.
+
+### Option A — `./install.sh` from a clone
+
+Installs system packages on Debian/Ubuntu, Fedora/RHEL-like, or Arch-like distros; installs Rust if needed; builds both release binaries; installs them to `~/.local/bin`; enables `ydotoold` as a user service; enables GNOME AT-SPI settings when running under GNOME; and installs the bundled GNOME Shell extension on GNOME Wayland.
+
+```bash
+git clone https://github.com/avifenesh/computer-use-linux
+cd computer-use-linux
+./install.sh
+# log out and back in if the GNOME extension was newly installed
+computer-use-linux doctor | jq .readiness
+```
+
+### Option B — `cargo install` (Rust binaries, no system setup)
+
+Installs the Rust binaries from crates.io. You still handle the system-level pieces yourself: `ydotoold`, AT-SPI, desktop portals, and the GNOME extension if you need the GNOME Wayland exact-focus backend.
+
+```bash
+cargo install computer-use-linux --version 0.2.1
+computer-use-linux doctor
+```
+
+For unreleased changes from `main`, install directly from Git:
+
+```bash
+cargo install --git https://github.com/avifenesh/computer-use-linux
+```
+
+Then, as needed:
+
+```bash
+sudo apt install ydotool at-spi2-core         # or your distro's equivalent
+systemctl --user enable --now ydotoold
+computer-use-linux setup                      # gsettings AT-SPI bridge
+computer-use-linux setup-window-targeting     # GNOME Shell extension
+```
+
+### Option C — npm wrapper (binary download)
+
+Good for users who already have Node.js and want a no-Rust install. The npm package downloads and verifies the matching main and COSMIC helper binaries during install, then the wrapper sets `COMPUTER_USE_LINUX_COSMIC_HELPER` to the bundled helper automatically.
+
+```bash
+npm install -g @agent-sh/computer-use-linux@0.2.1
+computer-use-linux doctor
+```
+
+You will still need `ydotoold` running and AT-SPI enabled (run `computer-use-linux setup` and the systemd commands above).
+
+### Option D — prebuilt binaries
+
+Linux x86_64 / aarch64 builds are published with each tag. Each binary ships a `.sha256` next to it.
+
+- Release: <https://github.com/avifenesh/computer-use-linux/releases/tag/v0.2.1>
+
+```bash
+target=x86_64-unknown-linux-gnu
+version=v0.2.1
+for binary in computer-use-linux computer-use-linux-cosmic; do
+  asset="$binary-$target"
+  curl -L -O "https://github.com/avifenesh/computer-use-linux/releases/download/$version/$asset"
+  curl -L -O "https://github.com/avifenesh/computer-use-linux/releases/download/$version/$asset.sha256"
+  sha256sum -c "$asset.sha256"
+  install -m 0755 "$asset" "$HOME/.local/bin/$binary"
+done
+```
+
+You will still need `ydotoold` running and AT-SPI enabled (run `computer-use-linux setup` and the systemd commands above).
+
+## Wire it into your MCP host
+
+The binary speaks the `rmcp` 2024-11-05 stdio protocol. Pass `mcp` as the only argument; everything else is configured through MCP tool calls.
+
+### Codex Desktop (Linux build)
+
+The Linux build of Codex Desktop already bundles this binary as a plugin. You don't need to wire it up manually — the plugin definition lives in [`codex-desktop-linux`](https://github.com/avifenesh/codex-desktop-linux) under its `plugins/` directory and is enabled by default. To upgrade the plugin in place, replace the binary it ships with the one from this repo's release assets.
+
+### Claude Desktop
+
+Edit `~/.config/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "computer-use-linux": {
+      "command": "computer-use-linux",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The 15 tools should appear in the tools list.
+
+### Hermes Agent
+
+If `computer-use-linux` is on your `PATH`, let Hermes discover it:
+
+```bash
+hermes mcp add computer-use-linux --command computer-use-linux --args mcp
+hermes mcp test computer-use-linux
+```
+
+Press Enter at the "Enable all tools?" prompt to expose all 15 tools. Hermes registers them as `mcp_computer_use_linux_<tool>` and creates the `mcp-computer-use-linux` runtime toolset.
+
+If you installed the binary somewhere that is not on `PATH`, pass the absolute path as `--command`.
+
+You can also edit `~/.hermes/config.yaml` directly:
+
+```yaml
+mcp_servers:
+  computer-use-linux:
+    command: computer-use-linux
+    args: ["mcp"]
+
+# Optional: expose the tools to subagents as well.
+inherit_mcp_toolsets: true
+```
+
+### Generic MCP client
+
+Spawn the binary with `["mcp"]` as the argv tail. It speaks JSON-RPC over stdio per the rmcp 2024-11-05 protocol; capability discovery happens through `tools/list` and the `doctor` tool. The server normally needs no MCP-specific configuration, but desktop runtime environment still matters (`DBUS_SESSION_BUS_ADDRESS`, `XDG_RUNTIME_DIR`, portals, AT-SPI, `ydotoold`, and optionally `COMPUTER_USE_LINUX_COSMIC_HELPER`).
+
+## First-run checklist
+
+1. **Run `doctor`.**
+
+   ```bash
+   computer-use-linux doctor | jq .readiness
+   ```
+
+   Aim for `can_register_mcp_tools`, `can_build_accessibility_tree`, `can_send_development_input`, and `can_query_windows` all `true`. The `blockers` array should be empty.
+
+2. **If `accessibility.at_spi_bus.ok = false`** — run `computer-use-linux setup` (or call the `setup_accessibility` MCP tool). This sets:
+   - `org.gnome.desktop.interface toolkit-accessibility true`
+
+   You may need to restart toolkit-using apps for the change to take effect.
+
+3. **If `windowing.can_list_windows = false`** — inspect `doctor.windowing.backends`. On GNOME Wayland, run `computer-use-linux setup-window-targeting` (or call `setup_window_targeting`) to install the bundled `computer-use-linux@avifenesh.dev` Shell extension, then log out and back in so GNOME Shell loads it. On KDE, Hyprland, i3, or COSMIC, install or expose the matching compositor tool/helper shown in the backend details.
+
+4. **Grant the screencast portal on first screenshot.** The first time `get_app_state` or any screenshot subcommand runs, GNOME will pop a portal dialog asking to share the screen. Accept once and tick "remember" to make it sticky for the session.
+
+5. **Confirm `ydotoold` is running.**
+
+   ```bash
+   systemctl --user status ydotoold
+   ```
+
+   Its socket should appear at `/run/user/$UID/.ydotool_socket`.
+
+## Architecture
+
+- **Accessibility tree** — [`atspi`](https://crates.io/crates/atspi) crate (tokio backend) talks to the AT-SPI registry on the user session bus. The tree is flattened to `(role, name, text, states, bounds)` tuples and indexed; element indices are stable for the duration of a `get_app_state` snapshot.
+- **DBus where desktops expose it** — [`zbus`](https://crates.io/crates/zbus) for portal calls (`org.freedesktop.portal.Screenshot`, `…RemoteDesktop`, `…ScreenCast`), GNOME Shell screenshots (`org.gnome.Shell.Screenshot`), the bundled GNOME extension's `dev.avifenesh.ComputerUseLinux.WindowControl` service, and temporary KWin scripting.
+- **MCP transport** — [`rmcp`](https://crates.io/crates/rmcp) with the `transport-io` feature; stdio framing, no network.
+- **Input fallback** — when the remote-desktop portal isn't available or the host wants deterministic injection, the binary writes to `ydotoold`'s socket, which writes to `/dev/uinput`. `install.sh` can configure `ydotoold`; the `setup` command only enables the GNOME AT-SPI bridge.
+- **Window registry** — `list_windows`, `focused_window`, `activate_window`, `press_key`, and `type_text` share a backend registry. It tries GNOME extension, GNOME Introspect, COSMIC helper, KWin scripting, Hyprland `hyprctl`, and i3 IPC in that order, skipping empty or failed backends so another compositor backend can answer.
+- **GNOME extension fallback** — recent GNOME builds deny `org.gnome.Shell.Introspect.GetWindows` to non-blessed clients. The bundled Shell extension exposes window data and exact activation under `dev.avifenesh.ComputerUseLinux.WindowControl`.
+- **COSMIC helper** — `computer-use-linux-cosmic` talks to COSMIC toplevel protocols and is resolved from `COMPUTER_USE_LINUX_COSMIC_HELPER`, next to the running binary, or from `PATH`.
+- **Terminal enrichment** — `list_windows` cross-references each terminal window with its controlling TTY and the foreground process on that TTY, so `type_text` / `press_key` can target "the terminal where `pytest` is running" without the host ever knowing the window id.
+
+## Security
+
+Computer-use tooling is, by definition, a privilege-escalation surface. The threat model:
+
+- **`ydotoold` runs as a per-user systemd service** with read/write access to `/dev/uinput`. Any process that can connect to its socket (`/run/user/$UID/.ydotool_socket`, mode `0600` by default) can synthesize arbitrary input — keypresses, clicks, anything. Keep the socket in the user runtime dir (the default), not in `/tmp` or any world-readable location. Do not run `ydotoold` as a system service.
+- **The screencast portal asks for permission once per session.** Granting it lets the calling MCP host capture the screen for the rest of the session. If you don't want that, decline the portal dialog and use `get_app_state` with `include_screenshot: false`.
+- **AT-SPI exposes window contents to any client on your session bus.** Enabling the AT-SPI bridge (`setup_accessibility`) is a prerequisite for this binary; it's also what screen readers use, and it shares the same trust boundary.
+- **The GNOME Shell extension** is loaded only into your user's GNOME Shell, runs in the Shell's JS sandbox, and exposes a single DBus interface on the user session bus. It does not request any extra permissions.
+- **No network.** This binary opens no TCP/UDP listener, makes no outbound Internet connections, and ships no telemetry. It does use local session transports such as DBus and the per-user `ydotoold` Unix socket.
+- **Mutating tools are explicit.** The MCP tool list annotates read-only versus mutating tools, and CI fails if the published tool annotations drift from the table above. Treat those annotations as hints; the host is still responsible for user approval and policy.
+
+If you're running this on a shared workstation, set `ydotoold`'s socket permissions to `0600` (the default) and audit which processes on your user can `connect()` to it.
+
+## Troubleshooting
+
+`computer-use-linux doctor` is the source of truth. Common failure modes and fixes:
+
+- **`accessibility.at_spi_bus.ok = false`** — AT-SPI registry isn't running or the toolkit bridge is off. Fix: `computer-use-linux setup` (or call the `setup_accessibility` MCP tool). Restart the apps you want to drive.
+- **`windowing.gnome_shell_introspect.ok = false` and `gnome_shell_extension_dbus.ok = false`** — GNOME blocks introspection and the extension isn't installed. Fix: `computer-use-linux setup-window-targeting`, then log out and log back in.
+- **`input.ydotool_socket.ok = false`** — daemon isn't running. Fix: `systemctl --user enable --now ydotoold`. If the unit doesn't exist, install the `ydotool` package and rerun `./install.sh` (or copy the unit from `systemd/ydotoold.service` in this repo).
+- **`input.uinput.ok = false`** — `/dev/uinput` isn't accessible to your user. Fix: add yourself to the `input` group (`sudo usermod -aG input $USER`) and re-login. On distros that ship `uinput` as a kernel module without auto-loading it, add `uinput` to `/etc/modules-load.d/`.
+- **Portal calls hang or time out** — `xdg-desktop-portal` or its backend (`-gnome`, `-gtk`, `-kde`, `-wlr`) crashed. Fix: check `journalctl --user -u xdg-desktop-portal -u xdg-desktop-portal-gnome --since '5 min ago'` and restart the relevant unit.
+- **KWin / Hyprland / i3 / COSMIC windowing is unavailable** — check `doctor.windowing.backends`. KWin needs session-bus scripting; Hyprland needs `hyprctl`; i3 needs `i3-msg` and its IPC socket. COSMIC needs `computer-use-linux-cosmic`, which the standard installers provide automatically; if you copied binaries by hand, copy the helper too or set `COMPUTER_USE_LINUX_COSMIC_HELPER`.
+- **Screenshots return black frames on multi-monitor setups** — known portal / compositor edge case. Use `get_app_state` with `include_screenshot: false` and rely on AT-SPI until the portal backend is healthy.
+- **`type_text` types into the wrong window** — pass an explicit target (`window_id`, `pid`, `wm_class`, `title`, or for terminals `tty` / `terminal_pid` / `terminal_command` / `terminal_cwd`). Without a target, input goes to whatever window currently has compositor focus.
+
+If `doctor` is green and a specific tool still misbehaves, file an issue with the JSON output of `doctor` and the failing tool's request payload.
+
+## Credits
+
+Extracted from [`codex-desktop-linux`](https://github.com/avifenesh/codex-desktop-linux), the Linux distribution of Codex Desktop, which continues to ship this same binary as a bundled plugin. Maintained by [Avi Fenesh](https://github.com/avifenesh).
+
+Built on top of:
+
+- [`atspi`](https://crates.io/crates/atspi) — AT-SPI bindings
+- [`zbus`](https://crates.io/crates/zbus) — async DBus
+- [`rmcp`](https://crates.io/crates/rmcp) — MCP runtime
+- [`ydotool`](https://github.com/ReimuNotMoe/ydotool) — Wayland-friendly uinput driver
+- [`cosmic-protocols`](https://crates.io/crates/cosmic-protocols) — COSMIC Wayland toplevel protocol bindings
+
+## Publishing
+
+Publishing is tag-driven from GitHub Actions. The repository needs these Actions secrets:
+
+```bash
+gh secret set CARGO_REGISTRY_TOKEN -R avifenesh/computer-use-linux
+gh secret set NPM_TOKEN -R avifenesh/computer-use-linux
+```
+
+Then bump `Cargo.toml` and `package.json` together, update `CHANGELOG.md`, and push a `vX.Y.Z` tag. CI runs the full Rust and MCP safety gates, builds release assets for both architectures, publishes `computer-use-linux` to crates.io, and publishes the npm wrapper after the GitHub release binaries are available.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/npm/README.md

@@ -0,0 +1,26 @@
+# computer-use-linux
+
+NPM wrapper for the `computer-use-linux` MCP server. Current release:
+[`@agent-sh/computer-use-linux@0.2.1`](https://www.npmjs.com/package/@agent-sh/computer-use-linux/v/0.2.1).
+
+Security note: this server can control the local Linux desktop. Tools such as
+`click`, `type_text`, `press_key`, `perform_action`, and `set_value` are
+mutating and can change real application state. The MCP tool list includes
+`ToolAnnotations` so hosts can distinguish read-only observation from mutating
+desktop actions.
+
+```bash
+npm install -g @agent-sh/computer-use-linux@0.2.1
+computer-use-linux doctor
+hermes mcp add computer-use-linux --command computer-use-linux --args mcp
+hermes mcp test computer-use-linux
+```
+
+The package downloads the matching Linux x86_64 or aarch64 binary from the
+GitHub release for this package version and verifies the `.sha256` asset before
+installing it. It also installs the matching `computer-use-linux-cosmic` helper
+used for COSMIC desktop window targeting.
+
+If you already built or installed the binary yourself, set
+`COMPUTER_USE_LINUX_BIN=/path/to/computer-use-linux` to make the wrapper use
+that executable instead.

package/npm/bin/computer-use-linux.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+const binaryName = `computer-use-linux-${process.platform}-${process.arch}`;
+const bundledBinary = path.join(__dirname, binaryName);
+const binary = process.env.COMPUTER_USE_LINUX_BIN || bundledBinary;
+const bundledCosmicHelper = path.join(__dirname, 'computer-use-linux-cosmic');
+
+if (!fs.existsSync(binary)) {
+  console.error(
+    [
+      `computer-use-linux binary not found: ${binary}`,
+      'Reinstall the package, run `npm rebuild computer-use-linux`, or set COMPUTER_USE_LINUX_BIN.',
+    ].join('\n')
+  );
+  process.exit(127);
+}
+
+const env = { ...process.env };
+if (!env.COMPUTER_USE_LINUX_COSMIC_HELPER && fs.existsSync(bundledCosmicHelper)) {
+  env.COMPUTER_USE_LINUX_COSMIC_HELPER = bundledCosmicHelper;
+}
+
+const child = spawn(binary, process.argv.slice(2), {
+  stdio: 'inherit',
+  env,
+});
+
+for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+  process.on(signal, () => {
+    if (!child.killed) {
+      child.kill(signal);
+    }
+  });
+}
+
+child.on('error', (error) => {
+  console.error(`failed to start computer-use-linux: ${error.message}`);
+  process.exit(127);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    const signalExitCodes = {
+      SIGHUP: 129,
+      SIGINT: 130,
+      SIGTERM: 143,
+    };
+    process.exit(signalExitCodes[signal] || 1);
+  }
+  process.exit(code ?? 1);
+});

package/npm/install.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const https = require('node:https');
+const os = require('node:os');
+const path = require('node:path');
+
+const pkg = require('../package.json');
+
+const archToTarget = {
+  x64: 'x86_64',
+  arm64: 'aarch64',
+};
+
+const binDir = path.join(__dirname, 'bin');
+const binaryPath = path.join(binDir, `computer-use-linux-${process.platform}-${process.arch}`);
+const cosmicHelperPath = path.join(binDir, 'computer-use-linux-cosmic');
+
+function fail(message) {
+  console.error(`[computer-use-linux] ${message}`);
+  process.exit(1);
+}
+
+function copyLocalBinary(source) {
+  fs.mkdirSync(binDir, { recursive: true });
+  fs.copyFileSync(source, binaryPath);
+  fs.chmodSync(binaryPath, 0o755);
+  if (process.env.COMPUTER_USE_LINUX_LOCAL_COSMIC_HELPER) {
+    fs.copyFileSync(process.env.COMPUTER_USE_LINUX_LOCAL_COSMIC_HELPER, cosmicHelperPath);
+    fs.chmodSync(cosmicHelperPath, 0o755);
+  }
+  console.log(`[computer-use-linux] installed local binary from ${source}`);
+}
+
+function download(url, destination, redirects = 5) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, (response) => {
+      if (
+        response.statusCode >= 300 &&
+        response.statusCode < 400 &&
+        response.headers.location &&
+        redirects > 0
+      ) {
+        response.resume();
+        const nextUrl = new URL(response.headers.location, url).toString();
+        download(nextUrl, destination, redirects - 1).then(resolve, reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`download failed with HTTP ${response.statusCode}: ${url}`));
+        return;
+      }
+
+      const file = fs.createWriteStream(destination, { mode: 0o600 });
+      response.pipe(file);
+      file.on('finish', () => file.close(resolve));
+      file.on('error', reject);
+    });
+    request.on('error', reject);
+  });
+}
+
+function parseSha256(text) {
+  const match = text.match(/\b[a-fA-F0-9]{64}\b/);
+  if (!match) {
+    throw new Error('sha256 file did not contain a 64-character hex digest');
+  }
+  return match[0].toLowerCase();
+}
+
+function sha256File(filePath) {
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(filePath));
+  return hash.digest('hex');
+}
+
+async function main() {
+  if (process.env.COMPUTER_USE_LINUX_SKIP_DOWNLOAD === '1') {
+    console.log('[computer-use-linux] skipping binary download');
+    return;
+  }
+
+  if (process.env.COMPUTER_USE_LINUX_LOCAL_BINARY) {
+    copyLocalBinary(process.env.COMPUTER_USE_LINUX_LOCAL_BINARY);
+    return;
+  }
+
+  if (process.platform !== 'linux') {
+    fail(`unsupported platform: ${process.platform}. This package only supports Linux.`);
+  }
+
+  const targetArch = archToTarget[process.arch];
+  if (!targetArch) {
+    fail(`unsupported CPU architecture: ${process.arch}. Supported: x64, arm64.`);
+  }
+
+  const asset = `computer-use-linux-${targetArch}-unknown-linux-gnu`;
+  const cosmicAsset = `computer-use-linux-cosmic-${targetArch}-unknown-linux-gnu`;
+  const baseUrl =
+    process.env.COMPUTER_USE_LINUX_DOWNLOAD_BASE ||
+    `https://github.com/avifenesh/computer-use-linux/releases/download/v${pkg.version}`;
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'computer-use-linux-'));
+  const tmpBinary = path.join(tmpDir, asset);
+  const tmpSha = path.join(tmpDir, `${asset}.sha256`);
+  const tmpCosmic = path.join(tmpDir, cosmicAsset);
+  const tmpCosmicSha = path.join(tmpDir, `${cosmicAsset}.sha256`);
+
+  try {
+    console.log(`[computer-use-linux] downloading ${asset} from ${baseUrl}`);
+    await download(`${baseUrl}/${asset}`, tmpBinary);
+    await download(`${baseUrl}/${asset}.sha256`, tmpSha);
+    await download(`${baseUrl}/${cosmicAsset}`, tmpCosmic);
+    await download(`${baseUrl}/${cosmicAsset}.sha256`, tmpCosmicSha);
+
+    const expected = parseSha256(fs.readFileSync(tmpSha, 'utf8'));
+    const actual = sha256File(tmpBinary);
+    if (actual !== expected) {
+      fail(`sha256 mismatch for ${asset}: expected ${expected}, got ${actual}`);
+    }
+
+    const expectedCosmic = parseSha256(fs.readFileSync(tmpCosmicSha, 'utf8'));
+    const actualCosmic = sha256File(tmpCosmic);
+    if (actualCosmic !== expectedCosmic) {
+      fail(`sha256 mismatch for ${cosmicAsset}: expected ${expectedCosmic}, got ${actualCosmic}`);
+    }
+
+    fs.mkdirSync(binDir, { recursive: true });
+    fs.copyFileSync(tmpBinary, binaryPath);
+    fs.chmodSync(binaryPath, 0o755);
+    fs.copyFileSync(tmpCosmic, cosmicHelperPath);
+    fs.chmodSync(cosmicHelperPath, 0o755);
+    console.log(`[computer-use-linux] installed ${asset} and ${cosmicAsset}`);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((error) => fail(error.message));

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@agent-sh/computer-use-linux",
+  "version": "0.2.1",
+  "description": "Linux desktop-control MCP server: AT-SPI accessibility trees, Wayland/X11 input, screenshots, and compositor window targeting.",
+  "license": "MIT",
+  "type": "commonjs",
+  "homepage": "https://github.com/avifenesh/computer-use-linux#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/avifenesh/computer-use-linux.git"
+  },
+  "bugs": {
+    "url": "https://github.com/avifenesh/computer-use-linux/issues"
+  },
+  "keywords": [
+    "mcp",
+    "computer-use",
+    "linux",
+    "wayland",
+    "accessibility",
+    "hermes-agent",
+    "codex"
+  ],
+  "os": [
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "bin": {
+    "computer-use-linux": "npm/bin/computer-use-linux.js"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "npm/README.md",
+    "npm/bin/computer-use-linux.js",
+    "npm/install.js"
+  ],
+  "scripts": {
+    "postinstall": "node npm/install.js",
+    "pack:check": "npm pack --dry-run",
+    "test:wrapper": "node npm/bin/computer-use-linux.js --help"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}