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

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=+1234567890 # 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

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