Divyanshu Sharma

Posted on Mar 6

I Found an Open-Source AI Agent That Runs on Your Laptop and Talks Through Telegram, Discord, and WhatsApp

#opensource #python #ai #selfhosted

What if your AI assistant lived on YOUR machine, not someone else's cloud?

That question led me to PocketPaw -- a self-hosted AI agent written in Python that runs locally and connects to every messaging platform you already use.

No cloud dependency. No subscription. No data leaving your machine unless you say so.

The Problem Nobody Talks About

Every AI assistant today lives in someone else's server. Your prompts, your files, your context -- all shipped off to a cloud you don't control.

PocketPaw flips that. It runs a full AI agent loop on your local machine and lets you talk to it through:

Telegram
Discord
Slack
WhatsApp
A built-in web dashboard

Same agent. Same memory. Every channel.

What Actually Makes It Different

I dug into the codebase (2000+ tests, properly architected Python) and here's what stood out:

1. Message Bus Architecture

PocketPaw doesn't just bolt channels together. It uses an event-driven message bus with three clean event types:

InboundMessage   # user input from ANY channel
OutboundMessage  # agent response (supports streaming)
SystemEvent      # internal events (tool use, thinking, errors)

Every channel adapter just translates between its native protocol and this bus.

Adding a new channel means implementing three methods:

_on_start()
_on_stop()
send()

2. Six AI Backends, One Interface

You're not locked into one AI provider. PocketPaw supports:

Backend	What It Uses
claude_agent_sdk	Anthropic Claude (default)
openai_agents	OpenAI GPT + Ollama
google_adk	Google Gemini
codex_cli	OpenAI Codex
copilot_sdk	GitHub Copilot
opencode	Any REST-based LLM

All backends implement the same AgentBackend protocol and yield standardized AgentEvent objects.

Switch backends by changing one config value.

3. Real Streaming Across Channels

This isn't "wait 30 seconds then dump the response." PocketPaw streams tokens in real-time.

Discord edits messages in place
The web dashboard streams chunks over WebSocket
WhatsApp buffers and sends when complete

4. It Has 60+ Built-in Tools

Gmail, Spotify, web search, filesystem operations, shell commands, browser automation via Playwright -- it comes loaded.

Each tool follows a ToolProtocol interface:

class MyTool(BaseTool):
    name = "my_tool"
    description = "Does something useful"
    parameters = { ... }  # JSON Schema

    async def execute(self, **params) -> str:
        # Your logic here
        return result

5. Security Is Not an Afterthought

Guardian AI double-checks dangerous operations
Append-only audit log records every tool execution
API keys encrypted using Fernet
SecretFilter removes token patterns from logs
Tool access controlled through policy profiles

Getting Started in 60 Seconds

One-line install (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/pocketpaw/pocketpaw/main/installer/install.sh | sh

Windows PowerShell

irm https://raw.githubusercontent.com/pocketpaw/pocketpaw/main/installer/install.ps1 | iex

Or from source

git clone https://github.com/pocketpaw/pocketpaw.git
cd pocketpaw
uv sync --dev
uv run pocketpaw

The web dashboard opens at http://localhost:8888.

Configure your API key, choose a backend, and start chatting.

The Part That Surprised Me: The Codebase Quality

This isn't a weekend hack. The engineering shows:

Async everywhere
Protocol-oriented architecture
Lazy imports for backends
2000+ tests including Playwright E2E

The code reads like it was written by someone who ships production software.

Contributing Is Straightforward

The repo has clear CONTRIBUTING.md guidelines and labeled issues.

Their workflow:

Find or open an issue
Branch from dev
Fix + add tests
Submit PR to dev

I personally found a Telegram pairing security bug (bot token leaked in error responses), fixed it, wrote tests, and submitted a PR.

Review turnaround was only a few days.

They're even hiring interns through open-source contributions -- no resumes, just code.

Who Is This For?

Privacy-focused developers
Tinkerers building custom AI tools
Teams wanting a shared AI agent without SaaS seat pricing
Anyone tired of copy-pasting between ChatGPT and their workflow

DEV Community