ghost-pc 0.2.18

Control your Windows PC from WhatsApp with AI vision

GhostPC

Control your Windows PC from WhatsApp with AI vision.

GhostPC is a local-first AI desktop agent that gives you full control of your Windows PC through WhatsApp messages. Send a text, and the AI sees your screen, moves your mouse, types on your keyboard, runs commands, launches apps, and streams your screen live to your phone.

Features

• AI Vision — Gemini Computer Use sees your screen and takes actions
• Full Desktop Control — Mouse, keyboard, scroll, drag-and-drop
• Terminal Commands — Run PowerShell/cmd from your phone
• App Launching — "Open Chrome", "Open VS Code"
• Live Screen Streaming — MJPEG stream viewable in any mobile browser
• WhatsApp Integration — Baileys-powered, QR code pairing
• Clipboard — Read/write system clipboard remotely
• File Browsing — List, search, and read files on your PC
• Emergency Stop — Ctrl+Alt+Q kills all agent activity instantly
• System Tray — Status icon showing connection state

Quick Start

Prerequisites

• Windows 10/11 (screen capture and input injection are Windows-only)
• Python 3.12+ (auto-downloaded by uv)
• Node.js 20+ (for the WhatsApp bridge)
• Gemini API key from Google AI Studio

Install & Run

# Clone the repo
git clone https://github.com/yourusername/ghost-pc.git
cd ghost-pc

# Set your API key
export GEMINI_API_KEY=your-key-here

# Run (uv handles everything)
uv run ghost

That's it. Scan the QR code with WhatsApp, and start texting commands.

Quick Commands

Command	What it does
Just type naturally	AI processes and executes
screenshot / ss	Send current screen as image
watch / live	Get live screen stream URL
stop	Cancel current action
reset	Clear conversation history
help	Show command list

Configuration

All settings are via environment variables. Create a .env file or export them:

# Required
GEMINI_API_KEY=your-gemini-api-key

# Optional
GHOST_SCREEN_FPS=10               # Live stream FPS (1-60)
GHOST_JPEG_QUALITY=70             # JPEG quality (1-100)
GHOST_CAPTURE_RESOLUTION=1280x720 # Capture resolution
GHOST_STREAM_PORT=8443            # Stream server port
GHOST_EMERGENCY_HOTKEY=ctrl+alt+q # Emergency stop hotkey
GHOST_ALLOWED_NUMBERS=[phone] # WhatsApp allowlist (comma-separated)
GHOST_LOG_LEVEL=INFO              # Logging level

Architecture

Python Agent (asyncio event loop)
├── Orchestrator — wires all subsystems together
├── ADK Agent — Gemini Computer Use model + tools
│   ├── ComputerUseToolset → DesktopComputer(BaseComputer)
│   │   ├── BetterCam screen capture → PNG for model
│   │   └── Win32 SendInput (mouse/keyboard/scroll)
│   └── Custom tools (terminal, apps, clipboard, files)
├── AgentRunner — manages sessions, tool callbacks
├── BaileysBridge — spawns Node.js, JSON-RPC over stdio
├── MJPEGServer — aiohttp, streams JPEG frames + WebSocket chat
└── GhostTray — pystray system tray icon

Node.js Bridge (subprocess)
├── Baileys socket — WhatsApp connection
├── stdin reader — JSON-RPC commands from Python
└── stdout writer — JSON-RPC events to Python

Security

Layer	Protection
WhatsApp Access	Phone number allowlist
Emergency Stop	Ctrl+Alt+Q hotkey
Screen Data	Only sent to Gemini API for analysis
Live Viewing	Token-authenticated URLs
Terminal	Command blocklist (no format, del /s, etc.)
Files	Configurable allowed directories
Coordinates	Clamped to screen dimensions

Development

# Install dev dependencies
uv sync --group dev

# Run tests
uv run pytest tests/ -v

# Lint
uv run ruff check src/

# Format
uv run ruff format src/

# Type check
uv run pyright src/

License

MIT