CLAUDE.md · pocketpaw/pocketpaw

Sections

1. Project Overview
2. Knowledge Base
3. Commands
4. Architecture
5. Key Conventions
6. Desktop Client (client/)

First lines (shown under the repo's MIT license)

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

PocketPaw is a self-hosted AI agent that runs locally and is controlled via Telegram, Discord, Slack, WhatsApp, or a web dashboard. The Python package is named `pocketpaw` (the internal/legacy name), while the public-facing name is `pocketpaw`. Python 3.11+ required.

## Knowledge Base

A codebase wiki lives at `docs/wiki/` — auto-generated from AST analysis + LLM compilation. **Read the relevant wiki article before modifying a module.**

```bash
# Search the KB from terminal
cd /path/to/knowledge-base && kb search "GroupService" --scope paw-cloud

# Show a specific module's wiki
kb show group_service --scope paw-cloud

# Rebuild after big changes (also runs automatically via PostCommit hook)
kb build ./ee/cloud --scope paw-cloud --output docs/wiki/

# Check wiki health
kb lint --scope paw-cloud
```

Key wiki articles for the enterprise cloud module:
- `docs/wiki/index.md` — Full index with all articles
- `docs/wiki/group_service.md` — Chat group CRUD, membership, agents
- `docs/wiki/message_service.md` — Message CRUD, reactions, threads
- `docs/wiki/service.md` (workspace) — Workspace CRUD, members, invites
- `docs/wiki/agent_bridge.md` — Agent orchestration for cloud chat
- `docs/wiki/errors.md` — CloudError hierarchy

The wiki auto-rebuilds on commits that touch `ee/cloud/` files (via `.claude/hooks/kb-rebuild.sh`).

## Commands

```bash
# Install dev dependencies
uv sync --dev

# Run the app (web dashboard is the default — auto-starts all configured adapters)
uv run pocketpaw

# Run Telegram-only mode (legacy pairing flow)
uv run pocketpaw --telegram

# Run headless Discord bot
uv run pocketpaw --discord

# Run headless Slack bot (Socket Mode, no public URL needed)
uv run pocketpaw --slack

# Run headless WhatsApp webhook server
uv run pocketpaw --whatsapp

# Run multiple headless channels simultaneously
uv run pocketpaw --discord --slack

# Run in development mode (auto-reload on file changes)
uv run pocketpaw --dev

# CLI management commands (all support --json for scripting)
uv run pocketpaw status                     # Show agent status (--watch for live)
uv run pocketpaw health                     # Quick startup health check
uv run pocketpaw doctor                     # Full diagnostics with connectivity
uv run pocketpaw channels                   # List channel configured/autostart status
uv run pocketpaw channels start discord     # Start a channel adapter (needs running dashboard)
uv run pocketpaw channels stop slack        # Stop a channel adapter
uv run pocketpaw skills                     # List available skills
uv run pocketpaw sessions                   # List chat sessions
uv run pocketpaw sessions search <query>    # Search session content
uv run pocketpaw sessions delete <key>      # Delete a session
uv run pocketpaw memory                     # Show memory stats
uv run pocketpaw memory search <query>      # Search long-term memories
uv run pocketpaw config                     # Show config (secrets masked)
uv run pocketpaw config set <key> <value>   # Set a config value
uv run pocketpaw config validate            # Validate API keys
uv run pocketpaw config path                # Print config file path
uv run pocketpaw errors                     # Show recent errors (--limit, --search)
uv run pocketpaw logs                       # Show audit log (--follow to tail)
uv run pocketpaw update                     # Update to latest version via uv

# Run all tests (excluding E2E tests)
uv run pytest --ignore=tests/e2e

# Run a single test file
uv run pytest tests/test_bus.py

# Run a specific test
uv run pytest tests/test_bus.py::test_publish_subscribe -v

# Run E2E tests (requires Playwright browsers - see below)
uv run pytest tests/e2e/ -v

# Install Playwright browsers (required for E2E tests, one-time setup)
# Linux/Mac:
uv run playwright install
# Windows (if above fails with trampoline error):
.venv\Scripts\python -m playwright install

# Lint
uv run ruff check .

# Format
uv run ruff format .

# Type check
uv run mypy .

# Run pre-commit hooks manually
pre-commit run --all-files

# Build package
python -m build
```

## Architecture

### Message Bus Pattern

The core architecture is an event-driven message bus (`src/pocketpaw/bus/`). All communication flows through three event types defined in `bus/events.py`:

- **InboundMessage** — user input from any channel (Telegram, WebSocket, CLI)
- **OutboundMessage** — agent responses back to channels (supports streaming via `is_stream_chunk`/`is_stream_end`)
- **SystemEvent** — internal events (tool_start, tool_result, thinking, error) consumed by the web dashboard Activity panel

### AgentLoop → AgentRouter → Backend

The processing pipeline lives in `agents/loop.py` and `agents/router.py`:

1. **AgentLoop** consumes from the message bus, manages memory context, and streams responses back
2. **AgentRouter** uses a registry-based system (`agents/registry.py`) to select and delegate to one of six backends based on `settings.agent_backend`:
   - `claude_agent_sdk` (default/recommended) — Official Claude Agent SDK with built-in tools (Bash, Read, Write, etc.). Uses `PreToolUse` hooks for dangerous command blocking. Lives in `agents/claude_sdk.py`.
   - `openai_agents` — OpenAI Agents SDK with GPT models and Ollama support. Lives in `agents/openai_agents.py`.
   - `google_adk` — Google Agent Development Kit with Gemini models and native MCP support. Lives in `agents/google_adk.py`.
   - `codex_cli` — OpenAI Codex CLI subprocess wrapper with MCP support. Lives in `agents/codex_cli.py`.
   - `opencode` — External server-based backend via REST API. Lives in `agents/opencode.py`.
   - `copilot_sdk` — GitHub Copilot SDK with multi-provider support. Lives in `agents/copilot_sdk.py`.
   - `deep_agents` — LangChain Deep Agents with LangGraph runtime, built-in planning/subagent tools, and multi-provider support. Lives in `agents/deep_agents.py`.
3. All backends implement the `AgentBackend` protocol (`agents/backend.py`) and yield standardized `AgentEvent` objects with `type`, `content`, and `metadata`
4. Legacy backend names (`pocketpaw_native`, `open_interpreter`, `claude_code`, `gemini_cli`) are mapped to active backends via `_LEGACY_BACKENDS` in the registry

### Channel Adapters

`bus/adapters/` contains protocol translators that bridge external channels to the message bus:

- `TelegramAdapter` — python-telegram-bot
- `WebSocketAdapter` — FastAPI WebSockets
- `DiscliAdapter` — `discord-cli-agent` subprocess wrapper (optional dep `pocketpaw[discord]`). Slash command `/paw` + DM/mention support. Stream buffering with edit-in-place (1.5s rate limit). Auto-registers a `pocketpaw-discord` MCP server on startup exposing Discord operations to all MCP-capable backends. Admin commands (`/converse`, `/setstatus`, etc.) require Administrator or Manage Server permission.
- `SlackAdapter` — slack-bolt Socket Mode (optional dep `pocketpaw[slack]`). Handles `app_mention` + DM events. No public URL needed. Thread support via `thread_ts` metadata.
- `WhatsAppAdapter` — WhatsApp Business Cloud API via `httpx` (core dep). No streaming; accumulates chunks and sends on `stream_end`. Dashboard exposes `/webhook/whatsapp` routes; standalone mode runs its own FastAPI server.

**Dashboard channel management:** The web dashboard (default mode) auto-starts all configured adapters on startup. Channels can be configured, started, and stopped dynamically from the Channels modal in the sidebar. REST API: `GET /api/channels/status`, `POST /api/channels/save`, `POST /api/channels/toggle`.

### Key Subsystems

- **Memory** (`memory/`) — Session history + long-term facts, file-based storage in `~/.pocketpaw/memory/`. Protocol-based (`MemoryStoreProtocol`) for future backend swaps
- **Browser** (`browser/`) — Playwright-based automation using accessibility tree snapshots (not screenshots). `BrowserDriver` returns `NavigationResult` with a `refmap` mapping ref numbers to CSS selectors