Is Peepbo open source?

Yes. MIT-licensed on GitHub at LichAmnesia/peepbo and on npm as `peepbo`.

Does Peepbo work on macOS or Windows?

No. Peepbo is Linux-only — it wraps Linux-specific tools (xdotool, scrot). For macOS use peekaboo; for Windows use Robot.js.

Does it support Wayland?

Partially. Screenshots work via gdbus + GNOME Screenshot portal. Mouse/keyboard automation under pure Wayland is restricted by design — use XWayland sessions for full functionality.

What is it built for?

Headless desktop automation: testing GUI apps, scripting repetitive tasks, capturing screenshots in CI, building AI agent computer-use tools on Linux.

How does it compare to xdotool directly?

Peepbo is a typed Node.js wrapper — better DX (async/await, types) than shelling out to xdotool from your scripts.

Can I use it in a Docker container?

Yes, with an X virtual framebuffer (Xvfb). Useful for GUI testing in CI.

Peepbo 🫣

A lightweight, Node.js + TypeScript automation tool for Linux. Control your mouse, keyboard, and screenshots programmatically.

View on GitHub View on NPM

See

Capture screenshots using scrot, gnome-screenshot, imagemagick, or gdbus for Wayland.

Click

Programmatically move the mouse and perform clicks using xdotool.

Type

Type text and press key combinations to interact with applications.

Linux Native

Optimized for Linux environments, supporting both X11 and Wayland (with configuration).

Installation

Install globally via npm:

npm install -g peepbo

Or verify requirements:

peepbo verify

Simple to Use

Capture Screenshot

peepbo image --output capture.png

Click Coordinates

peepbo click --x 500 --y 300

Type Text

peepbo type "Hello World"

Key Combinations

peepbo key "ctrl+c"

ALL TOOLS · THE CATALOG

34 single-purpose utilities · runs local

Browse all →

All tools process files entirely in your browser · Your data never leaves your device

Peepbo — Linux Automation in Node.js

Peepbo is an open-source Linux automation library. Drive the mouse, keyboard, and screen capture from Node.js or TypeScript scripts. Works with X11 and (with configuration) Wayland.

How to automate Linux desktop tasks with Peepbo

Install via npm. Run `npm install peepbo`. Peepbo wraps xdotool, scrot, and gnome-screenshot — install those system packages on Ubuntu / Arch / Fedora.
Capture screenshots. await peepbo.screenshot({ path: "out.png" }) — outputs a PNG of the current screen. Supports scrot, gnome-screenshot, ImageMagick, or gdbus on Wayland.
Move mouse and click. await peepbo.click({ x: 500, y: 300 }) — moves the cursor and clicks. Supports left, right, middle, double-click.
Type text or shortcuts. await peepbo.type("hello") or await peepbo.key("ctrl+s") — simulates keyboard input via xdotool.

Frequently Asked Questions

Is Peepbo open source?: Yes. MIT-licensed on GitHub at LichAmnesia/peepbo and on npm as `peepbo`.
Does Peepbo work on macOS or Windows?: No. Peepbo is Linux-only — it wraps Linux-specific tools (xdotool, scrot). For macOS use peekaboo; for Windows use Robot.js.
Does it support Wayland?: Partially. Screenshots work via gdbus + GNOME Screenshot portal. Mouse/keyboard automation under pure Wayland is restricted by design — use XWayland sessions for full functionality.
What is it built for?: Headless desktop automation: testing GUI apps, scripting repetitive tasks, capturing screenshots in CI, building AI agent computer-use tools on Linux.
How does it compare to xdotool directly?: Peepbo is a typed Node.js wrapper — better DX (async/await, types) than shelling out to xdotool from your scripts.
Can I use it in a Docker container?: Yes, with an X virtual framebuffer (Xvfb). Useful for GUI testing in CI.

Use Cases

Build a Linux desktop AI agent (computer-use) in Node.js
Automate repetitive GUI tasks on a Linux workstation
Capture screenshots in CI for visual regression testing
Script GUI app testing on Ubuntu / Fedora / Arch
Build a Linux equivalent of peekaboo for AI coding workflows