Owpenbot (WhatsApp UI)

Owpenbot is a lightweight messaging bridge that connects WhatsApp and Telegram to a running OpenCode server. It allows users to interact with agentic workflows through mobile messaging platforms, effectively providing a "WhatsApp UI" for the OpenWork ecosystem. Sources: packages/owpenbot/README.md:3, ARCHITECTURE.md:46-51

The system operates as a standalone CLI tool (owpenwork) or as a sidecar managed by the OpenWork desktop application. It transforms incoming chat messages into OpenCode prompts and relays the agent's responses back to the user's messaging app. Sources: packages/owpenbot/src/cli.ts:133-134, packages/headless/src/cli.ts:896-915

System Architecture

The architecture of Owpenbot is based on a bridge pattern that links external messaging providers (WhatsApp/Telegram) to the internal OpenCode SDK.

This diagram shows the flow of communication from messaging platforms through Owpenbot to the OpenCode engine. Sources: ARCHITECTURE.md:46-51, packages/owpenbot/src/cli.ts:40-45, packages/owpenbot/src/config.ts:41-65

Core Components

• Bridge Service: Manages the lifecycle of messaging sessions and event relaying. Sources: packages/owpenbot/src/cli.ts:133-150
• Adapters: Platform-specific handlers for WhatsApp (using Baileys) and Telegram (using Grammy). Sources: packages/owpenbot/src/cli.ts:600-630
• Persistence Layer: Uses SQLite (defaulting to ~/.owpenbot/owpenbot.db) to store pairing requests and allowlists. Sources: packages/owpenbot/README.md:92, packages/owpenbot/src/config.ts:208
• Tauri Integration: In the desktop app, a Rust-based manager spawns and monitors the Owpenbot process as a sidecar. Sources: packages/desktop/src-tauri/src/commands/owpenbot.rs:64-100

User Authentication & Pairing

Owpenbot implements a security model to control which users can interact with the local OpenCode engine. It supports several Direct Message (DM) policies.

Sources: packages/owpenbot/README.md:94, packages/owpenbot/src/config.ts:18, packages/app/src/app/pages/settings.tsx:287-292

Pairing Flow

When a new user messages the bot under the pairing policy, a request is generated and must be approved via the CLI or the Desktop UI.

Configuration and Environment

Owpenbot configuration is stored in ~/.owpenbot/owpenbot.json. Key configuration parameters include:

• OPENCODE_URL: The endpoint of the running OpenCode server (default: http://127.0.0.1:4096).
• OPENCODE_DIRECTORY: The workspace path for the OpenCode instance.
• WHATSAPP_AUTH_DIR: Directory where WhatsApp session credentials are stored.
• TELEGRAM_BOT_TOKEN: Authentication token from @BotFather.

Sources: packages/owpenbot/src/config.ts:41-72, packages/owpenbot/README.md:32-40

Security Constraints

The bridge is designed for local-first execution. It enforces folder access through the OpenCode server's authorization model, ensuring the bot only works within authorized directories. Sources: ARCHITECTURE.md:144-155, PRINCIPLES.md:15-18

Technical Implementation Details

WhatsApp Integration

The WhatsApp bridge uses the baileys library. It requires a one-time QR code scan to link a "personal" or "dedicated" number to the OpenWork host. Sources: packages/owpenbot/README.md:52-65

// QR Generation Logic in CLI
async function getWhatsAppQr(config: ReturnType<typeof loadConfig>, format: "ascii" | "base64"): Promise<string> {
  const { createWhatsAppSocket, closeWhatsAppSocket } = await import("./whatsapp-session.js");
  // ... creates socket and listens for 'onQr' event
}

Sources: packages/owpenbot/src/cli.ts:155-180

Desktop Sidecar Management

The Tauri desktop shell manages Owpenbot as a background process. It monitors stdout and stderr to detect status changes, such as when a WhatsApp account becomes successfully linked. Sources: packages/desktop/src-tauri/src/commands/owpenbot.rs:64-100

// Snippet from Rust sidecar manager
if line.contains("WhatsApp linked") {
    state.whatsapp_linked = true;
}

Sources: packages/desktop/src-tauri/src/commands/owpenbot.rs:88-90

Conclusion

Owpenbot (WhatsApp UI) provides an accessible interface for OpenWork, enabling mobile-first agentic workflows. By bridging ubiquitous messaging platforms with the OpenCode engine, it fulfills the project goal of making "agentic work" feel like a product accessible to both technical and non-technical users. Sources: README.md:13-25, PRODUCT.md:5-15