Peepbo
Peekaboo for Linux — screenshot, mouse, keyboard & window automation for desktop AI agents.
Peepbo is a lightweight Node.js + TypeScript automation tool for Linux, inspired by Peekaboo on macOS. Capture screenshots (X11 and Wayland), control mouse and keyboard, and manage window focus — the building blocks for AI agents that drive the Linux desktop.
What is Peepbo?
Peepbo is a lightweight Node.js + TypeScript desktop-automation tool for Linux, inspired by macOS's Peekaboo, that lets you programmatically control the mouse, keyboard, and window focus and capture screenshots — making it suited for building AI agents that interact with the Linux desktop. It captures screens via scrot, gnome-screenshot, imagemagick, or gdbus (for GNOME Wayland), drives input through xdotool, installs globally via npm (npm install -g peepbo), and ships a CLI with commands like image, click, type, key, window focus, and a verify command that checks required system dependencies.
Key features
- Screenshot capture on X11 and Wayland: scrot, gnome-screenshot, or imagemagick on X11, and GNOME's D-Bus API via gdbus on Wayland
- Mouse control via xdotool: move and click at specific coordinates (peepbo click --x 500 --y 300)
- Keyboard automation: type text (peepbo type "Hello World") and press key combos (peepbo key "ctrl+c")
- Window management: focus and query active windows (peepbo window focus "Code")
- Fully typed TypeScript codebase; requires Node >= 16
- Built-in dependency checker: peepbo verify reports whether xdotool, libglib2.0-bin (gdbus), and scrot/imagemagick are installed
- Install from npm (npm install -g peepbo) or build from source (npm install && npm run build && npm link)
- Documented Wayland black-screenshot workaround: enable GNOME "Unsafe Mode" via Looking Glass, or switch to an X11 session; docs include a Tool Reference and Agent Patterns guide
Who it's for
- Developers building AI agents that need to see and act on a Linux desktop (screenshot + click + type loop)
- Node.js/TypeScript teams who want Linux desktop automation without leaving the npm ecosystem
- Users of Peekaboo on macOS who need an equivalent workflow on Linux machines
- Scripted UI testing or repetitive desktop task automation on X11 or GNOME Wayland sessions
When not to use it
Peepbo is Linux-only — on macOS use Peekaboo, its inspiration, instead. On Wayland it depends on GNOME's D-Bus API and may require enabling GNOME "Unsafe Mode" (which bypasses some default security sandboxing and resets on logout), so environments that can't accept that trade-off should use an X11 (Xorg) session or another tool.
FAQ
Does Peepbo work on Wayland?
Yes, via GNOME's D-Bus API (gdbus). But on modern distros (e.g. Ubuntu 24.04/25.10) screenshots can come out black unless GNOME is put in "Unsafe Mode" (Alt+F2 → lg → global.context.unsafe_mode = true), which resets on logout. Alternatively, switch to an X11 session.
What system dependencies does Peepbo need?
xdotool for mouse/keyboard automation, libglib2.0-bin for gdbus screenshots on GNOME Wayland, and scrot or imagemagick as X11 screenshot fallbacks. Run `peepbo verify` to check what's installed. Node >= 16 is required.
How do I install Peepbo?
From npm: `npm install -g peepbo`. Or from source: clone github.com/LichAmnesia/peepbo, then `npm install`, `npm run build`, and optionally `npm link` for global usage.
How is Peepbo different from Peekaboo?
Peepbo is inspired by Peekaboo but targets Linux instead of macOS, and is built in Node.js + TypeScript. It wraps Linux tooling (xdotool, scrot, gdbus) to provide screenshots, clicks, typing, and window focus for AI agents.
What CLI commands does Peepbo provide?
peepbo image --output capture.png (screenshot), peepbo click --x/--y (mouse), peepbo type "text", peepbo key "ctrl+c" (key combos), peepbo window focus "Code", and peepbo verify (dependency check). A full Tool Reference lives in docs/tools.md.
Share this launch
Embed this badge
<a href="https://orangebot.ai/product/peepbo" target="_blank" rel="noopener noreferrer"> <img src="https://orangebot.ai/api/badge/peepbo.svg" alt="Featured on OrangeBot" width="200" height="54" /> </a>