testsAndMisc/robotgo_demo/.github/copilot-instructions.md

Copilot Instructions for robotgo_demo

Overview

robotgo_demo/ is a Go project using go-vgo/robotgo for desktop automation on Arch Linux, X11, i3 window manager. Robotgo provides cross-platform control of mouse, keyboard, screen, clipboard, and window management.

System Requirements (Arch Linux / X11)

All dependencies must be installed before building:

sudo pacman -S --needed gcc go libxtst libx11 libxkbcommon libxkbcommon-x11 \
    libpng xsel xclip libxcb

These provide:

• GCC + Go — compiler toolchain (robotgo uses cgo)
• libxtst, libx11, libxcb — X11 display and XTest extension
• libxkbcommon, libxkbcommon-x11 — keyboard hook support (gohook)
• libpng — bitmap/screenshot capture
• xsel, xclip — clipboard read/write

Build & Run

cd robotgo_demo
go build -o robotgo_demo .
./robotgo_demo

To update the dependency:

go get -u github.com/go-vgo/robotgo
go mod tidy

Robotgo API Quick Reference

Use import "github.com/go-vgo/robotgo" in Go files. Key APIs:

Mouse

robotgo.Move(x, y)              // instant move
robotgo.MoveSmooth(x, y)        // human-like smooth move
robotgo.Click("left")           // click (left/right/center)
robotgo.DragSmooth(x, y)        // drag to position
robotgo.ScrollDir(n, "up")      // scroll direction
x, y := robotgo.Location()      // current mouse position

Keyboard

robotgo.Type("text")              // type a string
robotgo.KeyTap("enter")          // tap a single key
robotgo.KeyTap("a", "ctrl")      // key combo (ctrl+a)
robotgo.KeyToggle("shift")       // hold key down
robotgo.KeyToggle("shift", "up") // release key

Screen

sx, sy := robotgo.GetScreenSize()        // screen dimensions
color := robotgo.GetPixelColor(x, y)     // hex color at pixel
bit := robotgo.CaptureScreen(x, y, w, h) // capture region
defer robotgo.FreeBitmap(bit)            // always free bitmaps
img := robotgo.ToImage(bit)              // convert to Go image

Clipboard

robotgo.WriteAll("text")         // write to clipboard
text, err := robotgo.ReadAll()   // read from clipboard

Window

title := robotgo.GetTitle()               // active window title
pids, err := robotgo.FindIds("firefox")   // find PIDs by name
robotgo.ActivePid(pid)                    // focus window by PID
robotgo.ActiveName("firefox")             // focus window by name

Event Hooks (via gohook)

import hook "github.com/robotn/gohook"

hook.Register(hook.KeyDown, []string{"q", "ctrl"}, func(e hook.Event) {
    hook.End()
})
s := hook.Start()
<-hook.Process(s)

Timing

robotgo.Sleep(1)              // sleep 1 second
robotgo.MilliSleep(500)       // sleep 500ms
robotgo.MouseSleep = 300      // default delay between mouse ops
robotgo.KeySleep = 100        // default delay between key ops

Key Docs & Links

• Full API docs
• Key name reference
• Examples
• GoDoc

Conventions

• Always defer robotgo.FreeBitmap(bit) after CaptureScreen to avoid memory leaks.
• Use MoveSmooth over Move when simulating human interaction.
• Add time.Sleep or robotgo.MilliSleep before typing to give the user time to focus the target window.
• Robotgo operates on X11 only — this project does not support Wayland.
• The compiled binary is git-ignored; always build from source.

Gotchas

• cgo required: robotgo uses C bindings. CGO_ENABLED=1 must be set (it's the default on native builds).
• X11 only: will not work under Wayland. Ensure $DISPLAY is set.
• Root not needed: runs as a regular user with X11 access.
• Bitmap capture may fail if no X display is available (e.g., headless/SSH without X forwarding).
• png.h: No such file or directory: install libpng (sudo pacman -S libpng).

Project Structure

robotgo_demo/
├── .gitignore      # ignores compiled binary
├── go.mod          # Go module (robotgo_demo)
├── go.sum          # dependency checksums
├── main.go         # demo: mouse, keyboard, screen, clipboard, window
└── README.md       # user-facing docs