Configuration

Configuration controls browser access, strict accessibility execution, and the macOS agent cursor.

Files

Global config:

~/.pi/agent/extensions/pi-computer-use.json

Project config:

.pi/computer-use.json

Project config overrides global config. Environment variables override both.

Example:

{
  "browser_use": true,
  "managed_browser": "chrome",
  "headless": false,
  "cursor_overlay": true
}

Run /computer-use in Pi to show the active config and its source.

Options

browser_use

Default: true

When false, the extension refuses known browser windows. This is useful for projects that should not control browsers.

Known browser families include Safari, Chrome and Chromium-family browsers, Firefox, Arc, Brave, Edge, Vivaldi, and Helium.

managed_browser

Default: "chrome"

Selects "helium" or "chrome" for launch_browser. The debugging port is always allocated internally and isn't part of the model-facing contract.

headless

Default: false

When true, actions must remain in the background. Raw pointer events, raw keyboard events, foreground focus fallback, cursor takeover, and the agent cursor overlay are blocked. When false (the default), Pi prefers verified semantic activation when it is credible, preserves the focus established by editable clicks for dependent keyboard input, and may retry keyboard input in the foreground when a background attempt conclusively produced no value change. Ambiguous pointer actions are never replayed blindly.

cursor_overlay

Default: true

When true, macOS pointer actions enqueue a click-through agent cursor animation to the native grounded point during non-headless background delivery. Foreground actions that control the physical cursor don't display the overlay. The overlay doesn't move the system pointer, accept input, or delay the action. Set it to false for invisible automation. headless: true always suppresses it regardless of this setting.

Environment variables

PI_COMPUTER_USE_BROWSER_USE=0
PI_COMPUTER_USE_BROWSER_USE=1
PI_COMPUTER_USE_MANAGED_BROWSER=helium
PI_COMPUTER_USE_MANAGED_BROWSER=chrome
PI_COMPUTER_USE_HEADLESS=0
PI_COMPUTER_USE_HEADLESS=1
PI_COMPUTER_USE_CURSOR_OVERLAY=0
PI_COMPUTER_USE_CURSOR_OVERLAY=1
PI_COMPUTER_USE_DELIVERY_POLICY=default
PI_COMPUTER_USE_DELIVERY_POLICY=foreground
PI_COMPUTER_USE_CDP_PORT=9222

PI_COMPUTER_USE_HEADLESS=1 prohibits foreground fallback. PI_COMPUTER_USE_DELIVERY_POLICY is a debugging input; normal policy belongs in configuration rather than individual model calls.

CDP browser support

PI_COMPUTER_USE_CDP_PORT enables Chrome DevTools Protocol support for Chromium-family browsers. Launch the browser with --remote-debugging-port=<port> and set this variable to the same port.

When CDP is active, discovered pages participate in the same root and state system as desktop UI. launch_browser configures CDP automatically and returns an observed page state. navigate_browser and evaluate_browser accept only CDP browser-page states; native browser windows continue to use the normal desktop observe/act tools.

With the variable unset, CDP is inactive.