peepbo

Peepbo 🫣

Peepbo is a lightweight, Node.js + TypeScript automation tool for Linux, inspired by Peekaboo. It allows you to programmatically control your mouse, keyboard, and window focus, as well as capture screenshots, making it ideal for building AI agents that interact with the Linux desktop.

Features

• 👀 See: Capture screenshots (scrot, gnome-screenshot, imagemagick, or gdbus for Wayland).
• point_up Click: Move mouse and click (xdotool).
• keyboard Type: Type text and press key combinations.
• window Window Management: Focus and query active windows.
• TypeScript: Fully typed for safety.

Requirements

Peepbo relies on standard Linux automation tools. You can check for them using the built-in verify command:

peepbo verify

Typically, you will need:

• xdotool (for automation)
• libglib2.0-bin (for gdbus screenshots on GNOME Wayland)
• scrot or imagemagick (fallback for X11 screenshots)

Installation

From npm (Recommended)

npm install -g peepbo

From Source

# Clone the repository
git clone https://github.com/LichAmnesia/peepbo.git
cd peepbo

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (optional)
npm link

Usage

You can run Peepbo directly via node:

# Link for global usage (optional)
npm link

# Capture a screenshot
peepbo image --output capture.png

# Click at specific coordinates
peepbo click --x 500 --y 300

# Type text
peepbo type "Hello World"

# Press a key combo
peepbo key "ctrl+c"

# Focus a window
peepbo window focus "Code"

Troubleshooting: Wayland & Black Screenshots

On modern Linux distributions (like Ubuntu 24.04/25.10) using Wayland, you might encounter completely black screenshots. Peepbo handles this via GNOME's D-Bus API, but it requires GNOME to be in "Unsafe Mode" to allow external script interaction.

⚠️ Hardcore Solution: Enabling "Unsafe Mode"

Enabling Unsafe Mode allows external processes to interact with GNOME Shell internals. This is powerful for automation but bypasses some default security sandboxing.

• Open Looking Glass: Press Alt + F2, type lg, and hit Enter.
• Execute Command: In the console that appears, type the following and press Enter:

  global.context.unsafe_mode = true
  

• Exit: Press Esc to close the console.

Note: This setting resets on logout/reboot. If you prefer not to use this, consider switching to an X11 (Xorg) session from the login screen.

Documentation

• Tool Reference: Detailed guide to all CLI commands.
• Agent Patterns: Best practices for AI agents using Peepbo.

Development

# Watch mode for development
npm run build -- --watch

License

ISC