# Peepbo 🫣

**Peepbo** is a lightweight, Node.js + TypeScript automation tool for Linux, inspired by [Peekaboo](https://github.com/steipete/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.

![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
![Node](https://img.shields.io/badge/node-%3E%3D16-green.svg)
![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)

## 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:

```bash
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)

```bash
npm install -g peepbo
```

### From Source

```bash
# 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`:

```bash
# 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.

1.  **Open Looking Glass**: Press `Alt + F2`, type `lg`, and hit `Enter`.
2.  **Execute Command**: In the console that appears, type the following and press `Enter`:
    ```javascript
    global.context.unsafe_mode = true
    ```
3.  **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**](docs/tools.md): Detailed guide to all CLI commands.
*   [**Agent Patterns**](docs/agent-patterns.md): Best practices for AI agents using Peepbo.

## Development

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

## License

ISC