Interact with your machine via a coding agent on WhatsApp.
- Install it
npm install -g piwa-cli- Run it
piwaOn first run, piwa will guide you through a quick setup:
- AI Credentials: If no credentials are found, it will help you connect to a provider (like Google Antigravity, which is free).
- Phone Numbers: Set your WhatsApp bot number and owner number.
- WhatsApp Link: A QR code will appear. Open WhatsApp → Settings → Linked Devices → Link a Device, scan the code, and you're live!
Desktop app coming soon — contributions are very welcome! See the Development section to run locally.
- Node.js v18.0.0 or higher.
- A WhatsApp account with a secondary phone number for the agent.
- API keys for at least one supported LLM provider (Google Gemini, Anthropic, or OpenAI).
If you cloned the repository locally:
cd piwa
npm installOr install globally:
npm install -g piwa-cliPiwa looks for API keys in ~/.pi/agent/auth.json. If you haven't authenticated yet, run:
piwa loginOr manually add your API keys to ~/.pi/agent/auth.json.
Launch the WhatsApp bridge and terminal UI:
piwaYou'll be guided through a zero-friction pairing process:
- A QR code appears in your terminal.
- Open WhatsApp on your phone → Settings → Linked Devices → Link a Device.
- Scan the QR code to connect your agent number.
Once paired, the bridge stays active and you can send commands via WhatsApp.
| Command | Description |
|---|---|
piwa |
Starts the agent bridge and TUI |
piwa status |
Shows current pairing and configuration status |
piwa help |
Displays the help menu |
piwa logout |
Removes saved authentication |
Press Ctrl + C in the terminal to gracefully shut down the bridge.
- Hardware-Aware Safety: Proactively prevents running intensive agent tasks that exceed your system's hardware limits.
- Instant Public URLs: Generates secure, public URLs for your agent endpoints automatically.
- Real-Time Telemetry: Monitor agent performance (CPU, GPU, RAM) directly from the desktop interface.
- Dual Interface: Run the native terminal UI and the WhatsApp bridge simultaneously.
cd piwa-desktop
npm install
npm run devnpm install
npm start- Runtime: Node.js (v18.0.0 or higher).
- WhatsApp: A secondary number for the Agent and your personal number for the Owner.
- API Keys: Supports Google Gemini, Anthropic, and OpenAI.
Piwa uses the native pi-coding-agent for authentication. It will automatically find existing keys in ~/.pi/agent/auth.json. You can also use /login in the terminal to connect OAuth providers.
MIT