---
name: pi-setup
description: "Pi coding agent setup for native computer-use-linux tools."
---

# Pi Setup

## Install

Install one package:

```bash
pi install npm:@agent-sh/computer-use-linux
```

Restart Pi or run `/reload`. No separate MCP adapter or MCP configuration is
required. This does not put `computer-use-linux` on `PATH`. For shell `doctor`,
`setup`, or MCP hosts, also install the CLI with
`npm install -g @agent-sh/computer-use-linux` or
`cargo install computer-use-linux`.

The integration is designed for current Pi releases with additive dynamic tool
loading. Update Pi and installed packages when needed:

```bash
pi update --all
```

## How tool loading works

Pi initially sees one small loader:

```text
computer_use_linux_tools
```

Enable exact tools:

```text
computer_use_linux_tools({ tools: ["doctor", "list_windows"] })
```

Or search by capability:

```text
computer_use_linux_tools({ query: "inspect a window and type text" })
```

Called with no arguments, the loader enables `doctor`, `list_windows`,
`focused_window`, `get_app_state` and `get_tree_page`.

The selected native tools appear starting on the next model turn with their
full upstream schemas and remain active for the session:

```text
computer_use_linux_doctor({})
computer_use_linux_list_windows({})
computer_use_linux_type_text({ text: "hello", title: "Notes" })
```

Pi does not start the desktop process when the loader runs. The first real tool
call starts one computer-use-linux process, and the package reuses it for the
session so `get_app_state` element indices and portal sessions remain valid.

Codemode scripts receive `{ text, images, isError }`. Each image is an MCP image
block that can be passed directly to `image()`:

```js
const result = await tools.computer_use_linux_screenshot({});
if (result.isError) throw new Error(result.text);
text(result.text);
for (const block of result.images) image(block);
```

## Safe operating loop

1. Enable `get_app_state`, `list_windows`, and any likely action tools.
2. Call `computer_use_linux_get_app_state` scoped to the target app
   (`app_name_or_bundle_identifier`, or `window_id`/`pid`/`app_id`/`wm_class`/
   `title`), using `include_screenshot: false` when accessibility data is
   enough. An unscoped call returns the whole desktop tree, reports
   `tree_scoped: false`, and warns; that can exhaust a small context window.
3. Inspect the returned readiness block; enable/call `doctor` only for full
   diagnostics.
4. Identify the target with `computer_use_linux_list_windows` or
   `computer_use_linux_focused_window`.
5. Enable and call the required action tool.
6. Re-observe after the UI changes.

Native Computer Use tools execute sequentially. Cancellation is forwarded to
the MCP request. If the server process exits, the failed call is never replayed
automatically; call `get_app_state` again before another element-based action.
Each call times out after 60 seconds. Set `COMPUTER_USE_LINUX_TIMEOUT_MS` in
Pi's environment to change it, for example for `run_shell` calls with
`timeout_seconds` above 60.

## Migration from the adapter-based package

Older releases required `pi-mcp-adapter` and wrote a
`computer-use-linux` entry into `mcp.json` under the configured Pi agent
directory.

The native integration does not write MCP configuration. It reads only the
legacy entry location to show a migration notice. After updating:

1. Remove only the `computer-use-linux` entry from the Pi agent `mcp.json` if
   it is still present.
2. Keep `pi-mcp-adapter` if you use it for other MCP servers; otherwise remove
   it with `pi remove npm:pi-mcp-adapter`.
3. Run `/reload`.

The package reports a non-destructive migration notice when it detects the
legacy entry.

## If the binary is not found

The extension looks for `computer-use-linux` in this order:

1. `COMPUTER_USE_LINUX_BIN`, when it is an absolute path to an executable. A
   relative or non-executable value is ignored and the next step is used.
2. The binary downloaded inside the installed npm package. When it is missing,
   as after npm 12 skipped the install script, the first real tool call runs the
   package's `npm/install.js` to download it.
3. `computer-use-linux` on `PATH`, from `npm install -g` or `cargo install`,
   when that download fails

The extension still checks that the server version and tool catalog match, so
a mismatched install fails with that reason instead of starting. Set
`COMPUTER_USE_LINUX_BIN` to run a `PATH` or development build instead of the
download.

Reinstall the package if the bundled binary is missing:

```bash
pi remove npm:@agent-sh/computer-use-linux
pi install npm:@agent-sh/computer-use-linux
```

Users with a separate build can set:

```bash
export COMPUTER_USE_LINUX_BIN=/absolute/path/to/computer-use-linux
```

## Verification

Enable and call the readiness tool:

```text
computer_use_linux_tools({ tools: ["doctor"] })
computer_use_linux_doctor({})
```

Ready output has:

- `can_register_mcp_tools: true`
- `can_build_accessibility_tree: true`
- `can_query_windows: true`
- `can_send_development_input: true`
- `screenshot_capture_status: "unverified"`
- `can_capture_screenshots: false`
- `blockers: []`

Doctor detects screenshot routes without capturing or requesting consent. Treat unverified capture as a warning. Call `get_app_state` with `include_screenshot: true` to verify it: a successful raw capture reports `screenshot_capture_status: "verified"` and `can_capture_screenshots: true`; a failure reports `failed` and keeps the boolean false. Inspect `screenshot_error` for the full backend cause.