If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/go-vgo/robotgo shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 3w ago
• 4 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 93% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live go-vgo/robotgo repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/go-vgo/robotgo.

What it runs against: a local clone of go-vgo/robotgo — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in go-vgo/robotgo | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 50 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of go-vgo/robotgo. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/go-vgo/robotgo.git
#   cd robotgo
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of go-vgo/robotgo and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "go-vgo/robotgo(\\.git)?\\b" \\
  && ok "origin remote is go-vgo/robotgo" \\
  || miss "origin remote is not go-vgo/robotgo (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "robotgo.go" \\
  && ok "robotgo.go" \\
  || miss "missing critical file: robotgo.go"
test -f "mouse/mouse.go" \\
  && ok "mouse/mouse.go" \\
  || miss "missing critical file: mouse/mouse.go"
test -f "key.go" \\
  && ok "key.go" \\
  || miss "missing critical file: key.go"
test -f "screen.go" \\
  && ok "screen.go" \\
  || miss "missing critical file: screen.go"
test -f "base/base.go" \\
  && ok "base/base.go" \\
  || miss "missing critical file: base/base.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 50 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~20d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/go-vgo/robotgo"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

RobotGo is a Go library for cross-platform desktop automation and GUI control that enables mouse/keyboard input, screen reading, window management, and global event listening on macOS, Windows, and Linux (X11). It provides native bindings to OS-level input/output APIs, making it suitable for RPA (Robotic Process Automation), automated testing, and AI-driven computer use applications. Monorepo with platform-specific packages: clipboard/ (cross-platform clipboard), cv/ (computer vision with gosseract), event/ (global event listening), base/ (C headers and OS detection), plus root-level Go files wrapping mouse/keyboard/screen APIs. Core Go wraps C FFI headers (base/*.h) that vary per-OS; each OS family (darwin, unix/linux, windows) has dedicated files and conditional compilation.

Go developers building automation tools, test frameworks, and AI agents who need programmatic control of desktop environments without platform-specific reimplementation. Also used by QA engineers automating GUI testing and by robotics/RPA solution architects targeting multiple operating systems.

Actively maintained with solid CI/CD setup (CircleCI, GitHub Actions), recent Go 1.25.0 support, and multi-platform coverage (macOS/Windows/Linux on arm64 and x86-amd64). High-quality upstream (vcaesar ecosystem) and clear documentation structure, though main repo shows focused, incremental development rather than rapid feature velocity—production-ready for established use cases.

Single primary maintainer (vcaesar) creates concentration risk; dependency chain includes specialized libs (xgb for X11, gosseract for OCR, win API wrappers) with varying update cadences. macOS privacy settings (Screen Recording, Accessibility) are hard requirements that can break silently in CI/sandboxed environments. C FFI bindings (72K LOC) introduce platform-specific compilation complexity and potential ABI incompatibilities across OS versions.

Recent activity includes Go 1.25.0 version bump, dependency updates (tailscale/win, vcaesar ecosystem libs), and likely Wayland support development (mentioned in README as pro/commercial feature). CircleCI and GitHub Actions workflows actively run tests across platforms; issue template and PR template suggest standard contribution process.

git clone https://github.com/go-vgo/robotgo.git
cd robotgo
# Install Golang and GCC first
# macOS: brew install go, then install Xcode Command Line Tools
# Linux: apt-get install golang gcc build-essential libx11-dev
# Windows: choco install golang gcc or download installers
go get github.com/go-vgo/robotgo
go test ./...

Daily commands:

# No server—library usage in your own Go code
go get github.com/go-vgo/robotgo
# Example: create main.go with mouse.Move(100, 100) and keyboard.Type("hello")
go run main.go
# For CLI tools, see clipboard/cmd/gocopy and clipboard/cmd/gopaste
cd clipboard/cmd/gocopy && go build

• robotgo.go — Main entry point and API surface for the entire library; defines core functions like MoveMouse, Click, TypeStr, and KeyPress that all users depend on.
• mouse/mouse.go — Cross-platform mouse abstraction layer that dispatches to platform-specific implementations; critical for mouse automation.
• key.go — High-level key simulation API; integrates with platform-specific keypress implementations used by most automation scripts.
• screen.go — Screen capture and image retrieval API; foundational for visual automation and image recognition workflows.
• base/base.go — C-interop layer and low-level utilities; handles CGO bindings for platform-specific native libraries.
• go.mod — Dependency manifest showing critical native dependencies (vcaesar/screenshot, vcaesar/keycode, jezek/xgb) required for cross-platform automation.
• robotgo_x11.go — Linux/X11 platform-specific implementations; required entry point for all Unix-like system automation features.

Add a new mouse automation function

1. Add high-level function signature to robotgo.go (e.g., func MouseDoubleClick(x, y int32)) (robotgo.go)
2. Implement cross-platform wrapper in mouse/mouse.go that dispatches to OS-specific code (mouse/mouse.go)
3. Implement Windows version using Win32 API or tailscale/win (robotgo_win.go)
4. Implement macOS version using Core Graphics CGEvent (robotgo_mac.go)
5. Implement Linux version using X11 XTest extension via jezek/xgb (robotgo_x11.go)
6. Add example usage in examples/mouse/main.go (examples/mouse/main.go)

Add a new keyboard function

1. Add public API to key.go (e.g., func ModifierKey(modifiers []string)) (key.go)
2. Define keycode mappings in key/keycode.h or extend keycode.go (keycode.go)
3. Implement Windows keypress dispatch in robotgo_win.go or key/key_windows.go (robotgo_win.go)
4. Implement macOS keypress in robotgo_mac.go using CGEventCreateKeyboardEvent (robotgo_mac.go)
5. Implement X11 keypress in robotgo_x11.go using XTestFakeKeyEvent (robotgo_x11.go)

Add a new vision/OCR feature

1. Create or extend robotgo_ocr.go with OCR-related functions using gosseract/v2 (robotgo_ocr.go)
2. Optionally extend cv/gocv.go for image matching and template detection (cv/gocv.go)
3. Integrate with screen.go to capture region-specific images before processing (screen.go)
4. Add integration example in examples/screen/main.go or new example file (examples/screen/main.go)

• Go + CGO — Provides cross-platform high-performance access to native OS automation APIs while maintaining Go's simplicity; CGO bridges Go to C/platform libraries.
• Windows: Win32 API via tailscale/win — Direct access to Windows mouse/keyboard events through SetCursorPos, mouse_event, keybd_event without wrappers.
• macOS: Core Graphics (Quartz Events) — Apple's native event framework for mouse/keyboard automation; no third-party GUI automation frameworks needed.
• Linux: X11 XTest Extension — Standard X11 mechanism for synthetic input; accessed via jezek/xgb and xgbutil for X server communication.
• gosseract/v2 (Tesseract OCR) — Industry-standard open-source OCR for text recognition in captured images; enables vision-based automation.
• vcaesar/screenshot — Optimized cross-platform screenshot capture that RobotGo wraps; faster than alternatives.

• Separate platform-specific files (robotgo_win.go, robotgo_mac.go, robotgo_x11.go) instead of build tags everywhere

  • Why: Cleaner readability and reduces conditional compilation complexity; each file clearly targets one OS.
  • Consequence: More files to maintain but easier to understand platform-specific logic; CI must test each platform separately.

• CGO bindings instead of pure Go native libraries

  • Why: Access to low-level OS APIs not exposed by Go stdlib; necessary for real-time mouse/keyboard control at OS level.
  • Consequence: Requires C compiler to build; adds dependency on system libraries; slightly slower startup due to CGO overhead.

• Synchronous blocking API (MoveMouse waits until complete) rather than async/channel-based

  • Why: Matches user expectations for RPA/automation workflows where sequential steps must block until done.
  • Consequence: Simpler mental model for users but can block goroutines; users must manage concurrency themselves.

• Platform detection at runtime via conditionally compiled code rather than interface-based abstraction

  • Why: Minimal runtime overhead; compile-time safety ensures correct platform code is included.
  • Consequence: Code must be tested on each platform; cannot hot-swap implementations at runtime.

• Web-based automation (not a Selenium alternative; targets native desktop applications only)
• Real-time collaborative automation (no multi-user session support)
• Permanent record/audit logs of automation actions
• Visual feedback UI or dashboard for automation execution
• iOS automation (event/ios directories are stubs; focus is Windows, macOS, Linux, Android)

macOS sandbox: requires Screen Recording + Accessibility privacy grants before any screen/input operations work; CI/headless tests will fail silently without proper entitlements. X11 display: Linux requires DISPLAY env var set and X server running (wayland untested in open-source version per README). CGO complexity: on Windows, specific MSVC/MinGW toolchain versions may be needed; macOS Xcode Command Line Tools version mismatches can break linking. Global event listener: event/ package may require elevated privileges on some Linux distros. Screenshot/cv dependencies: gosseract needs tesseract library installed separately (not auto-vendored).

• CGO Foreign Function Interface (FFI) — RobotGo's entire architecture hinges on calling C/Objective-C APIs via cgo; understanding how Go pointers map to C memory and how build tags isolate platform code is essential to debugging crashes and adding features.
• Platform-Specific Build Tags — The codebase uses //go:build darwin, //go:build windows, //go:build linux to conditionally compile entirely different implementations; misunderstanding tag precedence or forgetting stubs on one OS is a common contributor mistake.
• Global Event Listener (IPC/Message Pumps) — The event/ package must hook into OS-level input event streams (Windows message queue, X11 event socket, Quartz Event Tap on macOS), requiring non-blocking loop design and careful cleanup—critical for automation tools that react to keyboard/mouse in real time.
• Bitmap/Raster Graphics Manipulation — RobotGo captures raw pixel buffers (MMBitmap) for screen reading and image matching; understanding color space conversions (RGB vs BGRA), stride/pitch in memory layout, and bitmap serialization is necessary for reliable visual recognition.
• X11 Protocol and XGb Library — Linux support relies on X11 wire protocol via xgb (pure Go X11 client); X11's asynchronous request/response model and atom-based window property system are conceptually different from native Windows/macOS APIs and common source of Linux-only bugs.
• Optical Character Recognition (OCR) Integration — The cv/ package wraps gosseract (Tesseract binding) for screen text extraction; RPA workflows that identify UI by text rely on OCR accuracy, language packs, and preprocessing; critical for AI agent automation.
• Accessibility API Privileges — macOS and modern Windows require Accessibility/UIAutomation permission to hook input/events; understanding sandbox entitlements, codesigning, and privacy prompts prevents silent permission denials in production.

• go-echarts/go-echarts — Different domain, but similar cross-platform Go-native binding philosophy; useful for visualizing automation metrics
• vcaesar/gops — Sister project in vcaesar ecosystem; provides process/system introspection that pairs with robotgo for target window selection
• vcaesar/screenshot — Core dependency of robotgo; handles low-level bitmap capture and is separately maintained for reuse
• go-vgo/gospider — Companion project for web scraping; often used with robotgo for hybrid browser automation + native GUI control
• vcaesar/codg — Modern AI agent framework built on top of robotgo; shows production RPA usage and long-term direction of vcaesar ecosystem

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for clipboard package

The clipboard package (clipboard/*.go) has platform-specific implementations (clipboard_darwin.go, clipboard_unix.go, clipboard_windows.go) but clipboard_test.go appears minimal. RobotGo is a cross-platform automation library, so clipboard operations are critical. Adding platform-specific test coverage would catch regressions and ensure consistency across macOS, Linux, and Windows.

• [ ] Review clipboard_test.go and identify missing test cases for Read/Write operations
• [ ] Add platform-specific tests for clipboard_darwin.go (macOS pasteboard)
• [ ] Add platform-specific tests for clipboard_unix.go (X11/Wayland clipboard)
• [ ] Add platform-specific tests for clipboard_windows.go (Windows clipboard APIs)
• [ ] Ensure tests validate empty clipboard, special characters, and large data handling
• [ ] Update .github/workflows/go.yml if needed to run tests on all platforms

Add integration tests for cross-platform mouse and keyboard events

The event package has platform-specific subdirectories (event/android, event/ios) with C headers, suggesting platform-specific event handling. However, there are no visible test files in the event package. Given RobotGo's core purpose (GUI automation and computer use), comprehensive event testing is critical to prevent platform-specific regressions in mouse clicks, keyboard input, and event sequencing.

• [ ] Create event/event_test.go for platform-agnostic event behavior tests
• [ ] Create event/event_darwin_test.go for macOS-specific event handling validation
• [ ] Create event/event_linux_test.go for Linux X11/Wayland event validation
• [ ] Create event/event_windows_test.go for Windows event API validation
• [ ] Add tests for mouse click sequences, keyboard modifier combinations, and timing
• [ ] Document any environment setup needed (e.g., X11 display, accessibility permissions)

Add missing documentation and examples for cv (computer vision) module

The cv package directory (cv/gocv.go and cv/README.md) exists but has minimal visible documentation compared to other modules. The go.mod shows dependencies on image processing (golang.org/x/image, github.com/vcaesar/imgo) suggesting image analysis capabilities. New contributors would benefit from concrete examples of image detection, screenshot analysis, and pattern matching workflows.

• [ ] Review cv/gocv.go to document exported functions and their parameters
• [ ] Create examples/vision/main.go demonstrating image detection workflow
• [ ] Create examples/pattern_match/main.go showing pattern matching on screenshots
• [ ] Add cv/cv_test.go with unit tests for image processing functions
• [ ] Update cv/README.md with code examples and use cases (e.g., OCR with gosseract, template matching)
• [ ] Document integration with github.com/otiai10/gosseract/v2 for OCR functionality

• Add missing unit tests for Windows-specific clipboard operations in clipboard/clipboard_windows.go—currently only Darwin/Unix tests exist in clipboard_test.go, creating platform coverage gap.
• Document X11 DISPLAY and XDG_RUNTIME_DIR environment requirements in docs/install.md with Linux setup examples—users on Wayland or headless systems currently lack guidance.
• Create integration examples in examples/ for AI agent use cases (read screen → OCR → move mouse → type) that demonstrate cv/gosseract + mouse/keyboard coordination, leveraging codg architecture shown in README.

• High · Outdated and Potentially Vulnerable Dependencies — go.mod. The project uses several dependencies with versions that may contain known security vulnerabilities. Notable concerns include: github.com/jezek/xgbutil (v0.0.0-20260124183602-9fd151d6a51a) which appears to be a future-dated commit hash, and multiple transitive dependencies like golang.org/x/sys (v0.42.0) that may have security patches in newer versions. The use of pre-release and uncommitted versions increases supply chain risk. Fix: Run 'go get -u' to update all dependencies to their latest stable versions. Use 'go mod tidy' and 'go list -m all' to audit transitive dependencies. Consider using 'go list -u -m all' to identify available updates and 'nancy' or 'govulncheck' tools to scan for known vulnerabilities.
• High · RPA/GUI Automation Security Risks — Repository root (mouse, key, cv modules). RobotGo is a GUI automation and RPA library that provides capabilities for mouse control, keyboard input, and screen capture. Such tools inherently pose security risks as they can be misused for: keystroke logging, screen capture without consent, automated credential theft, and phishing automation. The library provides no built-in access controls or audit logging. Fix: Document security guidelines for library usage. Implement usage examples that emphasize secure practices. Add warnings in README about privilege requirements and potential misuse. Consider implementing optional audit logging callbacks. Require explicit user consent before capturing sensitive screen areas.
• Medium · Native Code Dependencies (C/C++) Without Visibility — base/, mouse/, key/, event/ directories (header files). The project includes native C/C++ header files (base/.h, mouse/.h, key/.h, event//*.h) that interface with the operating system. These files are not included in the provided analysis, creating blind spots for potential buffer overflows, memory safety issues, or OS-level vulnerabilities. CGO usage introduces additional attack surface. Fix: Perform regular static analysis of C/C++ code using tools like clang-analyzer or cppcheck. Ensure all native code uses safe APIs and bounds checking. Maintain a security policy for CGO usage. Document all OS-level capabilities and their security implications.
• Medium · Clipboard Access Without Restrictions — clipboard/clipboard.go and platform-specific implementations. The clipboard module (clipboard/) provides unrestricted access to system clipboard. This could allow applications to: read sensitive data from clipboard (passwords, API keys), inject malicious content, or perform clipboard-based attacks. No permission prompts or logging mechanisms are evident. Fix: Implement optional clipboard access logging. Add configuration options to restrict clipboard operations. Document clipboard security implications in README. Consider implementing a clipboard content filter for sensitive patterns (base64 encoded tokens, etc.).
• Medium · Commented-out Version Override in go.mod — go.mod (line with commented replace directive). The go.mod file contains a commented-out 'replace' directive for golang.org/x/sys that references an old commit hash. While currently inactive, this suggests past issues with version management and could be accidentally uncommented, forcing the use of outdated vulnerable dependencies. Fix: Remove all commented-out replace directives. If version pinning is necessary, document the reason in code comments. Use proper versioning practices and semantic versioning. Keep replace directives only when absolutely necessary and well-documented.
• Medium · Screenshot Functionality Without Consent Mechanism — cv/gocv.go, examples/screen/. The cv/gocv.go module appears to handle computer vision and screenshot operations. There is no evidence of user consent prompts or sensitive area detection (detecting password fields, payment information, etc.) before capturing screen content. Fix: Implement optional screenshot preview before capture. Add configuration to blur or exclude sensitive areas. Implement audit logging for screenshot operations. Add clear documentation about screen capture capabilities and privacy implications.
• Low · Missing CHANGELOG and Version Tracking — docs/CHANGELOG.md, go.mod. While docs/CHANGELOG.md exists, the project uses a vague versioning scheme in some dependencies (v0.0.0-xxxxx commit hashes). This makes it difficult to track security-relevant changes and audit library updates. Fix: Maintain detailed CHANGELOG with security-related entries clearly marked. Use semantic versioning (MAJOR.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.