Complete documentation content # AGENTS.md Support > PocketPaw reads AGENTS.md files from target repositories and injects project-specific constraints into the agent's system prompt, following the standardized agent capability declaration format. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page PocketPaw supports the [AGENTS.md standard](https://github.com/anthropics/agents-md), a convention for declaring what an AI agent can and cannot do in a repository. When PocketPaw operates on a codebase, it reads any `AGENTS.md` file and injects those constraints into the agent’s system prompt. ## How It Works 1. On every message, PocketPaw looks for `AGENTS.md` starting from the working directory 2. It walks up parent directories until it finds the file or hits a `.git` boundary (repo root) 3. If found, the file content is injected into the system prompt as a `# Project AGENTS.md Constraints` block 4. The dashboard Activity panel shows an `agents_md_loaded` event when a file is discovered ## Search Behavior The loader mirrors how Git finds `.gitignore`: * Starts at the current working directory (or `file_jail_path` as fallback) * Checks for `AGENTS.md` in each directory * If found, stops and uses it (nearest file wins) * Walks up to the parent directory * Stops at `.git` boundary (repo root) or after 20 levels * Files larger than 32 KB are truncated to prevent oversized prompts ## Writing an AGENTS.md An `AGENTS.md` file declares your project’s rules for AI agents: ```markdown ## Capabilities - Read and write files in the src/ directory - Run tests with `npm test` - Search code with grep ## Forbidden Operations - Never delete the database - Never push to main branch directly - Never modify .env files ## Coding Conventions - Use TypeScript strict mode - Follow the existing naming conventions - All new functions need tests ``` PocketPaw reads the entire file and injects it as-is. You can use any Markdown structure, but clear headings like `Capabilities`, `Forbidden Operations`, and `Conventions` help the agent parse the intent. ## Caching Parsed `AGENTS.md` files are cached by `(path, mtime)`. Repeated calls within the same process are free. Editing the file automatically invalidates the cache on the next message. ## Configuration No configuration is needed. AGENTS.md support is automatic when a file exists in the project directory tree. The feature is resilient by design: if discovery fails for any reason, the agent continues without constraints. ## PocketPaw’s Own AGENTS.md PocketPaw publishes its own `AGENTS.md` at the repository root, declaring its tools, safety boundaries, forbidden operations, and coding conventions for other agents working on the codebase. ## Related ### [Agent Loop](/concepts/agent-loop) [How PocketPaw processes messages and builds context.](/concepts/agent-loop) ### [Context Building](/memory/context-building) [How the system prompt is assembled from identity, memory, and state.](/memory/context-building) Last updated: April 29, 2026 2 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/advanced/agents-md.mdx) Was this page helpful? Yes No --- # Autonomous Messaging: Proactive AI Notifications > PocketPaw can send messages proactively using scheduled intentions with cron triggers. The Proactive Daemon orchestrates agent behaviors and delivers results to any configured notification channel. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page PocketPaw can send messages proactively — without waiting for user input. This is powered by three components: the **Proactive Daemon** (orchestrator), **Intentions** (scheduled behaviors), and the **Channel Notifier** (delivery). ## How It Works ```plaintext ┌─────────────────────────────────┐ │ Proactive Daemon │ │ (orchestrates intentions) │ ├──────────┬──────────────────────┤ │ Trigger │ Intention │ │ Engine │ Executor │ │ (cron) │ (runs agent) │ └────┬─────┴──────────┬───────────┘ │ │ ▼ ▼ APScheduler Channel Notifier fires trigger → delivers to channels ``` ## Intentions An intention is a scheduled agent behavior — a prompt that runs on a trigger. ### Intention Schema | Field | Type | Description | | ----------------- | ------- | ---------------------------------------------------- | | `name` | string | Human-readable name (e.g., “Morning Standup”) | | `prompt` | string | The prompt to send to the agent | | `trigger` | object | When to fire (cron schedule) | | `context_sources` | array | Additional context to inject (e.g., `system_status`) | | `enabled` | boolean | Whether the intention is active | ### Creating Intentions ```plaintext User: Every weekday at 8 AM, check my calendar and summarize today's meetings Agent: Created intention "Daily Calendar Brief" — triggers Mon-Fri at 8:00 AM ``` ### Trigger Types Currently supports cron triggers with standard 5-field expressions: ```plaintext minute hour day month day_of_week 0 8 * * 1-5 (weekdays at 8 AM) ``` Common presets are available: | Preset | Schedule | | --------------------- | ------------- | | `every_minute` | `* * * * *` | | `every_5_minutes` | `*/5 * * * *` | | `every_hour` | `0 * * * *` | | `every_morning_8am` | `0 8 * * *` | | `weekday_morning_8am` | `0 8 * * 1-5` | | `daily_noon` | `0 12 * * *` | | `weekly_monday_9am` | `0 9 * * 1` | | `monthly_first_9am` | `0 9 1 * *` | ### Intention Lifecycle 1. **Create** — Define name, prompt, trigger, and context sources 2. **Schedule** — Trigger engine registers the cron job 3. **Fire** — When the trigger fires, the executor runs the agent with the prompt 4. **Deliver** — Results are streamed to the dashboard and optionally pushed to channels 5. **Repeat** — The trigger re-schedules for the next occurrence ## Channel Notifier The notifier delivers messages to any configured channel without user interaction. ### Configuration Set notification targets in settings as `"channel:chat_id"` strings: ```bash export POCKETPAW_NOTIFICATION_CHANNELS='["telegram:123456789","discord:987654321","slack:C0A1B2C3D"]' ``` Supported channel formats: | Format | Example | | ------------------------- | ------------------------ | | `telegram:{chat_id}` | `telegram:123456789` | | `discord:{channel_id}` | `discord:987654321` | | `slack:{channel_id}` | `slack:C0A1B2C3D` | | `whatsapp:{phone}` | `whatsapp:+1234567890` | | `signal:{phone}` | `signal:+1234567890` | | `matrix:{room_id}` | `matrix:!abc:matrix.org` | | `teams:{conversation_id}` | `teams:19:abc@thread.v2` | | `gchat:{space}` | `gchat:spaces/abc123` | ### Usage Points The notifier is called by: * **Scheduler** — When reminders trigger * **Proactive Daemon** — When intentions execute * **Deep Work** — Human task notifications and project completion alerts * **Dashboard** — Broadcast messages ## Owner ID Set the `owner_id` to identify yourself. This enables the memory system to distinguish between your messages and those from other users on shared channels. ```bash export POCKETPAW_OWNER_ID="your_telegram_user_id" ``` ## Persistence * Intentions are stored in `~/.pocketpaw/intentions.json` * Notification channel targets are stored in config * The daemon reloads all intentions on startup and re-schedules triggers ## Dashboard Integration The web dashboard provides: * View and manage all intentions * Toggle intentions on/off * Trigger an intention manually * See next scheduled run time * Stream execution results in real time Tip Combine autonomous messaging with [Gmail](/integrations/gmail) and [Calendar](/integrations/calendar) tools for powerful automated workflows. For example: “Every morning at 8 AM, check my calendar and email, then send a Telegram summary.” ## Related ### [Cron Scheduler](/advanced/scheduler) [The scheduling engine that powers intention triggers and reminders.](/advanced/scheduler) ### [Deep Work](/advanced/deep-work) [Long-running projects that use autonomous messaging for human task alerts.](/advanced/deep-work) ### [Memory Isolation](/memory/memory-isolation) [Per-user memory scoping tied to the owner ID used by notifications.](/memory/memory-isolation) Last updated: April 29, 2026 2 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/advanced/autonomous-messaging.mdx) Was this page helpful? Yes No --- # Deep Work: Long-Running Autonomous Projects > Deep Work is PocketPaw's AI-powered project orchestrator: describe a project and it researches the domain, writes a PRD, decomposes tasks with dependencies, assembles an agent team, and executes autonomously. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page Deep Work is PocketPaw’s orchestration system for complex, multi-step projects. Describe what you want to build, and PocketPaw researches the domain, writes a product requirements document, breaks it into tasks with dependencies, assembles an agent team, and executes everything autonomously. ## How It Works ### Describe Your Project Provide a natural-language description of what you want to build or accomplish. ### AI Research & Planning The planner agent researches the domain, writes a PRD, decomposes the project into atomic tasks, and recommends an agent team. ### Review & Approve Review the generated plan — tasks, dependencies, time estimates, and team — in the dashboard. Approve when ready. ### Autonomous Execution Tasks execute in dependency order. Agent tasks run via Claude, human tasks notify you for manual completion. Failed tasks retry automatically. Progress streams in real time. ### Completion When all tasks finish, the project is marked complete and deliverables are saved to disk. ## Project Lifecycle | Status | Description | | ------------------- | -------------------------------------------------------- | | `DRAFT` | Project created, not yet planned | | `PLANNING` | Planner agent is researching and decomposing tasks | | `AWAITING_APPROVAL` | Plan ready for user review | | `APPROVED` | User approved, ready to execute | | `EXECUTING` | Tasks are running | | `PAUSED` | Execution paused by user | | `COMPLETED` | All tasks finished | | `FAILED` | Planning or execution error | | `CANCELLED` | User cancelled the project — all remaining tasks skipped | ## Planning Phases The planner runs four sequential phases, each broadcasting progress events to the dashboard: ### 1. Research Gathers domain knowledge before planning. Controlled by `research_depth`: | Depth | Behavior | | ---------- | ------------------------------------------------------- | | `none` | Skip research entirely | | `quick` | Minimal analysis from existing knowledge, no web search | | `standard` | Balanced research, may use web search | | `deep` | Thorough research with extensive web searching | ### 2. Product Requirements Document (PRD) Generates a structured PRD with: * Problem statement * Scope (in/out) * Functional requirements * Non-goals * Technical constraints ### 3. Task Breakdown Decomposes the PRD into atomic tasks. Each task includes: | Field | Description | | ---------------------- | ---------------------------------------------------- | | `key` | Short unique identifier (e.g., `t1`, `t2`) | | `title` | Human-readable name | | `description` | Full description with acceptance criteria | | `task_type` | `agent`, `human`, or `review` | | `priority` | `low`, `medium`, `high`, or `urgent` | | `estimated_minutes` | Time estimate (15-120 min range) | | `required_specialties` | Skills needed (e.g., `backend`, `frontend`) | | `blocked_by_keys` | Dependencies on other tasks | | `max_retries` | How many times to auto-retry on failure (default: 1) | | `timeout_minutes` | Per-task execution time limit (optional) | ### 4. Team Assembly Recommends the minimal set of AI agents needed. Each agent has a name, role, specialties, and backend. Agents are auto-assigned to tasks based on specialty overlap. ## Dependency Scheduling Tasks execute in dependency order using a topological sort (Kahn’s algorithm): * Tasks with no blockers run first (concurrently) * When a task completes, newly unblocked tasks dispatch automatically * The scheduler validates the dependency graph for cycles and missing references before execution ```plaintext Level 0: [t1, t2] ← no dependencies, run in parallel Level 1: [t3, t4] ← depend only on level 0 Level 2: [t5] ← depends on level 1 ``` ## Task Types | Type | Execution | | -------- | -------------------------------------------------------------------------------------------- | | `agent` | Runs via the agent backend (Claude Agent SDK). Output saved as deliverable document. | | `human` | Notification sent to your channels. You complete it manually and mark done in the dashboard. | | `review` | Quality gate — agent output is ready for your review before dependents proceed. | ## Retry & Timeout Tasks don’t just fail and stop — they fight through problems on their own. ### Auto-Retry Each task has a `max_retries` count (default: 1). When an agent task fails or times out, the executor checks whether retries remain. If so, it resets the task to `ASSIGNED` and re-dispatches it automatically. The `retry_count` field tracks how many attempts have been made. Once retries are exhausted, the task moves to `BLOCKED` and waits for your attention. You can also manually retry any blocked task from the dashboard or API — manual retries bypass the `max_retries` limit. ### Task Timeout Set `timeout_minutes` on a task to enforce a hard execution time limit. The executor wraps the agent call in `asyncio.wait_for` — if the agent hasn’t finished within the window, it’s interrupted and treated the same as a failure (triggers retry if attempts remain, otherwise goes `BLOCKED`). Leave `timeout_minutes` unset for tasks that genuinely need open-ended time, like deep research or large code generation. ## Output Chaining When an agent task completes, its full output is stored directly on the `task.output` field. Downstream tasks can reference this output as context — the executor builds each task’s prompt with deliverables from upstream dependencies already included. This means later tasks in the dependency chain know what earlier tasks produced, without you having to wire anything up manually. ## Cancellation Cancel a running project when you need to pull the plug. Cancellation is a terminal state — once cancelled, the project can’t be resumed. What happens when you cancel: 1. All currently executing tasks are stopped immediately 2. All pending and assigned tasks are marked `SKIPPED` 3. Tasks already completed keep their `DONE` status (work isn’t lost) 4. The project status changes to `CANCELLED` You can’t cancel a project that’s already completed or already cancelled. ## Usage ### Starting a Project ```plaintext User: Start a deep work project to build a REST API for a recipe management app Agent: Starting Deep Work project... researching domain, writing PRD, decomposing tasks. ``` Or via the REST API: ```bash curl -X POST http://localhost:8000/api/deep-work/start \ -H "Content-Type: application/json" \ -d '{"description": "Build a REST API for recipe management", "research_depth": "standard"}' ``` ### Reviewing the Plan The dashboard shows: * The generated PRD * Task list with dependencies visualized as execution levels * Estimated total time * Recommended agent team ### Controlling Execution | Action | API Endpoint | | -------------------- | --------------------------------------------------------- | | Approve plan | `POST /api/deep-work/projects/{id}/approve` | | Pause execution | `POST /api/deep-work/projects/{id}/pause` | | Resume execution | `POST /api/deep-work/projects/{id}/resume` | | Cancel project | `POST /api/deep-work/projects/{id}/cancel` | | Skip a task | `POST /api/deep-work/projects/{id}/tasks/{task_id}/skip` | | Retry a blocked task | `POST /api/deep-work/projects/{id}/tasks/{task_id}/retry` | Skipping a task marks it as `SKIPPED` and unblocks dependents. Retrying resets a blocked task to `ASSIGNED` and re-dispatches it. ## PawKit Templates Deep Work projects can be packaged as [PawKit](/advanced/pawkit) templates — YAML configs that define a full [Command Center](/concepts/command-centers) with layout, automated workflows, user configuration, and bundled skills. The Deep Work engine becomes the “Project Orchestrator” Command Center, and domain experts can publish their own PawKits for others to install. See [Command Centers](/concepts/command-centers) for the concept and [PawKit Reference](/advanced/pawkit) for the full YAML schema. ## Project Directories Each project gets a working directory at `~/pocketpaw-projects/{project_id}/`. Agent tasks execute within this directory, and deliverables are saved there. ## Recovery If the server restarts during execution: * Projects stuck in `PLANNING` are marked `FAILED` * Projects in `EXECUTING` have their in-progress tasks reset and re-dispatched ## WebSocket Events The dashboard receives real-time updates: | Event | When | | ---------------------- | ------------------------------------------------------- | | `dw_planning_phase` | Each planning phase starts (research, prd, tasks, team) | | `dw_planning_complete` | Planning finishes or fails | | `dw_project_cancelled` | Project was cancelled | | `mc_task_started` | A task begins executing | | `mc_task_output` | Agent produces output (streamed) | | `mc_task_completed` | A task finishes (includes retry info) | | `mc_task_retry` | A task is about to be retried after failure | Info Deep Work builds on top of [Mission Control](/advanced/mission-control) for task storage, agent management, and the execution engine. The two systems are designed to work together. ## Related ### [Mission Control](/advanced/mission-control) [The multi-agent execution engine that powers Deep Work task management.](/advanced/mission-control) ### [Plan Mode](/advanced/plan-mode) [Structured approval workflows for reviewing agent-generated plans.](/advanced/plan-mode) ### [Autonomous Messaging](/advanced/autonomous-messaging) [Get notified when human tasks need attention or projects complete.](/advanced/autonomous-messaging) Last updated: April 29, 2026 4 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/advanced/deep-work.mdx) Was this page helpful? Yes No --- # Mission Control: Multi-Agent Orchestration > Mission Control is PocketPaw's multi-agent task management framework: create AI agent teams, assign tasks with dependencies, track progress via activity feeds, and stream execution results in real time. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page Mission Control is PocketPaw’s internal framework for managing AI agents, tasks, documents, and activities. It provides the execution backbone for [Deep Work](/advanced/deep-work) and can also be used directly via the REST API for custom multi-agent workflows. ## Core Concepts ### Agents An `AgentProfile` represents a virtual team member with a name, role, specialties, and backend configuration. | Field | Description | | ------------- | ----------------------------------------------------------------------------- | | `name` | Agent name (e.g., `backend-dev`) | | `role` | Job title (e.g., `Backend Engineer`) | | `specialties` | Skills like `["backend", "database", "api"]` | | `backend` | Agent backend (default: `claude_agent_sdk`) | | `status` | `IDLE`, `ACTIVE`, `BLOCKED`, or `OFFLINE` | | `level` | `INTERN` (needs approval), `SPECIALIST` (independent), `LEAD` (full autonomy) | ### Tasks Tasks track units of work with status, priority, dependencies, and assignees. | Status | Description | | ------------- | ----------------------------- | | `INBOX` | New, unassigned | | `ASSIGNED` | Has owner(s), not yet started | | `IN_PROGRESS` | Being worked on | | `REVIEW` | Done, awaiting approval | | `DONE` | Completed | | `BLOCKED` | Waiting on something | | `SKIPPED` | Manually skipped | Tasks support dependency chains via `blocked_by` (IDs of tasks that must complete first) and `blocks` (IDs of tasks waiting on this one). ### Documents Documents store deliverables, research notes, and protocols. Types: `DELIVERABLE`, `RESEARCH`, `PROTOCOL`, `TEMPLATE`, `DRAFT`. Documents are auto-versioned on update. ### Messages & Notifications Tasks have threaded message boards. Messages support `@mentions` — mentioning an agent by name (e.g., `@backend-dev`) creates a notification for that agent. Use `@all` to notify everyone. ### Activity Feed All changes (task creation, status updates, messages, heartbeats) generate activity entries for a full audit trail. ## Task Execution When a task is dispatched for execution: 1. A dedicated `AgentRouter` is created with the assigned agent’s backend 2. The task prompt is built with agent identity, project context, PRD, and upstream deliverables 3. The agent streams output via the router 4. Output is broadcast as `mc_task_output` WebSocket events 5. On completion, the output is saved as a `DELIVERABLE` document 6. The scheduler callback fires to unblock dependent tasks Up to 5 tasks can run concurrently. Double-dispatch is prevented by a background launch guard. ## Heartbeat System The `HeartbeatDaemon` periodically checks agent status using APScheduler: * Default interval: 15 minutes * Checks for unread notifications and assigned tasks * Updates agent status (`ACTIVE` if urgent work, `IDLE` otherwise) * Agents are woken up with 2-second stagger to avoid thundering herd ## REST API Mission Control exposes a full CRUD API at `/api/mission-control`. ### Agent Endpoints | Method | Endpoint | Description | | -------- | ------------------------ | ------------------------------ | | `GET` | `/agents` | List agents (filter by status) | | `POST` | `/agents` | Create agent | | `GET` | `/agents/{id}` | Get agent details | | `PATCH` | `/agents/{id}` | Update agent | | `DELETE` | `/agents/{id}` | Delete agent | | `POST` | `/agents/{id}/heartbeat` | Record heartbeat | ### Task Endpoints | Method | Endpoint | Description | | -------- | -------------------- | --------------------------------------------- | | `GET` | `/tasks` | List tasks (filter by status, assignee, tags) | | `POST` | `/tasks` | Create task | | `GET` | `/tasks/{id}` | Get task with messages | | `PATCH` | `/tasks/{id}` | Update task | | `DELETE` | `/tasks/{id}` | Delete task | | `POST` | `/tasks/{id}/assign` | Assign to agents | | `POST` | `/tasks/{id}/status` | Update status | | `POST` | `/tasks/{id}/run` | Execute with agent (background) | | `POST` | `/tasks/{id}/stop` | Stop running task | | `GET` | `/tasks/running` | List currently executing tasks | ### Message & Document Endpoints | Method | Endpoint | Description | | ------- | ----------------------- | ----------------------------------------- | | `GET` | `/tasks/{id}/messages` | Get task messages | | `POST` | `/tasks/{id}/messages` | Post message (auto-detects @mentions) | | `GET` | `/tasks/{id}/documents` | Get task documents | | `GET` | `/documents` | List all documents | | `POST` | `/documents` | Create document | | `PATCH` | `/documents/{id}` | Update document (auto-increments version) | ### Activity & Reports | Method | Endpoint | Description | | ------ | ---------------- | ------------------------------------ | | `GET` | `/activity` | Activity feed (filter by agent/task) | | `GET` | `/stats` | Counts by status for all entities | | `GET` | `/standup` | Generated standup report (markdown) | | `GET` | `/notifications` | List notifications | ## Storage Mission Control uses file-based JSON storage at `~/.pocketpaw/mission_control/`: ```plaintext mission_control/ ├── agents.json ├── tasks.json ├── messages.json ├── activities.json ├── documents.json ├── notifications.json └── projects.json ``` All writes use atomic temp-file-then-rename for crash safety. The storage backend is protocol-based (`MissionControlStoreProtocol`), so it can be swapped for SQLite, Postgres, or any other backend. ## WebSocket Events Real-time updates for the dashboard: | Event | Payload | | --------------------- | -------------------------------------------------------------------- | | `mc_task_started` | `task_id`, `agent_id`, `agent_name`, `task_title` | | `mc_task_output` | `task_id`, `content`, `output_type` (message/tool\_use/tool\_result) | | `mc_task_completed` | `task_id`, `agent_id`, `status`, `error` | | `mc_activity_created` | Full activity object | Info Mission Control is the execution engine behind [Deep Work](/advanced/deep-work). Deep Work adds the planning layer (research, PRD, task breakdown, team assembly) on top of Mission Control’s task management. ## Related ### [Deep Work](/advanced/deep-work) [AI-powered project orchestration built on top of Mission Control.](/advanced/deep-work) ### [Plan Mode](/advanced/plan-mode) [Structured approval workflows for reviewing task execution plans.](/advanced/plan-mode) ### [Autonomous Messaging](/advanced/autonomous-messaging) [Deliver task notifications and completion alerts to any channel.](/advanced/autonomous-messaging) Last updated: April 29, 2026 2 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/advanced/mission-control.mdx) Was this page helpful? Yes No --- # Model Router: Auto-Select Local or Cloud LLMs > PocketPaw's model router automatically classifies message complexity as SIMPLE, MODERATE, or COMPLEX using heuristic signals, then selects the optimal model size to balance cost and capability. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page The Model Router automatically selects the appropriate model size based on message complexity, optimizing cost and latency. Warning **Disabled by default.** Smart model routing is off by default because it conflicts with Claude Code CLI’s built-in model routing. When using the Claude Agent SDK backend (recommended), Claude Code already picks the best model for each task. Enable the model router only if you want explicit control over model tiers. ## How It Works The router classifies each message into one of three complexity levels: | Level | Description | Typical Model | | ---------- | -------------------------------------------- | -------------------- | | `SIMPLE` | Greetings, simple questions, short responses | Smaller/faster model | | `MODERATE` | Multi-step tasks, moderate reasoning | Default model | | `COMPLEX` | Coding, deep analysis, multi-tool chains | Largest model | ## Classification Heuristics The router uses several signals to determine complexity: 1. **Message length** — Longer messages tend to be more complex 2. **Keyword detection** — Certain words indicate complexity: * Code-related: “write code”, “debug”, “refactor”, “implement” * Analysis: “analyze”, “compare”, “explain in detail” * Multi-step: “step by step”, “plan”, “research” 3. **Tool mentions** — References to specific tools suggest higher complexity 4. **Question depth** — Follow-up questions in a chain indicate growing complexity ### Threshold A message is classified as COMPLEX if it has at least 1 complex signal AND is longer than 30 characters. ## Configuration The model router is **disabled by default** (`smart_routing_enabled: false`). Enable it in the dashboard under Settings → Behavior & Safety, or via environment variable: ```bash export POCKETPAW_SMART_ROUTING_ENABLED=true # Customize model tiers export POCKETPAW_MODEL_TIER_SIMPLE="claude-haiku-4-5-20251001" export POCKETPAW_MODEL_TIER_MODERATE="claude-sonnet-4-5-20250929" export POCKETPAW_MODEL_TIER_COMPLEX="claude-opus-4-6" ``` The router works with the Claude Agent SDK backend (and any backend that supports model overrides). ## Example Classifications | Message | Classification | | ---------------------------------------------------- | -------------- | | ”Hi!” | SIMPLE | | ”What time is it?” | SIMPLE | | ”Write a Python web scraper that handles pagination” | COMPLEX | | ”Analyze the performance of my database queries” | COMPLEX | | ”Search for news about AI” | MODERATE | Info The model router is a heuristic system. For most users, leaving it disabled and letting Claude Code handle model selection produces the best results. Enable it only if you want to optimize API costs or need explicit control over which models are used for different task types. Warning **Ollama users:** The model router is automatically skipped when using Ollama, since Ollama runs a single local model. There are no tiers to route between. ## Related ### [Plan Mode](/advanced/plan-mode) [Structured approval workflows that pair well with model routing.](/advanced/plan-mode) ### [Deep Work](/advanced/deep-work) [Long-running autonomous projects that benefit from smart model selection.](/advanced/deep-work) Last updated: April 29, 2026 2 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/advanced/model-router.mdx) Was this page helpful? Yes No --- # PawKit Reference > Technical reference for the PawKit YAML schema — the configuration format behind Command Center templates. Covers layout, panels, workflows, user config, integrations, and the Python API for loading and saving kits. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page A PawKit is a YAML file that defines everything about a [Command Center](/concepts/command-centers): what the user sees (layout), what the agent does automatically (workflows), what the user configures on install (user\_config), what domain knowledge is included (skills), and what external services are needed (integrations). This page is the technical reference. For the concept and vision behind Command Centers, see [Command Centers](/concepts/command-centers). ## Schema Overview ```yaml meta: name: "My Kit" author: "your-name" version: "0.1.0" description: "What this kit does" category: "business" tags: [crm, sales] layout: columns: 2 sections: [...] workflows: daily_scan: schedule: "daily 8am" instruction: "..." output_type: structured user_config: - key: api_key label: "API Key" field_type: secret skills: [domain-knowledge.md] integrations: required: [google-calendar] optional: [slack] ``` ## Meta Every PawKit starts with metadata for display and marketplace indexing. | Field | Type | Description | | --------------- | ------ | ---------------------------------------------------- | | `name` | string | Display name (required) | | `author` | string | Creator name or handle | | `version` | string | Semver version (default: `0.1.0`) | | `description` | string | What this kit does, shown in the Kit Store | | `category` | enum | Domain category (see below) | | `tags` | list | Searchable tags | | `icon` | string | Icon identifier for the sidebar | | `preview_image` | string | Screenshot path for marketplace listing | | `built_in` | bool | Whether this ships with PocketPaw (default: `false`) | ### Categories `general`, `code`, `business`, `creative`, `education`, `content`, `marketing`, `devops`, `finance`, `health`, `realestate` ## Layout The layout defines a grid of sections, each containing one or more panels. ```yaml layout: columns: 2 sections: - title: Overview span: full panels: - id: key-metrics panel_type: metrics_row items: - label: Active Projects source: workflows.project_scan - label: Revenue MTD source: workflows.finance_scan - title: Pipeline span: left panels: - id: deals panel_type: kanban columns: - id: lead title: Leads - id: proposal title: Proposals - id: closed title: Closed - title: Activity span: right panels: - id: recent panel_type: feed max_items: 20 ``` ### Section Fields | Field | Type | Description | | -------- | ------ | ---------------------------------- | | `title` | string | Section heading | | `span` | enum | Width: `full`, `left`, or `right` | | `panels` | list | One or more panels in this section | ### Panel Fields | Field | Type | Description | | ------------- | ------ | --------------------------------------------------------------------- | | `id` | string | Unique panel identifier | | `panel_type` | enum | Widget type (see Panel Types below) | | `source` | string | Data source — typically a workflow output like `workflows.daily_scan` | | `config` | object | Panel-specific settings | | `actions` | list | Interactive buttons (agent\_action, dismiss, navigate, api\_call) | | `items` | list | For `metrics_row`: the stat cards to display | | `columns` | list | For `kanban`: the column definitions | | `chart_type` | enum | For `chart`: `line`, `bar`, `pie`, or `area` | | `max_items` | int | Limit displayed items | | `filter` | object | Filter criteria for the data source | | `card_fields` | list | Which fields to show on kanban cards | | `period` | string | Time range for charts (e.g., `7d`, `30d`) | | `label` | string | Display label override | ### Panel Types | Type | What It Renders | | ------------------ | ----------------------------------------------- | | `metrics_row` | Row of stat cards — counts, percentages, deltas | | `table` | Sortable, filterable data table | | `kanban` | Drag-and-drop columns with cards | | `chart` | Line, bar, pie, or area visualization | | `feed` | Scrollable activity or event feed | | `calendar` | Month or week view with events | | `pipeline` | Stage-based pipeline (like a sales funnel) | | `markdown` | Rendered markdown content block | | `status_list` | List of items with status indicators | | `progress_tracker` | Progress bar with labeled milestones | ### Panel Actions Attach interactive buttons to any panel: ```yaml panels: - id: reviews panel_type: feed source: workflows.review_scan actions: - label: "Draft Reply" action_type: agent_action instruction: "Draft a professional reply to this review" - label: "Dismiss" action_type: dismiss ``` Action types: `agent_action` (triggers agent task), `dismiss` (removes item), `navigate` (opens URL), `api_call` (hits external endpoint). ## Workflows Workflows are automated tasks the agent runs on a schedule or in response to a trigger. Each workflow produces structured output that panels consume. ### Scheduled Workflows Run on a human-readable schedule or cron expression: ```yaml workflows: morning_brief: schedule: "daily 8am" instruction: > Check all connected platforms. Summarize new messages, pending reviews, and any metrics that changed significantly since yesterday. Return structured data. output_type: structured retry: 2 weekly_report: schedule: "0 9 * * 1" # Monday 9 AM (cron) instruction: > Generate a weekly performance report covering the last 7 days. Include trends, highlights, and action items. output_type: document channels: [telegram] message: "Your weekly report is ready." ``` ### Trigger-Based Workflows React to conditions instead of running on a clock: ```yaml workflows: low_stock_alert: trigger: trigger_type: threshold source: workflows.inventory_scan condition: "stock_level < 10" instruction: "Generate a restock recommendation for items below threshold." output_type: structured channels: [telegram, slack] message: "Low stock alert: {{item_count}} items need restocking." review_response: trigger: trigger_type: event source: "new_review" instruction: "Draft a reply to this customer review." output_type: feed target_column: "needs_reply" ``` ### Workflow Fields | Field | Type | Description | | --------------- | ------ | ---------------------------------------------------------------- | | `schedule` | string | When to run — human-readable (`daily 8am`) or cron (`0 9 * * 1`) | | `trigger` | object | Alternative to schedule — reactive trigger | | `instruction` | string | What the agent should do (required) | | `output_type` | enum | `structured`, `task_list`, `feed`, or `document` | | `retry` | int | How many times to retry on failure (default: 2) | | `target_column` | string | For kanban panels: which column to place output items | | `channels` | list | Which channels to notify (e.g., `[telegram, slack]`) | | `message` | string | Notification message template (supports `{{placeholders}}`) | | `format` | string | Output format hint | A workflow must have either `schedule` or `trigger`, not both. ### Trigger Types | Type | Fires When | | ----------- | ---------------------------------------------------------- | | `threshold` | A monitored value crosses a condition (e.g., `stock < 10`) | | `event` | An external event occurs (e.g., new review, new order) | | `cascade` | Another workflow completes (chain workflows together) | ### Output Types | Type | What It Produces | | ------------ | ----------------------------------------------------- | | `structured` | JSON data consumed by table, metrics, or chart panels | | `task_list` | Tasks placed into a kanban column | | `feed` | Items appended to a feed panel | | `document` | Saved as a downloadable report | ## User Config Fields the user fills in during PawKit installation. Workflows reference these values via `{{user_config.}}` placeholders. ```yaml user_config: - key: youtube_channel_id label: "YouTube Channel ID" field_type: text placeholder: "UC..." help_url: "https://support.google.com/youtube/answer/3250431" - key: api_key label: "API Key" field_type: secret - key: brand_voice label: "Brand Voice" field_type: text placeholder: "Friendly, professional, slightly witty" default: "Professional and helpful" - key: content_niche label: "Content Niche" field_type: select options: [tech, lifestyle, gaming, education, business] - key: alert_threshold label: "Low Stock Alert Threshold" field_type: number default: 10 - key: auto_reply label: "Auto-reply to reviews" field_type: boolean default: false ``` ### Field Types | Type | Input Widget | | --------- | ---------------------------------------------- | | `text` | Single-line text input | | `secret` | Password-style input (masked, stored securely) | | `select` | Dropdown from `options` list | | `number` | Numeric input | | `boolean` | Toggle switch | ## Skills & Integrations ### Skills Bundled domain knowledge files. These are markdown files the agent loads as context when running workflows. ```yaml skills: - youtube-seo-guide.md - thumbnail-analysis-framework.md - content-calendar-template.md ``` ### Integrations External services the PawKit depends on. Shown to the user during install so they know what to connect. ```yaml integrations: required: [youtube-api] optional: [google-analytics, social-blade] ``` ## Full Example A content calendar PawKit that tracks, schedules, and analyzes content across platforms: ```yaml meta: name: Content Calendar author: pocketpaw version: 0.1.0 description: Plan, schedule, and track content across platforms category: content tags: [social-media, scheduling, analytics] icon: lucide:calendar layout: columns: 2 sections: - title: Overview span: full panels: - id: metrics panel_type: metrics_row items: - label: Scheduled source: workflows.content_scan - label: Published This Week source: workflows.content_scan - label: Engagement Rate source: workflows.analytics_scan - title: Content Pipeline span: left panels: - id: pipeline panel_type: kanban columns: - id: idea title: Ideas - id: drafting title: Drafting - id: review title: Review - id: scheduled title: Scheduled - id: published title: Published card_fields: [title, platform, due_date] actions: - label: "Draft with AI" action_type: agent_action instruction: "Write a first draft based on this content idea" - title: Recent Activity span: right panels: - id: activity panel_type: feed max_items: 15 source: workflows.content_scan workflows: content_scan: schedule: "daily 8am" instruction: > Check all connected platforms for scheduled and recently published content. Return structured data with post titles, platforms, publish dates, and status. output_type: structured retry: 2 analytics_scan: schedule: "daily 9am" instruction: > Pull engagement metrics for content published in the last 7 days. Calculate average engagement rate and flag any posts performing significantly above or below average. output_type: structured weekly_summary: schedule: "0 9 * * 1" instruction: > Generate a weekly content performance report. Include top performing posts, engagement trends, and recommendations for next week's content strategy. output_type: document channels: [telegram] message: "Your weekly content report is ready." low_engagement_alert: trigger: trigger_type: threshold source: workflows.analytics_scan condition: "engagement_rate < 2.0" instruction: "Analyze why recent posts are underperforming and suggest improvements." output_type: feed channels: [telegram] message: "Heads up — engagement dropped below 2%. Check the dashboard for details." user_config: - key: brand_voice label: Brand Voice field_type: text placeholder: "Friendly, professional, slightly witty" - key: platforms label: Primary Platform field_type: select options: [youtube, instagram, tiktok, twitter, linkedin] - key: posting_frequency label: Posts Per Week field_type: number default: 3 skills: - content-strategy-guide.md - platform-best-practices.md integrations: required: [] optional: [google-calendar, reddit, youtube-api] ``` ## Python API Load and save PawKit configs programmatically: ```python from pathlib import Path from pocketpaw.deep_work.pawkit import ( load_pawkit, save_pawkit, load_pawkit_from_string, PawKitConfig, PawKitMeta, LayoutConfig, ) # Load from file config = load_pawkit(Path("content-calendar.yaml")) print(config.meta.name) # "Content Calendar" print(len(config.workflows)) # 4 print(config.layout.columns) # 2 # Modify and save config.meta.version = "0.2.0" save_pawkit(config, Path("content-calendar-v2.yaml")) # Load from string (useful for testing or API input) config = load_pawkit_from_string(yaml_string) # Build from scratch config = PawKitConfig( meta=PawKitMeta(name="My Kit", category="business"), layout=LayoutConfig(columns=2), ) save_pawkit(config, Path("my-kit.yaml")) ``` Warning PyYAML is required for loading and saving PawKit files. Install it with `pip install pyyaml` if it’s not already available. The Pydantic models work without it for in-memory usage. Info PawKit schema is at v0.1. The core structure (meta, layout, workflows, user\_config) is stable. New panel types, trigger types, and workflow features will be added as Command Centers evolve. See the [roadmap](/advanced/roadmap) for what’s coming. Last updated: April 29, 2026 6 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/advanced/pawkit.mdx) Was this page helpful? Yes No --- # Plan Mode: Multi-Step Task Planning > Plan Mode adds a structured approval workflow to PocketPaw: the agent proposes a multi-step plan, you review it in the dashboard, approve or modify, then the agent executes with full transparency. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page Plan Mode enables a structured planning workflow where the agent creates a plan and waits for user approval before executing. ## How It Works ### User requests a complex task The agent determines the task requires planning (multiple steps, significant changes). ### Agent creates a plan A structured plan is generated with numbered steps, estimated actions, and any risks. ### Plan is presented for approval The plan is displayed in a modal in the web dashboard, or as a formatted message in other channels. ### User approves or modifies The user can approve the plan, request changes, or reject it entirely. ### Agent executes Once approved, the agent executes the plan step by step, reporting progress. ## Dashboard Integration In the web dashboard, Plan Mode uses a dedicated modal: * **Plan display** — Formatted markdown with steps * **Approve button** — Green button to approve and start execution * **Reject button** — Red button to cancel * **Modify** — Text input to request changes ## WebSocket Protocol Plan Mode uses WebSocket messages: ```json // Agent sends plan for approval {"type": "plan_created", "plan": "## Plan\n1. Step one\n2. Step two"} // User approves {"type": "plan_response", "action": "approve"} // User rejects {"type": "plan_response", "action": "reject", "reason": "Too risky"} // User requests modification {"type": "plan_response", "action": "modify", "feedback": "Add error handling"} ``` ## When Plan Mode Activates Plan Mode is triggered for tasks that: * Involve multiple file modifications * Require irreversible system changes * Include complex multi-step workflows * The agent determines would benefit from user review ## Use Cases * **Refactoring code** — Review planned changes before execution * **System administration** — Approve infrastructure changes * **Multi-file edits** — Verify scope before modifying many files * **Research workflows** — Approve the research strategy ## Related ### [Deep Work](/advanced/deep-work) [Full project orchestration with built-in plan review and approval.](/advanced/deep-work) ### [Mission Control](/advanced/mission-control) [Multi-agent task management that executes approved plans.](/advanced/mission-control) ### [Model Router](/advanced/model-router) [Automatic model selection based on task complexity.](/advanced/model-router) Last updated: April 29, 2026 1 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/advanced/plan-mode.mdx) Was this page helpful? Yes No --- # PocketPaw Roadmap: What’s Shipping Next > Track PocketPaw's development progress from v0.1 foundation through v0.4 production hardening. See what shipped, what's coming in v0.5 desktop and onboarding, and what's planned for v0.6 WebMCP and beyond. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page This page tracks what’s shipped and what’s coming. Updated as priorities shift. ## Shipped ### v0.1 - Foundation * Message bus architecture (event-driven core) * Agent loop with memory management * Tool protocol and registry * File-based memory system * Telegram adapter with QR pairing * Web dashboard (Alpine.js, WebSocket streaming) * Ollama, OpenAI, Anthropic LLM support ### v0.2 - Browser and security * Playwright browser automation with accessibility tree snapshots * Element reference system (`[ref=N]` for clicking, typing) * Guardian AI safety layer (secondary LLM check before shell commands) * Audit logging (append-only `~/.pocketpaw/audit.jsonl`) * File jail and single-user lock * Proactive daemon with cron triggers ### v0.3 - Channels and integrations * Discord adapter (slash commands, DM, mention support) * Slack adapter (Socket Mode, no public URL needed) * WhatsApp Business Cloud API adapter * Gmail, Calendar, Drive, Docs integrations via OAuth * Spotify and Reddit tools * Web search (Tavily, Brave, Google) * Image generation (Google Gemini) * Voice and TTS (OpenAI, ElevenLabs) * Speech-to-text (Whisper) * OCR (GPT-4o vision, pytesseract) * Research tool with source synthesis * MCP server support (stdio + HTTP) ### v0.4 - Production hardening (current) * Encrypted credential store (Fernet AES, auto-migration from plaintext) * 7-layer security stack * Injection scanner (regex + optional LLM deep scan) * Security audit CLI (`pocketpaw --security-audit`) * Self-audit daemon (12 daily checks, JSON reports) * Tool policy engine (profiles: minimal, coding, full) * Plan mode (approval workflow for tool execution) * Smart model router (Haiku, Sonnet, Opus based on complexity) * Session compaction (tiered compression for long conversations) * Deep Work mode (focused multi-step execution) * Mission Control (multi-agent orchestration) * Skills system (runtime agent training via SKILL.md files) * Channel management UI (configure, start, stop from dashboard) * Docker support * 2000+ tests passing ## Coming next ### v0.5 - Desktop and onboarding * Native installers (.exe for Windows, .dmg for macOS, .AppImage for Linux) * First-run setup wizard in the web dashboard * System tray app (start, stop, open dashboard) * One-click Ollama detection and install * Auto-update mechanism * Backup and restore (export config + memory) ### v0.6 - WebMCP and browser upgrades * [WebMCP integration](/advanced/webmcp) for structured website interaction * Hybrid browsing: WebMCP where available, accessibility tree fallback * Token usage tracking and cost dashboard * Model failover and context overflow recovery ### Future * ~~Signal, Matrix, Microsoft Teams, Google Chat adapters~~ (shipped) * Docker sandbox for shell command isolation * Hybrid memory search (vector + keyword) * Plugin architecture * Multi-user support * Session teleportation (cross-device continuity) * Desktop notifications center ## How we prioritize We ship what unblocks users first. Security and reliability fixes jump the queue. Feature requests from GitHub issues influence what gets built, so if you want something, [open an issue](https://github.com/pocketpaw/pocketpaw/issues). ## Related ### [WebMCP](/advanced/webmcp) [Browser-based MCP server access planned for v0.6.](/advanced/webmcp) ### [Deep Work](/advanced/deep-work) [Autonomous project orchestration shipped in v0.4.](/advanced/deep-work) ### [Mission Control](/advanced/mission-control) [Multi-agent task management shipped in v0.4.](/advanced/mission-control) Last updated: April 29, 2026 2 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/advanced/roadmap.mdx) Was this page helpful? Yes No --- # Cron Scheduler: Automated Recurring Tasks > PocketPaw's built-in cron scheduler handles recurring tasks and one-time reminders with APScheduler. Tasks persist across restarts, support natural language time parsing, and auto-reschedule after execution. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page PocketPaw includes a built-in task scheduler for recurring reminders and scheduled actions. ## Features * **Recurring tasks** — Schedule tasks with cron-like expressions * **Persistence** — Recurring tasks survive restarts * **Re-scheduling** — Tasks automatically re-schedule after execution * **Management** — Add and delete recurring tasks via tools ## How It Works The scheduler is built on APScheduler and manages two types of tasks: ### One-time Reminders ```plaintext User: Remind me to check the build in 30 minutes Agent: Set a reminder for 2:30 PM — "Check the build" ``` ### Recurring Tasks ```plaintext User: Every Monday at 9 AM, summarize my calendar for the week Agent: Created recurring task: "Weekly calendar summary" — Every Monday at 9:00 AM ``` ## API The scheduler provides two main functions: ### add\_recurring ```python from pocketpaw.scheduler import scheduler scheduler.add_recurring( task_id="weekly-summary", cron_expression="0 9 * * 1", # Every Monday at 9 AM callback=async_function, kwargs={"session_id": "..."}, ) ``` ### delete\_recurring ```python scheduler.delete_recurring("weekly-summary") ``` ## Persistence Recurring tasks are persisted to the config and re-loaded on startup. One-time reminders are stored in memory and lost on restart. ## Cron Expression Format Standard cron format: `minute hour day_of_month month day_of_week` | Expression | Description | | ---------------- | ------------------------------------ | | `0 9 * * 1` | Every Monday at 9:00 AM | | `*/30 * * * *` | Every 30 minutes | | `0 8,17 * * 1-5` | 8 AM and 5 PM on weekdays | | `0 0 1 * *` | First day of every month at midnight | ## Related ### [Autonomous Messaging](/advanced/autonomous-messaging) [Proactive AI notifications powered by scheduled intentions.](/advanced/autonomous-messaging) ### [Skills System](/advanced/skills) [Teach PocketPaw reusable behaviors that scheduled tasks can invoke.](/advanced/skills) Last updated: April 29, 2026 1 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/advanced/scheduler.mdx) Was this page helpful? Yes No --- # Skills System: Reusable AI Agent Capabilities > Skills are persistent SKILL.md files that teach PocketPaw how to handle specific task types. Define triggers, step-by-step instructions, tool chains, and output formats that load into every interaction. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page Skills are persistent markdown files that teach PocketPaw how to handle specific types of tasks. They’re loaded into the agent’s context on every interaction. ## What is a Skill? A skill is a SKILL.md file stored in `~/.claude/skills/` (the standard Claude SDK location). Each skill defines: * **When to activate** — Trigger phrases or conditions * **How to execute** — Step-by-step instructions * **What tools to use** — Tool chains and sequences * **Output format** — Expected response structure ## Creating Skills ### Via the Skill Generator Tool The agent can create skills using the `skill_gen` tool: ```plaintext User: Create a skill for writing daily standup summaries Agent: [uses skill_gen] → Created skill: daily-standup.md ``` ### Manually Create a markdown file in `~/.claude/skills/`: ```markdown # Code Review Skill ## Trigger When the user asks to review code, a PR, or a diff. ## Steps 1. Read the file or diff provided 2. Analyze for: - Bug risks - Performance issues - Security concerns - Code style 3. Provide structured feedback ## Output Format ### Summary Brief overall assessment. ### Issues Found - **[severity]** Description of issue (line X) ### Suggestions - Improvement suggestions ``` ## Skill Loading Skills are loaded by the `SkillLoader` and injected by the `AgentContextBuilder`: 1. On startup, all `*.md` files are scanned from three directories (in priority order): * `~/.agents/skills/` — central skills (from skills.sh) * `~/.claude/skills/` — Claude Code / SDK standard location * `~/.pocketpaw/skills/` — PocketPaw-specific (legacy) 2. Skill content is injected into the system prompt 3. The agent uses skills as reference when handling matching requests 4. After creating a new skill via `skill_gen`, the loader is reloaded When using the Claude Agent SDK backend, skills are also auto-discovered via `setting_sources` — the SDK natively reads SKILL.md files from `~/.claude/skills/` and `.claude/skills/` (project-level). ## Skill Directory ```plaintext ~/.claude/skills/ ├── daily-standup.md ├── code-review.md ├── meeting-notes.md └── git-workflow.md ``` ## Best Practices 1. **Keep skills focused** — One skill per task type 2. **Be specific** — Clear trigger conditions prevent false matches 3. **Include examples** — Show the expected output format 4. **Reference tools** — Specify which tools to use 5. **Test and iterate** — Try the skill and refine it ## Related ### [Context Building](/memory/context-building) [How skills are loaded and injected into the agent’s context window.](/memory/context-building) ### [Deep Work](/advanced/deep-work) [Autonomous project execution that leverages skills for specialized tasks.](/advanced/deep-work) ### [Cron Scheduler](/advanced/scheduler) [Schedule recurring tasks that can trigger skill-based workflows.](/advanced/scheduler) Last updated: April 29, 2026 2 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/advanced/skills.mdx) Was this page helpful? Yes No --- # WebMCP: Browser-Based MCP Server Access > WebMCP is a browser API that lets websites expose structured tools to AI agents. PocketPaw will support WebMCP alongside its existing Playwright-based browser automation for structured website interaction. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page Info WebMCP support is planned for a future release. PocketPaw’s current browser automation (Playwright + accessibility tree) continues to work with any website. ## What is WebMCP? WebMCP (Web Model Context Protocol) is a browser API announced by Google in Chrome 146 that lets websites expose structured tools directly to AI agents. Instead of an agent parsing the DOM or reading accessibility trees to figure out what a page does, the website tells the agent exactly what actions are available. Google and Microsoft co-developed it. It’s being standardized through the W3C’s Web Machine Learning community group. Two APIs make up WebMCP: **Declarative API** - Websites add a `toolname` attribute to HTML forms. The agent reads the form schema and submits structured data. No JavaScript needed. **Imperative API** - Websites register tools via `navigator.modelContext.registerTool()` with a name, description, input schema, and execute function. This handles complex multi-step workflows. Early benchmarks show a 67% reduction in computational overhead compared to vision-based browsing, with task accuracy around 98%. ## How this relates to MCP WebMCP and Anthropic’s Model Context Protocol (MCP) are complementary, not competing: | | Anthropic MCP | WebMCP | | ------------- | ------------------------------------ | ----------------------------- | | Operates | Server-side (backend) | Client-side (browser) | | Protocol | JSON-RPC | Browser API | | Who builds it | Service providers | Website developers | | Purpose | Connect agents to APIs and databases | Connect agents to website UIs | PocketPaw already supports [MCP servers](/integrations/mcp-servers) for backend connectivity. WebMCP adds the frontend equivalent: structured interaction with websites through Chrome. Together, they give PocketPaw agents structured access to both backend services and website UIs. ## How PocketPaw will use it PocketPaw currently browses the web using [Playwright with accessibility tree snapshots](/tools/browser). This works with any website but requires the agent to interpret page structure and figure out what to click. With WebMCP, when a website exposes structured tools, PocketPaw can call them directly: ```plaintext Without WebMCP (current): Navigate to page -> read accessibility tree -> interpret elements -> guess which button to click -> execute action -> hope it worked With WebMCP (planned): Navigate to page -> ask Chrome what tools the site exposes -> call add_to_cart({product_id: "123", quantity: 2}) -> get structured response ``` The plan is a hybrid approach: 1. Check if the website exposes WebMCP tools 2. If yes, use them (faster, more reliable) 3. If no, fall back to the existing accessibility tree approach This gives PocketPaw the widest compatibility: structured when available, smart fallback when not. ## Privacy angle WebMCP runs client-side in the browser. PocketPaw runs locally on your machine. Your browsing data stays on your computer, same as it does today with Playwright. Google’s own agent integration will likely route through Gemini (their cloud). PocketPaw keeps everything local. ## Current status * WebMCP is in early preview in Chrome 146 Canary (behind a flag) * No general availability date announced * Websites need to implement WebMCP tools for it to work * Mass adoption is likely 12-24 months out * PocketPaw will add support once the API stabilizes Track progress on [GitHub issue #156](https://github.com/pocketpaw/pocketpaw/issues/156). ## Further reading * [Chrome WebMCP early preview announcement](https://developer.chrome.com/blog/webmcp-epp) * [W3C Web Machine Learning community group](https://webmcp.link/) * [PocketPaw browser automation docs](/tools/browser) * [MCP server integration](/integrations/mcp-servers) ## Related ### [Model Router](/advanced/model-router) [Automatic model selection for optimizing browser automation tasks.](/advanced/model-router) ### [PocketPaw Roadmap](/advanced/roadmap) [Track WebMCP integration timeline and other upcoming features.](/advanced/roadmap) Last updated: April 29, 2026 2 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/advanced/webmcp.mdx) Was this page helpful? Yes No --- # API Reference > Complete REST API reference for the PocketPaw web dashboard: channels, sessions, MCP servers, memory, security, authentication, webhooks, tunnel, Deep Work, and Mission Control endpoints. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page The PocketPaw web dashboard exposes a comprehensive REST API for managing channels, sessions, MCP servers, memory, security, and more. All endpoints are served by the FastAPI backend. ### Base URL ```plaintext http://localhost:8000 ``` ## Endpoint Groups ### [Channels](/api/get-channels-status) [Start, stop, and configure messaging channels (Discord, Slack, WhatsApp, Telegram, etc.)](/api/get-channels-status) ### [Sessions](/api/get-sessions) [List, search, rename, and delete chat sessions.](/api/get-sessions) ### [MCP Servers](/api/get-mcp-status) [Add, remove, toggle, and test Model Context Protocol servers.](/api/get-mcp-status) ### [Memory](/api/get-memory-long-term) [Manage long-term memories, memory settings, and backend statistics.](/api/get-memory-long-term) ### [Security](/api/get-audit-logs) [View audit logs, run security audits, and manage self-audit reports.](/api/get-audit-logs) ### [Authentication](/api/post-auth-session) [Session tokens, QR login, OAuth flows, and token management.](/api/post-auth-session) ### [Webhooks](/api/get-webhooks) [Manage inbound webhook slots and external platform webhooks.](/api/get-webhooks) ### [Tunnel](/api/get-tunnel-status) [Start and stop Cloudflare tunnels for remote access.](/api/get-tunnel-status) ## Authentication Most API endpoints require authentication. PocketPaw supports multiple auth methods: ```bash curl http://localhost:8000/api/sessions \ -H "Authorization: Bearer your-access-token" ``` ```bash curl "http://localhost:8000/api/sessions?token=your-access-token" ``` Requests from `127.0.0.1` or `::1` bypass auth automatically (unless a Cloudflare tunnel is active). Info Auth-exempt paths: `/webhook/*`, `/oauth/callback`, `/static/*`, `/favicon.ico` ## Quick Reference ### Channels | Method | Endpoint | Description | | ------ | ------------------------------------------------- | -------------------------- | | `GET` | [/api/channels/status](/api/get-channels-status) | Get all channel statuses | | `POST` | [/api/channels/save](/api/post-channels-save) | Save channel configuration | | `POST` | [/api/channels/toggle](/api/post-channels-toggle) | Start or stop a channel | ### Sessions | Method | Endpoint | Description | | -------- | --------------------------------------------------- | -------------------- | | `GET` | [/api/sessions](/api/get-sessions) | List all sessions | | `GET` | [/api/sessions/search](/api/get-sessions-search) | Search sessions | | `DELETE` | [/api/sessions/{id}](/api/delete-session) | Delete a session | | `POST` | [/api/sessions/{id}/title](/api/post-session-title) | Rename a session | | `GET` | [/api/memory/session](/api/get-session-history) | Get session messages | ### MCP Servers | Method | Endpoint | Description | | ------ | -------------------------------------------------------- | ------------------------- | | `GET` | [/api/mcp/status](/api/get-mcp-status) | Get MCP server statuses | | `POST` | [/api/mcp/add](/api/post-mcp-add) | Add an MCP server | | `POST` | [/api/mcp/remove](/api/post-mcp-remove) | Remove an MCP server | | `POST` | [/api/mcp/toggle](/api/post-mcp-toggle) | Enable/disable MCP server | | `POST` | [/api/mcp/test](/api/post-mcp-test) | Test server connection | | `GET` | [/api/mcp/presets](/api/get-mcp-presets) | List available presets | | `POST` | [/api/mcp/presets/install](/api/post-mcp-preset-install) | Install a preset | ### Memory | Method | Endpoint | Description | | -------- | ------------------------------------------------------- | ----------------------- | | `GET` | [/api/memory/long\_term](/api/get-memory-long-term) | List long-term memories | | `DELETE` | [/api/memory/long\_term/{id}](/api/delete-memory-entry) | Delete a memory entry | | `GET` | [/api/memory/settings](/api/get-memory-settings) | Get memory config | | `POST` | [/api/memory/settings](/api/post-memory-settings) | Update memory config | | `GET` | [/api/memory/stats](/api/get-memory-stats) | Get memory statistics | ### Security & Audit | Method | Endpoint | Description | | ------ | ------------------------------------------------------------ | --------------------- | | `GET` | [/api/audit](/api/get-audit-logs) | Get audit log entries | | `POST` | [/api/security-audit](/api/post-security-audit) | Run security audit | | `GET` | [/api/self-audit/reports](/api/get-self-audit-reports) | List audit reports | | `GET` | [/api/self-audit/reports/{date}](/api/get-self-audit-report) | Get specific report | | `POST` | [/api/self-audit/run](/api/post-self-audit-run) | Trigger self-audit | ### Authentication & OAuth | Method | Endpoint | Description | | ------ | --------------------------------------------------- | ----------------------- | | `POST` | [/api/auth/session](/api/post-auth-session) | Get session token | | `GET` | [/api/qr](/api/get-qr-code) | Generate QR login code | | `POST` | [/api/token/regenerate](/api/post-token-regenerate) | Regenerate access token | | `GET` | [/api/oauth/authorize](/api/get-oauth-authorize) | Start OAuth flow | ### Webhooks | Method | Endpoint | Description | | ------ | ---------------------------------------------------- | ----------------------- | | `GET` | [/api/webhooks](/api/get-webhooks) | List webhook slots | | `POST` | [/api/webhooks/add](/api/post-webhooks-add) | Create webhook slot | | `POST` | [/api/webhooks/remove](/api/post-webhooks-remove) | Remove webhook slot | | `POST` | [/webhook/inbound/{name}](/api/post-webhook-inbound) | Receive webhook payload | ### Agent Status | Method | Endpoint | Description | | ------ | ----------------------------------------------------------- | ---------------------------- | | `GET` | [/api/v1/agent/status](/api/get-agent-status) | Get current agent status | | `GET` | [/api/v1/agent/status/stream](/api/get-agent-status-stream) | SSE stream of status changes | ### Tunnel | Method | Endpoint | Description | | ------ | -------------------------------------------- | ----------------------- | | `GET` | [/api/remote/status](/api/get-tunnel-status) | Get tunnel status | | `POST` | [/api/remote/start](/api/post-tunnel-start) | Start Cloudflare tunnel | | `POST` | [/api/remote/stop](/api/post-tunnel-stop) | Stop tunnel | Last updated: April 29, 2026 1 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/api/index.mdx) Was this page helpful? Yes No --- # Configuration Reference > Complete reference of all PocketPaw configuration options: environment variables with POCKETPAW_ prefix, JSON config fields, channel tokens, API keys, tool profiles, and memory backend settings. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page Complete reference of all configuration settings. All environment variables use the `POCKETPAW_` prefix. ## Core Settings | Setting | Env Variable | Type | Default | Description | | ----------------------- | --------------------------------- | ------- | ---------------------------- | --------------------------------------------------------------------------------------------------------- | | `anthropic_api_key` | `POCKETPAW_ANTHROPIC_API_KEY` | string | — | Anthropic API key | | `openai_api_key` | `POCKETPAW_OPENAI_API_KEY` | string | — | OpenAI API key | | `agent_backend` | `POCKETPAW_AGENT_BACKEND` | enum | `claude_agent_sdk` | Agent backend (`claude_agent_sdk`, `openai_agents`, `google_adk`, `codex_cli`, `opencode`, `copilot_sdk`) | | `claude_sdk_model` | `POCKETPAW_CLAUDE_SDK_MODEL` | string | `""` (auto) | Model override for Claude SDK (empty = let Claude Code decide) | | `claude_sdk_max_turns` | `POCKETPAW_CLAUDE_SDK_MAX_TURNS` | integer | `25` | Max tool-use turns per query in Claude SDK | | `smart_routing_enabled` | `POCKETPAW_SMART_ROUTING_ENABLED` | boolean | `false` | Smart model routing (disabled by default — conflicts with Claude Code) | | `model_tier_simple` | `POCKETPAW_MODEL_TIER_SIMPLE` | string | `claude-haiku-4-5-20251001` | Model for simple tasks (when smart routing is on) | | `model_tier_moderate` | `POCKETPAW_MODEL_TIER_MODERATE` | string | `claude-sonnet-4-5-20250929` | Model for moderate tasks (when smart routing is on) | | `model_tier_complex` | `POCKETPAW_MODEL_TIER_COMPLEX` | string | `claude-opus-4-6` | Model for complex tasks (when smart routing is on) | | `dashboard_host` | `POCKETPAW_DASHBOARD_HOST` | string | `0.0.0.0` | Dashboard bind address | | `dashboard_port` | `POCKETPAW_DASHBOARD_PORT` | integer | `8000` | Dashboard port | ## LLM Provider | Setting | Env Variable | Type | Default | Description | | -------------- | ------------------------ | ------ | ------------------------ | -------------------------------------------------------------------------------------------------------------- | | `llm_provider` | `POCKETPAW_LLM_PROVIDER` | enum | `auto` | LLM provider (`auto`, `anthropic`, `openai`, `ollama`, `openai_compatible`, `openrouter`, `gemini`, `litellm`) | | `ollama_host` | `POCKETPAW_OLLAMA_HOST` | string | `http://localhost:11434` | Ollama server URL | | `ollama_model` | `POCKETPAW_OLLAMA_MODEL` | string | `llama3.2` | Ollama model name | When `llm_provider` is `auto`, PocketPaw uses Anthropic if an API key is set, otherwise falls back to Ollama. ## OpenRouter | Setting | Env Variable | Type | Default | Description | | -------------------- | ------------------------------ | ------ | ------- | ------------------------------------------------ | | `openrouter_api_key` | `POCKETPAW_OPENROUTER_API_KEY` | string | — | OpenRouter API key (sk-or-v1-…) | | `openrouter_model` | `POCKETPAW_OPENROUTER_MODEL` | string | `""` | Model slug (e.g., `anthropic/claude-sonnet-4-6`) | ## LiteLLM | Setting | Env Variable | Type | Default | Description | | -------------------- | ------------------------------ | ------- | ----------------------- | ------------------------------------------------------ | | `litellm_api_base` | `POCKETPAW_LITELLM_API_BASE` | string | `http://localhost:4000` | LiteLLM proxy URL (leave empty for direct SDK mode) | | `litellm_api_key` | `POCKETPAW_LITELLM_API_KEY` | string | — | Proxy master key or target provider API key | | `litellm_model` | `POCKETPAW_LITELLM_MODEL` | string | `""` | Model name (use LiteLLM-prefixed names in direct mode) | | `litellm_max_tokens` | `POCKETPAW_LITELLM_MAX_TOKENS` | integer | `0` | Max output tokens (0 = provider default) | ## Tool Policy | Setting | Env Variable | Type | Default | Description | | -------------- | ------------------------ | --------- | ------- | ------------------------------------------ | | `tool_profile` | `POCKETPAW_TOOL_PROFILE` | enum | `full` | Tool profile (`minimal`, `coding`, `full`) | | `tools_allow` | `POCKETPAW_TOOLS_ALLOW` | string\[] | `[]` | Allowed tools (comma-separated list) | | `tools_deny` | `POCKETPAW_TOOLS_DENY` | string\[] | `[]` | Denied tools (comma-separated list) | ## Telegram | Setting | Env Variable | Type | Default | Description | | ---------------------- | -------------------------------- | --------- | ------- | ---------------------------------- | | `telegram_token` | `POCKETPAW_TELEGRAM_TOKEN` | string | — | Bot token | | `allowed_telegram_ids` | `POCKETPAW_ALLOWED_TELEGRAM_IDS` | string\[] | `[]` | Allowed user IDs (comma-separated) | ## Discord | Setting | Env Variable | Type | Default | Description | | --------------------------- | ------------------------------------- | ---------- | ------- | ------------------------------------ | | `discord_bot_token` | `POCKETPAW_DISCORD_BOT_TOKEN` | string | — | Bot token | | `discord_allowed_guild_ids` | `POCKETPAW_DISCORD_ALLOWED_GUILD_IDS` | integer\[] | `[]` | Allowed guilds (comma-separated IDs) | | `discord_allowed_user_ids` | `POCKETPAW_DISCORD_ALLOWED_USER_IDS` | integer\[] | `[]` | Allowed users (comma-separated IDs) | ## Slack | Setting | Env Variable | Type | Default | Description | | --------------------------- | ------------------------------------- | --------- | ------- | -------------------------------------- | | `slack_bot_token` | `POCKETPAW_SLACK_BOT_TOKEN` | string | — | Bot token (xoxb-) | | `slack_app_token` | `POCKETPAW_SLACK_APP_TOKEN` | string | — | App token (xapp-) | | `slack_allowed_channel_ids` | `POCKETPAW_SLACK_ALLOWED_CHANNEL_IDS` | string\[] | `[]` | Allowed channels (comma-separated IDs) | ## WhatsApp | Setting | Env Variable | Type | Default | Description | | -------------------------------- | ------------------------------------------ | --------- | ------------------------- | --------------------------------- | | `whatsapp_mode` | `POCKETPAW_WHATSAPP_MODE` | enum | `""` (unset) | Mode (`personal`, `business`) | | `whatsapp_access_token` | `POCKETPAW_WHATSAPP_ACCESS_TOKEN` | string | — | Business API token | | `whatsapp_phone_number_id` | `POCKETPAW_WHATSAPP_PHONE_NUMBER_ID` | string | — | Phone number ID | | `whatsapp_verify_token` | `POCKETPAW_WHATSAPP_VERIFY_TOKEN` | string | — | Webhook verify token | | `whatsapp_allowed_phone_numbers` | `POCKETPAW_WHATSAPP_ALLOWED_PHONE_NUMBERS` | string\[] | `[]` | Allowed numbers (comma-separated) | | `whatsapp_neonize_db` | `POCKETPAW_WHATSAPP_NEONIZE_DB` | string | `~/.pocketpaw/neonize.db` | Neonize DB path | ## Signal | Setting | Env Variable | Type | Default | Description | | ------------------------ | ---------------------------------- | --------- | ------- | --------------------------------- | | `signal_api_url` | `POCKETPAW_SIGNAL_API_URL` | string | — | signal-cli REST API URL | | `signal_phone_number` | `POCKETPAW_SIGNAL_PHONE_NUMBER` | string | — | Registered number | | `signal_allowed_numbers` | `POCKETPAW_SIGNAL_ALLOWED_NUMBERS` | string\[] | `[]` | Allowed numbers (comma-separated) | ## Matrix | Setting | Env Variable | Type | Default | Description | | ------------------------- | ----------------------------------- | --------- | ------- | ----------------------------------- | | `matrix_homeserver` | `POCKETPAW_MATRIX_HOMESERVER` | string | — | Homeserver URL | | `matrix_user_id` | `POCKETPAW_MATRIX_USER_ID` | string | — | Bot user ID | | `matrix_access_token` | `POCKETPAW_MATRIX_ACCESS_TOKEN` | string | — | Auth token | | `matrix_device_id` | `POCKETPAW_MATRIX_DEVICE_ID` | string | — | Device ID | | `matrix_allowed_room_ids` | `POCKETPAW_MATRIX_ALLOWED_ROOM_IDS` | string\[] | `[]` | Allowed rooms (comma-separated IDs) | | `matrix_display_name` | `POCKETPAW_MATRIX_DISPLAY_NAME` | string | — | Display name | ## Microsoft Teams | Setting | Env Variable | Type | Default | Description | | ------------------------ | ---------------------------------- | --------- | ------- | ----------------------------------- | | `teams_app_id` | `POCKETPAW_TEAMS_APP_ID` | string | — | Bot Framework App ID | | `teams_app_password` | `POCKETPAW_TEAMS_APP_PASSWORD` | string | — | App password | | `teams_tenant_id` | `POCKETPAW_TEAMS_TENANT_ID` | string | — | Azure tenant ID | | `teams_allowed_team_ids` | `POCKETPAW_TEAMS_ALLOWED_TEAM_IDS` | string\[] | `[]` | Allowed teams (comma-separated IDs) | ## Google Chat | Setting | Env Variable | Type | Default | Description | | --------------------------- | ------------------------------------- | --------- | --------- | ------------------------------------- | | `gchat_project_id` | `POCKETPAW_GCHAT_PROJECT_ID` | string | — | GCP project ID | | `gchat_service_account_key` | `POCKETPAW_GCHAT_SERVICE_ACCOUNT_KEY` | string | — | SA key path | | `gchat_mode` | `POCKETPAW_GCHAT_MODE` | enum | `webhook` | Connection mode (`webhook`, `pubsub`) | | `gchat_subscription` | `POCKETPAW_GCHAT_SUBSCRIPTION` | string | — | Pub/Sub subscription | | `gchat_allowed_space_ids` | `POCKETPAW_GCHAT_ALLOWED_SPACE_IDS` | string\[] | `[]` | Allowed spaces (comma-separated IDs) | ## Web Search | Setting | Env Variable | Type | Default | Description | | ---------------------- | -------------------------------- | ------ | -------- | ----------------------------------- | | `web_search_provider` | `POCKETPAW_WEB_SEARCH_PROVIDER` | enum | `tavily` | Search provider (`tavily`, `brave`) | | `tavily_api_key` | `POCKETPAW_TAVILY_API_KEY` | string | — | Tavily API key | | `brave_search_api_key` | `POCKETPAW_BRAVE_SEARCH_API_KEY` | string | — | Brave Search key | ## Image Generation | Setting | Env Variable | Type | Default | Description | | ---------------- | -------------------------- | ------ | ------------------ | ----------------- | | `google_api_key` | `POCKETPAW_GOOGLE_API_KEY` | string | — | Google AI API key | | `image_model` | `POCKETPAW_IMAGE_MODEL` | string | `gemini-2.0-flash` | Model | ## Voice & STT | Setting | Env Variable | Type | Default | Description | | -------------------- | ------------------------------ | ------ | ----------- | ----------------------------------------------- | | `tts_provider` | `POCKETPAW_TTS_PROVIDER` | enum | `openai` | TTS provider (`openai`, `elevenlabs`, `sarvam`) | | `tts_voice` | `POCKETPAW_TTS_VOICE` | string | `alloy` | Voice ID | | `elevenlabs_api_key` | `POCKETPAW_ELEVENLABS_API_KEY` | string | — | ElevenLabs key | | `stt_model` | `POCKETPAW_STT_MODEL` | string | `whisper-1` | STT model | ## Google Integration | Setting | Env Variable | Type | Default | Description | | ---------------------- | -------------------------------- | ------ | ------- | --------------- | | `google_client_id` | `POCKETPAW_GOOGLE_CLIENT_ID` | string | — | OAuth client ID | | `google_client_secret` | `POCKETPAW_GOOGLE_CLIENT_SECRET` | string | — | OAuth secret | ## Spotify | Setting | Env Variable | Type | Default | Description | | ----------------------- | --------------------------------- | ------ | ------- | ----------------- | | `spotify_client_id` | `POCKETPAW_SPOTIFY_CLIENT_ID` | string | — | Spotify client ID | | `spotify_client_secret` | `POCKETPAW_SPOTIFY_CLIENT_SECRET` | string | — | Spotify secret | ## MCP | Setting | Env Variable | Type | Default | Description | | ------------------------- | ----------------------------------- | ------ | ------- | ------------------------------------------------------------------------ | | `mcp_client_metadata_url` | `POCKETPAW_MCP_CLIENT_METADATA_URL` | string | — | CIMD URL for MCP OAuth (for servers without dynamic client registration) | ## Memory (Mem0) | Setting | Env Variable | Type | Default | Description | | ------------------------ | ---------------------------------- | ------- | --------------------------- | ----------------------------------------------------- | | `mem0_auto_learn` | `POCKETPAW_MEM0_AUTO_LEARN` | boolean | `false` | Enable auto-learn | | `mem0_llm_provider` | `POCKETPAW_MEM0_LLM_PROVIDER` | enum | `anthropic` | LLM provider (`anthropic`, `openai`, `ollama`) | | `mem0_llm_model` | `POCKETPAW_MEM0_LLM_MODEL` | string | `claude-haiku-4-5-20251001` | LLM model | | `mem0_embedder_provider` | `POCKETPAW_MEM0_EMBEDDER_PROVIDER` | enum | `openai` | Embedder provider (`openai`, `ollama`, `huggingface`) | | `mem0_embedder_model` | `POCKETPAW_MEM0_EMBEDDER_MODEL` | string | `text-embedding-3-small` | Embedder model | | `mem0_vector_store` | `POCKETPAW_MEM0_VECTOR_STORE` | enum | `qdrant` | Vector store (`qdrant`, `chroma`) | Last updated: April 29, 2026 2 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/api/configuration-reference.mdx) Was this page helpful? Yes No --- # WebSocket Protocol > PocketPaw's WebSocket protocol enables real-time bidirectional communication between the dashboard and backend: session switching, message streaming, tool events, and Deep Work progress updates. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page The web dashboard communicates with the PocketPaw backend over WebSocket for real-time streaming. ## Connection ```plaintext ws://localhost:8000/ws ws://localhost:8000/ws?resume_session=session_abc123 ``` The `resume_session` query parameter automatically loads a previous session on connect. ## Message Format All messages are JSON objects with a `type` or `action` field. ## Client → Server Messages ### Send Message ```json { "action": "message", "content": "Hello, what can you do?", "session_id": "session_abc123" } ``` ### Switch Session ```json { "action": "switch_session", "session_id": "session_def456" } ``` ### New Session ```json { "action": "new_session" } ``` ### Plan Response ```json { "action": "plan_response", "response": "approve" } ``` ## Server → Client Messages ### Response Chunk (Streaming) ```json { "type": "response_chunk", "content": "Here is the ", "session_id": "session_abc123" } ``` ### Stream End ```json { "type": "stream_end", "session_id": "session_abc123" } ``` ### Tool Start ```json { "type": "tool_start", "tool": "web_search", "input": {"query": "Python 3.13 release date"}, "session_id": "session_abc123" } ``` ### Tool Result ```json { "type": "tool_result", "tool": "web_search", "result": "Python 3.13 was released on...", "session_id": "session_abc123" } ``` ### Thinking ```json { "type": "thinking", "content": "Let me search for that...", "session_id": "session_abc123" } ``` ### Error ```json { "type": "error", "message": "Failed to execute tool", "session_id": "session_abc123" } ``` ### Plan Created ```json { "type": "plan_created", "plan": "## Plan\n1. Read the file\n2. Modify the function\n3. Run tests", "session_id": "session_abc123" } ``` ### Session Switched ```json { "type": "session_switched", "session_id": "session_def456", "messages": [...] } ``` ### MCP OAuth Redirect Sent when an MCP server requires OAuth authentication. The frontend should open the URL in a popup window. ```json { "type": "mcp_oauth_redirect", "url": "https://github.com/login/oauth/authorize?...", "server": "github" } ``` ### Inbox Update ```json { "type": "inbox_update", "channel": "telegram", "message": "New message from Telegram user", "session_id": "telegram_123" } ``` ## Connection Lifecycle 1. Client connects to `/ws` (optionally with `resume_session`) 2. Server sends session history if resuming 3. Client sends messages, server streams responses 4. Client can switch sessions at any time 5. Connection stays alive with WebSocket keep-alive Last updated: April 29, 2026 1 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/api/websocket.mdx) Was this page helpful? Yes No --- # Agent Backends: Choose Your AI Engine > Choose between six agent backends: Claude Agent SDK (recommended), OpenAI Agents, Google ADK, Codex CLI, OpenCode, or Copilot SDK. Each provides different capabilities and trade-offs. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page PocketPaw supports **seven agent backends** built on a unified `AgentBackend` protocol. Each backend provides different capabilities and trade-offs. All backends yield standardized `AgentEvent` objects, so switching is seamless. ## Backend Comparison | Feature | Claude SDK | OpenAI Agents | Google ADK | Deep Agents | Codex CLI | OpenCode | Copilot SDK | | ------------ | ---------------------------------------------------------------- | ------------- | ---------- | ----------- | --------- | -------- | ----------- | | Status | Production | Beta | Beta | Beta | Beta | Beta | Beta | | Streaming | Yes | Yes | Yes | Yes | Yes | Yes | Yes | | Tools | Yes | Yes | Yes | Yes | Yes | Yes | Yes | | MCP | Yes | No | Yes | .mcp.json | Yes | No | No | | Multi-turn | Yes | Yes | Yes | Yes | Yes | Yes | Yes | | Local models | Ollama | Ollama | No | Ollama | No | No | No | | OpenRouter | Partial | Yes | No | Yes | No | No | No | | LiteLLM | Yes | Yes | Yes | Yes | No | No | Yes | | Required key | [Anthropic API key](https://console.anthropic.com/settings/keys) | OpenAI | Google | None | OpenAI | None | None | ## Switching Backends Set the backend via environment variable, config file, or the dashboard: ```bash export POCKETPAW_AGENT_BACKEND="claude_agent_sdk" # default export POCKETPAW_AGENT_BACKEND="openai_agents" export POCKETPAW_AGENT_BACKEND="google_adk" export POCKETPAW_AGENT_BACKEND="codex_cli" export POCKETPAW_AGENT_BACKEND="opencode" export POCKETPAW_AGENT_BACKEND="copilot_sdk" export POCKETPAW_AGENT_BACKEND="deep_agents" ``` Or change it in the web dashboard’s **Settings** panel — the backend dropdown shows available backends with capability badges. ## Full Tool Access All seven backends have access to PocketPaw’s 50+ built-in tools (file operations, web search, memory, integrations, and more). Tools are wrapped differently for each backend’s expectations through a unified tool bridge: * **Claude SDK** uses native SDK tools (Bash, Read, Write, etc.) * **OpenAI Agents** and **Copilot SDK** wrap tools as `FunctionTool` objects with JSON schema * **Google ADK** and **Deep Agents** wrap tools as Python callables with introspected signatures * **Codex CLI** and **OpenCode** inject tool instructions into the system prompt with a CLI bridge Tool availability is governed by the same [Tool Policy](/tools/tool-policy) system across all backends. Profiles (`safe`, `dev`, `full`) and per-tool allow/deny lists work identically regardless of backend. ### OpenRouter & LiteLLM Support PocketPaw has dedicated provider adapters for **OpenRouter** and **LiteLLM**, giving access to 100+ models across multiple backends. **OpenRouter** (100+ models, pay-per-token): ```bash export POCKETPAW_AGENT_BACKEND="openai_agents" export POCKETPAW_OPENAI_AGENTS_PROVIDER="openrouter" export POCKETPAW_OPENROUTER_API_KEY="sk-or-v1-..." export POCKETPAW_OPENROUTER_MODEL="anthropic/claude-sonnet-4-6" ``` **LiteLLM** (100+ providers via proxy or direct SDK): ```bash export POCKETPAW_AGENT_BACKEND="openai_agents" # works with any backend export POCKETPAW_OPENAI_AGENTS_PROVIDER="litellm" export POCKETPAW_LITELLM_API_BASE="http://localhost:4000" export POCKETPAW_LITELLM_MODEL="gpt-4o" ``` See [LLM Providers](/concepts/llm-providers) for detailed configuration of both providers. ## Capability System Each backend declares its capabilities via a `Capability` flag enum: * **STREAMING** — Real-time token-by-token output * **TOOLS** — Can call tools (built-in or custom) * **MCP** — Native Model Context Protocol server support * **MULTI\_TURN** — Maintains conversation context across turns * **CUSTOM\_SYSTEM\_PROMPT** — Accepts a custom system prompt from PocketPaw The dashboard shows capability badges for each backend so you can compare at a glance. ## Backend Details ### [Claude Agent SDK](/backends/claude-sdk) [The recommended backend with native Claude tools, MCP support, and Ollama compatibility.](/backends/claude-sdk) ### [OpenAI Agents SDK](/backends/openai-agents) [OpenAI’s agent framework with GPT models. Supports Ollama for local inference.](/backends/openai-agents) ### [Google ADK](/backends/google-adk) [Google Agent Development Kit with Gemini models and native MCP support.](/backends/google-adk) ### [Codex CLI](/backends/codex-cli) [OpenAI’s Codex CLI for code-focused tasks with MCP support.](/backends/codex-cli) ### [OpenCode](/backends/opencode) [External server-based backend via REST API. Requires separate OpenCode server.](/backends/opencode) ### [Copilot SDK](/backends/copilot-sdk) [GitHub Copilot SDK with multi-provider support (Copilot, OpenAI, Azure, Anthropic).](/backends/copilot-sdk) ### [Deep Agents](/backends/deep-agents) [LangChain/LangGraph backend with built-in planning, subagent delegation, and multi-provider support.](/backends/deep-agents) ### [Ollama (Local LLMs)](/backends/ollama) [Run fully local with supported backends — no API keys, no cloud, no costs.](/backends/ollama) ## Legacy Backends The following backends have been removed but their config values are automatically mapped to active backends: | Legacy Value | Maps To | Removed | | ------------------ | ------------------ | -------- | | `pocketpaw_native` | `claude_agent_sdk` | Feb 2026 | | `open_interpreter` | `claude_agent_sdk` | Feb 2026 | | `claude_code` | `claude_agent_sdk` | Feb 2026 | | `gemini_cli` | `google_adk` | Feb 2026 | If your config still uses a legacy backend name, PocketPaw will silently redirect to the mapped backend. ## Guides ### [Run AI with Ollama](/guides/local-llm-agent) [Set up free local models with no API key needed.](/guides/local-llm-agent) ### [Self-Host Guide](/guides/self-host-ai-agent) [Full walkthrough for running PocketPaw on your own hardware.](/guides/self-host-ai-agent) Last updated: April 29, 2026 2 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/backends/index.mdx) Was this page helpful? Yes No --- # Claude Agent SDK: Recommended PocketPaw Backend > The Claude Agent SDK backend is the recommended choice: official Anthropic SDK with built-in Bash, Read, Write, and Edit tools, PreToolUse safety hooks, and MCP server integration. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page The Claude Agent SDK backend is the **recommended** choice for PocketPaw. It uses Anthropic’s official SDK with built-in tools and native MCP support. ## Overview This backend leverages the `claude-agent-sdk` package, which provides: * **Built-in tools**: Bash, Read, Write, Edit — managed by the SDK * **Tool execution hooks**: `PreToolUse` hooks for dangerous command blocking * **MCP integration**: Native Model Context Protocol server support * **Streaming**: Real-time token-by-token response streaming ## Authentication An **Anthropic API key** is required when using this backend with the Anthropic provider. This is a hard requirement — PocketPaw will not process messages without one. Warning **OAuth tokens are not permitted.** Anthropic’s [authentication policy](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use) prohibits third-party applications from using OAuth tokens obtained through Claude Free, Pro, or Max plans. PocketPaw must authenticate using an API key from [Claude Console](https://console.anthropic.com/settings/keys). ### Get an API key Go to [console.anthropic.com/api-keys](https://console.anthropic.com/settings/keys) and create a new key. ### Set the key Add it as an environment variable, in the dashboard Settings, or in `~/.pocketpaw/config.json`: ```bash export POCKETPAW_ANTHROPIC_API_KEY="sk-ant-..." ``` This requirement only applies to the **Anthropic provider**. If you use Ollama (local models), no API key is needed. ## Configuration ```bash export POCKETPAW_AGENT_BACKEND="claude_agent_sdk" export POCKETPAW_ANTHROPIC_API_KEY="sk-ant-..." ``` ### Claude SDK Settings These settings apply specifically to the Claude Agent SDK backend: | Setting | Env Variable | Default | Description | | ---------------------- | -------------------------------- | ----------- | ---------------------------------------------------------------------------------------- | | `claude_sdk_model` | `POCKETPAW_CLAUDE_SDK_MODEL` | `""` (auto) | Model override. Leave empty to let Claude Code auto-select the best model (recommended). | | `claude_sdk_max_turns` | `POCKETPAW_CLAUDE_SDK_MAX_TURNS` | `25` | Maximum tool-use turns per query. Safety net against runaway tool loops. | ```bash # Let Claude Code auto-select the model (recommended — no override needed) export POCKETPAW_CLAUDE_SDK_MODEL="" # Or force a specific model export POCKETPAW_CLAUDE_SDK_MODEL="claude-sonnet-4-5-20250929" # Increase max turns for complex multi-step tasks export POCKETPAW_CLAUDE_SDK_MAX_TURNS=50 ``` Info **Why let Claude Code auto-select?** Claude Code has its own sophisticated model routing that picks the best model for each task. Setting an explicit model override disables this. Only override if you have a specific reason (e.g., cost control or testing). Warning **Smart Model Routing conflict:** PocketPaw’s Smart Model Router (in Settings → Behavior) is disabled by default because it conflicts with Claude Code’s built-in routing. Enabling it will override Claude Code’s model selection, which may produce worse results. ### Provider Support | Provider | How | | ----------------- | --------------------------------------------- | | Anthropic | Native (default) | | Ollama | Ollama v0.14+ Anthropic API support | | LiteLLM | Routes through proxy via `ANTHROPIC_BASE_URL` | | OpenAI-Compatible | Only if endpoint speaks Anthropic format | ### Using with Ollama ```bash export POCKETPAW_AGENT_BACKEND="claude_agent_sdk" export POCKETPAW_LLM_PROVIDER="ollama" export POCKETPAW_OLLAMA_MODEL="qwen2.5:7b" ``` See [Ollama (Local LLMs)](/backends/ollama) for full setup instructions. ### Using with LiteLLM ```bash export POCKETPAW_AGENT_BACKEND="claude_agent_sdk" export POCKETPAW_CLAUDE_SDK_PROVIDER="litellm" export POCKETPAW_LITELLM_API_BASE="http://localhost:4000" export POCKETPAW_LITELLM_MODEL="gpt-4o" ``` The adapter sets `ANTHROPIC_BASE_URL` to point at the LiteLLM proxy, so the Claude SDK sends Anthropic-format requests to the proxy which translates them for the target provider. ## Built-in Tools The Claude Agent SDK provides these tools natively: | SDK Tool | Description | | -------- | --------------------------------------- | | `Bash` | Execute shell commands | | `Read` | Read files from the filesystem | | `Write` | Write/create files | | `Edit` | Edit existing files with search/replace | | `Skill` | Execute skills from SKILL.md files | ### Tool Name Mapping The SDK uses capitalized tool names internally. PocketPaw maps these to the policy system’s snake\_case names: | SDK Name | Policy Name | | -------- | ------------ | | `Bash` | `shell` | | `Read` | `read_file` | | `Write` | `write_file` | | `Edit` | `edit_file` | | `Skill` | `skill` | This mapping is handled by `_TOOL_POLICY_MAP` in the backend’s `info()` method. ## Safety Hooks The backend uses `PreToolUse` hooks to intercept and block dangerous commands before execution: ```python # Example: Blocking destructive shell commands async def pre_tool_use(tool_name, tool_input): if tool_name == "Bash": command = tool_input.get("command", "") if is_dangerous_command(command): return BlockedResponse("This command has been blocked for safety.") ``` ## MCP Server Integration The Claude Agent SDK has native MCP support. PocketPaw’s `_get_mcp_servers()` function translates MCP server configurations into the SDK’s expected format: ```python # MCP servers are loaded from ~/.pocketpaw/mcp.json # and passed to the SDK during initialization servers = _get_mcp_servers() ``` MCP tools are subject to the tool policy system. Use `mcp::*` patterns in allow/deny lists: ```bash # Allow all tools from a specific MCP server export POCKETPAW_TOOLS_ALLOW="mcp:filesystem:*" # Deny all MCP tools export POCKETPAW_TOOLS_DENY="group:mcp" ``` ## Custom Tools In addition to the SDK’s built-in tools, PocketPaw registers its own tools (web\_search, image\_gen, etc.) as custom tool definitions passed to the SDK. ## Skill Auto-Discovery The backend passes `setting_sources=["user", "project"]` to the SDK, enabling automatic discovery of SKILL.md files from: * `~/.claude/skills/` — User-level skills * `.claude/skills/` — Project-level skills This means skills created by the `skill_gen` tool (which writes to `~/.claude/skills/`) are automatically available to the SDK without additional configuration. ## Response Format The backend yields standardized `AgentEvent` objects (not raw dicts): ```python AgentEvent(type="message", content="Here's the result...") AgentEvent(type="tool_use", content="", metadata={"tool": "Bash", "input": {"command": "ls"}}) AgentEvent(type="tool_result", content="file1.txt\nfile2.txt", metadata={"tool": "Bash"}) AgentEvent(type="done", content="") ``` All backends use the same `AgentEvent` format, defined in `agents/backend.py`. ## Related ### [Ollama: Run with Free Local Models](/backends/ollama) [Use the Claude Agent SDK with local models via Ollama — no API keys needed.](/backends/ollama) ### [OpenAI Agents SDK](/backends/openai-agents) [Alternative backend using OpenAI’s agent framework with GPT models.](/backends/openai-agents) ### [All Agent Backends](/backends) [Compare all six backends side by side with capability badges.](/backends) ### [Self-Host PocketPaw](/guides/self-host-ai-agent) [Deploy PocketPaw on your own server with the Claude Agent SDK backend.](/guides/self-host-ai-agent) Last updated: April 29, 2026 3 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/backends/claude-sdk.mdx) Was this page helpful? Yes No --- # Codex CLI: Code-Focused AI Backend > The Codex CLI backend wraps OpenAI's Codex CLI for code-focused agent tasks with MCP server support, NDJSON streaming, and shell/file tools for programming workflows. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page The Codex CLI backend wraps OpenAI’s **Codex CLI** as a subprocess, providing code-focused agent capabilities with MCP support. ## Overview * **Status**: Beta * **Provider support**: OpenAI * **Built-in tools**: shell, file\_edit, web\_search, mcp * **MCP support**: Yes * **Architecture**: Subprocess wrapper — spawns the `codex` binary ## Prerequisites Install the Codex CLI globally: ```bash npm install -g @openai/codex ``` Verify it’s on your PATH: ```bash codex --version ``` ## Configuration ```bash export POCKETPAW_AGENT_BACKEND="codex_cli" export POCKETPAW_OPENAI_API_KEY="sk-..." ``` The backend also accepts `CODEX_API_KEY` as an alternative to `OPENAI_API_KEY`. ### Backend-Specific Settings | Setting | Env Variable | Default | Description | | --------------------- | ------------------------------- | ----------------- | ---------------------------- | | `codex_cli_model` | `POCKETPAW_CODEX_CLI_MODEL` | `"gpt-5.3-codex"` | Model to use | | `codex_cli_max_turns` | `POCKETPAW_CODEX_CLI_MAX_TURNS` | `0` (unlimited) | Max tool-use turns per query | ## Built-in Tools | Codex Tool | Policy Mapping | | ------------ | -------------- | | `shell` | `shell` | | `file_edit` | `write_file` | | `web_search` | `browser` | | `mcp` | `mcp` | ## How It Works 1. PocketPaw spawns the `codex` CLI binary as a subprocess 2. Messages and history are injected via the CLI’s input interface 3. Output streams as NDJSON (newline-delimited JSON) 4. PocketPaw parses NDJSON events into `AgentEvent` objects 5. MCP servers are forwarded to the Codex CLI ## When to Use Choose Codex CLI when: * You want a code-focused agent optimized for programming tasks * You’re already using OpenAI’s Codex CLI and want it integrated into PocketPaw * You need MCP support with an OpenAI-based backend ## Related ### [OpenAI Agents SDK](/backends/openai-agents) [Another OpenAI-powered backend with GPT models and Ollama support.](/backends/openai-agents) ### [Claude Agent SDK](/backends/claude-sdk) [The recommended backend with native tools and MCP integration.](/backends/claude-sdk) ### [All Agent Backends](/backends) [Compare all six backends side by side with capability badges.](/backends) Last updated: April 29, 2026 1 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/backends/codex-cli.mdx) Was this page helpful? Yes No --- # Copilot SDK: GitHub Multi-Provider Backend > The Copilot SDK backend uses GitHub's Copilot SDK with support for Copilot, OpenAI, Azure, and Anthropic providers. JSON-RPC event-driven agent execution. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page The Copilot SDK backend wraps GitHub’s **Copilot SDK** (`github-copilot-sdk`), providing multi-provider agent capabilities with JSON-RPC event-driven execution. ## Overview * **Status**: Beta * **Provider support**: Copilot, OpenAI, Azure, Anthropic, LiteLLM * **Built-in tools**: shell, file\_ops, git, web\_search * **MCP support**: No * **Architecture**: Python SDK wrapper with CopilotClient singleton ## Prerequisites Install the Copilot CLI: ```bash pip install github-copilot-sdk ``` Ensure the `copilot` CLI is on your PATH. For the default Copilot provider, you need an active GitHub Copilot subscription. ## Configuration ```bash export POCKETPAW_AGENT_BACKEND="copilot_sdk" ``` ### Backend-Specific Settings | Setting | Env Variable | Default | Description | | ----------------------- | --------------------------------- | --------------- | -------------------------------------------------------------- | | `copilot_sdk_provider` | `POCKETPAW_COPILOT_SDK_PROVIDER` | `"copilot"` | Provider: `copilot`, `openai`, `azure`, `anthropic`, `litellm` | | `copilot_sdk_model` | `POCKETPAW_COPILOT_SDK_MODEL` | `""` (auto) | Model to use | | `copilot_sdk_max_turns` | `POCKETPAW_COPILOT_SDK_MAX_TURNS` | `0` (unlimited) | Max turns per query | ### Provider Configuration Copilot (default) OpenAI Azure Anthropic LiteLLM ```bash export POCKETPAW_COPILOT_SDK_PROVIDER="copilot" # Uses your GitHub Copilot subscription, no separate API key needed ``` ```bash export POCKETPAW_COPILOT_SDK_PROVIDER="openai" export POCKETPAW_OPENAI_API_KEY="sk-..." ``` ```bash export POCKETPAW_COPILOT_SDK_PROVIDER="azure" # Configure Azure OpenAI credentials ``` ```bash export POCKETPAW_COPILOT_SDK_PROVIDER="anthropic" export POCKETPAW_ANTHROPIC_API_KEY="sk-ant-..." ``` ```bash export POCKETPAW_COPILOT_SDK_PROVIDER="litellm" export POCKETPAW_LITELLM_API_BASE="http://localhost:4000" export POCKETPAW_LITELLM_MODEL="gpt-4o" ``` ## Built-in Tools | Copilot Tool | Policy Mapping | | ------------ | -------------- | | `shell` | `shell` | | `file_ops` | `write_file` | | `git` | `shell` | | `web_search` | `browser` | ## How It Works 1. PocketPaw creates a `CopilotClient` singleton for the session 2. Messages are sent via the JSON-RPC event-driven interface 3. The Copilot CLI handles tool execution and multi-turn reasoning 4. History is injected for multi-turn context 5. Responses stream back as `AgentEvent` objects ## When to Use Choose Copilot SDK when: * You have a GitHub Copilot subscription and want to use it as your agent backbone * You want multi-provider flexibility (switch between Copilot, OpenAI, Azure, and Anthropic) * You want git-aware coding assistance integrated into PocketPaw ## Related ### [Claude Agent SDK](/backends/claude-sdk) [The recommended backend with native tools and MCP integration.](/backends/claude-sdk) ### [OpenAI Agents SDK](/backends/openai-agents) [OpenAI’s agent framework with GPT models and Ollama support.](/backends/openai-agents) ### [All Agent Backends](/backends) [Compare all six backends side by side with capability badges.](/backends) ### [Self-Host PocketPaw](/guides/self-host-ai-agent) [Deploy PocketPaw on your own infrastructure.](/guides/self-host-ai-agent) Last updated: April 29, 2026 1 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/backends/copilot-sdk.mdx) Was this page helpful? Yes No --- # Deep Agents: LangChain/LangGraph Backend > The Deep Agents backend uses LangChain's Deep Agents SDK with LangGraph runtime for built-in planning, subagent delegation, and multi-provider LLM support. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page The Deep Agents backend uses LangChain’s [Deep Agents SDK](https://docs.langchain.com/oss/python/deepagents/overview) (`deepagents` package) with the LangGraph runtime. It provides built-in planning, subagent delegation, filesystem tools, and access to any LLM provider supported by LangChain. ## Overview * **Status**: Beta * **Provider support**: Anthropic, OpenAI, Google, Ollama, OpenRouter, OpenAI-compatible, LiteLLM * **Built-in tools**: write\_todos, read\_todos, task (subagents), ls, read\_file, write\_file * **MCP support**: Yes (via `.mcp.json` file discovery, supports stdio/SSE/HTTP transports) * **ACP support**: Yes (Agent Communication Protocol for IDE integration via `deepagents-acp`) * **Session persistence**: History injection (LangGraph checkpointing planned) ## Configuration ```bash export POCKETPAW_AGENT_BACKEND="deep_agents" export POCKETPAW_DEEP_AGENTS_MODEL="anthropic:claude-sonnet-4-6" ``` ### Backend-Specific Settings | Setting | Env Variable | Default | Description | | ----------------------- | --------------------------------- | ----------------------------- | ---------------------------------------------------------------- | | `deep_agents_model` | `POCKETPAW_DEEP_AGENTS_MODEL` | `anthropic:claude-sonnet-4-6` | Model in `provider:model` format | | `deep_agents_max_turns` | `POCKETPAW_DEEP_AGENTS_MAX_TURNS` | `100` | Max tool-use turns per query (maps to LangGraph recursion limit) | ### Model Format Deep Agents uses LangChain’s `init_chat_model()` which accepts a `provider:model` string. Set the model in the dashboard or via environment variable: ```bash # Anthropic export POCKETPAW_DEEP_AGENTS_MODEL="anthropic:claude-sonnet-4-6" # OpenAI export POCKETPAW_DEEP_AGENTS_MODEL="openai:gpt-4o" # Google Gemini export POCKETPAW_DEEP_AGENTS_MODEL="google_genai:gemini-2.0-flash" # Ollama (local) export POCKETPAW_DEEP_AGENTS_MODEL="ollama:llama3.2" ``` ### Using with Ollama For free local inference, point to your Ollama instance: ```bash export POCKETPAW_AGENT_BACKEND="deep_agents" export POCKETPAW_DEEP_AGENTS_MODEL="ollama:llama3.2" export POCKETPAW_OLLAMA_HOST="http://localhost:11434" # default ``` The backend passes the Ollama host as `base_url` to the LangChain model. Any model available in your Ollama instance can be used. ### Using with OpenRouter Access 100+ models through OpenRouter’s API: ```bash export POCKETPAW_AGENT_BACKEND="deep_agents" export POCKETPAW_DEEP_AGENTS_MODEL="openrouter:anthropic/claude-sonnet-4-6" export POCKETPAW_OPENROUTER_API_KEY="sk-or-v1-..." ``` The backend routes OpenRouter through the OpenAI-compatible API with `https://openrouter.ai/api/v1` as the base URL. ### Using with LiteLLM Route through a LiteLLM proxy for access to 100+ providers: ```bash export POCKETPAW_AGENT_BACKEND="deep_agents" export POCKETPAW_DEEP_AGENTS_MODEL="litellm:anthropic/claude-sonnet-4-6" export POCKETPAW_LITELLM_API_BASE="http://localhost:4000" export POCKETPAW_LITELLM_API_KEY="your-proxy-key" # optional ``` The backend routes LiteLLM through the OpenAI-compatible API pointed at your proxy URL. Use the `provider/model` format after `litellm:` (e.g., `litellm:openai/gpt-4o`, `litellm:huggingface/meta-llama/Llama-3-70b`). Info In the dashboard, when you type `litellm:`, `ollama:`, or `openrouter:` in the Model field, the relevant config fields (proxy URL, API key, host) appear inline automatically. ### Using with OpenAI-Compatible Endpoints Point to any OpenAI-compatible API: ```bash export POCKETPAW_AGENT_BACKEND="deep_agents" export POCKETPAW_DEEP_AGENTS_MODEL="openai_compatible:your-model-name" export POCKETPAW_OPENAI_COMPATIBLE_BASE_URL="https://your-endpoint.com/v1" export POCKETPAW_OPENAI_COMPATIBLE_API_KEY="your-key" ``` ## Built-in Tools Deep Agents includes its own planning and filesystem tools alongside PocketPaw’s 50+ custom tools: | Deep Agents Tool | Description | Policy Mapping | | ---------------- | --------------------------------- | -------------- | | `write_todos` | Task planning and decomposition | — | | `read_todos` | Read current task list | — | | `task` | Spawn subagents for isolated work | `shell` | | `ls` | List directory contents | `read_file` | | `read_file` | Read file contents | `read_file` | | `write_file` | Write/create files | `write_file` | PocketPaw’s custom tools (web\_search, image\_gen, memory, etc.) are registered as LangChain `StructuredTool` wrappers via the tool bridge. ## MCP Tools Deep Agents supports [MCP (Model Context Protocol)](https://docs.langchain.com/oss/python/deepagents/cli/mcp-tools) servers via `.mcp.json` configuration files. This lets the agent access external tools like file systems, APIs, and databases. ### Configuration Files The SDK discovers `.mcp.json` files at three locations (highest precedence last): 1. `~/.deepagents/.mcp.json` — user-level (global defaults) 2. `/.deepagents/.mcp.json` — project subdirectory 3. `/.mcp.json` — project root (Claude Code compatible) ### Supported Transports **stdio** (spawns server as child process): ```json { "servers": { "my-server": { "command": "/path/to/server", "args": ["--arg1", "value"], "env": { "API_KEY": "..." } } } } ``` **SSE** (remote server): ```json { "servers": { "remote-sse": { "type": "sse", "url": "https://example.com/sse", "headers": { "Authorization": "Bearer token" } } } } ``` **HTTP** (remote server): ```json { "servers": { "remote-http": { "type": "http", "url": "https://example.com/api", "headers": { "Authorization": "Bearer token" } } } } ``` Info The `.mcp.json` format at the project root is compatible with Claude Code’s MCP config, so existing MCP server configs carry over automatically. ### Trust and Security * **Project-level stdio servers**: default-deny policy. The CLI prompts for approval using SHA-256 fingerprinting. In non-interactive mode, use `--trust-project-mcp`. * **Remote servers** (SSE/HTTP): always allowed since they don’t execute local code. Warning MCP support in Deep Agents currently works via file-based discovery (`.mcp.json`), not as a programmatic parameter to `create_deep_agent()`. PocketPaw’s MCP servers configured in the dashboard are not automatically passed to the Deep Agents backend. To use MCP with Deep Agents, configure servers in a `.mcp.json` file in your project root. ## ACP (Agent Communication Protocol) Deep Agents supports [ACP](https://docs.langchain.com/oss/python/deepagents/acp) for IDE integration (Zed, JetBrains, VS Code). ACP standardizes communication between coding agents and editors, allowing editors to provide project context while receiving rich updates. ```bash pip install deepagents-acp ``` This is separate from PocketPaw’s integration and is primarily useful when running Deep Agents directly from an IDE. ## How It Works 1. PocketPaw calls `create_deep_agent()` with the LLM model, system prompt, and tools 2. Messages stream via LangGraph’s `astream()` with `stream_mode=["updates", "messages"]` 3. `messages` chunks yield token-by-token text to the chat 4. `updates` chunks surface tool calls and results to the Activity panel 5. The compiled LangGraph agent is cached across calls for performance 6. Conversation history is injected as message context for multi-turn support ## Installation ```bash pip install pocketpaw[deep-agents] ``` This installs the `deepagents` package and its LangChain/LangGraph dependencies. ## Related ### [All Agent Backends](/backends) [Compare all backends side by side with capability badges.](/backends) ### [Ollama: Free Local Models](/backends/ollama) [Run Deep Agents with local models via Ollama.](/backends/ollama) ### [LLM Providers](/concepts/llm-providers) [Detailed configuration for all supported LLM providers.](/concepts/llm-providers) ### [Tool Policy](/tools/tool-policy) [Control which tools are available to the agent.](/tools/tool-policy) Last updated: April 29, 2026 3 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/backends/deep-agents.mdx) Was this page helpful? Yes No --- # Google ADK: Gemini Models with MCP Support > The Google ADK backend uses Google's Agent Development Kit with Gemini models. Features native MCP support via McpToolset, custom tool bridging, and InMemoryRunner session management. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page The Google ADK backend uses Google’s **Agent Development Kit** (`google-adk` package) with Gemini models. It provides native MCP support and custom tool bridging. ## Overview * **Status**: Beta * **Provider support**: Google (Gemini models), LiteLLM * **Built-in tools**: google\_search, code\_execution * **MCP support**: Yes (native via `McpToolset` — stdio, SSE, HTTP transports) * **Session management**: InMemoryRunner with per-session state ## Configuration ```bash export POCKETPAW_AGENT_BACKEND="google_adk" export POCKETPAW_GOOGLE_API_KEY="..." ``` The backend also reads `GOOGLE_API_KEY` from the environment. ### Backend-Specific Settings | Setting | Env Variable | Default | Description | | ---------------------- | -------------------------------- | --------------- | ------------------------------- | | `google_adk_provider` | `POCKETPAW_GOOGLE_ADK_PROVIDER` | `google` | Provider: `google` or `litellm` | | `google_adk_model` | `POCKETPAW_GOOGLE_ADK_MODEL` | `""` (auto) | Gemini model to use | | `google_adk_max_turns` | `POCKETPAW_GOOGLE_ADK_MAX_TURNS` | `0` (unlimited) | Max tool-use turns per query | ### Using with LiteLLM LiteLLM support lets you use non-Gemini models with Google ADK’s tooling and MCP integration: ```bash export POCKETPAW_AGENT_BACKEND="google_adk" export POCKETPAW_GOOGLE_ADK_PROVIDER="litellm" export POCKETPAW_LITELLM_API_BASE="http://localhost:4000" export POCKETPAW_LITELLM_MODEL="openai/gpt-4o" ``` ## Built-in Tools | ADK Tool | Policy Mapping | | ---------------- | -------------- | | `google_search` | `browser` | | `code_execution` | `shell` | PocketPaw’s custom tools are wrapped as ADK `FunctionTool` objects via the `build_adk_function_tools()` bridge in `tool_bridge.py`. This uses signature introspection to convert PocketPaw tool definitions into ADK-compatible functions. ## MCP Integration Google ADK has native MCP support via `McpToolset`. PocketPaw loads configured MCP servers and passes them to the ADK agent: * **stdio** transport for local MCP servers * **SSE** transport for HTTP-based MCP servers * **HTTP** transport for REST-based MCP servers MCP tools are subject to the same tool policy system as other tools. ## How It Works 1. PocketPaw creates a `LlmAgent` with the system prompt, tools, and MCP servers 2. An `InMemoryRunner` manages session state 3. Messages are sent via the runner’s async interface 4. The ADK handles multi-turn tool calling with Gemini 5. Responses stream back as `AgentEvent` objects ## Installation ```bash pip install pocketpaw[google-adk] ``` This installs `google-adk>=1.0.0` as an optional dependency. Info **Replaces Gemini CLI:** This backend replaced the earlier `gemini_cli` backend. If your config still uses `gemini_cli`, PocketPaw will automatically redirect to `google_adk`. ## Related ### [Claude Agent SDK](/backends/claude-sdk) [The recommended backend with native tools and MCP integration.](/backends/claude-sdk) ### [Codex CLI](/backends/codex-cli) [Another MCP-capable backend focused on code generation tasks.](/backends/codex-cli) ### [All Agent Backends](/backends) [Compare all six backends side by side with capability badges.](/backends) Last updated: April 29, 2026 2 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/backends/google-adk.mdx) Was this page helpful? Yes No --- # Ollama: Run PocketPaw with Free Local Models > Run PocketPaw with local models via Ollama -- no API keys, no cloud, no costs. Works with Claude Agent SDK and OpenAI Agents backends using Ollama's compatible API endpoints. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page Run PocketPaw entirely on your machine with [Ollama](https://ollama.com) — no API keys, no cloud, no costs. The **Claude Agent SDK** and **OpenAI Agents** backends work with Ollama out of the box. ## How It Works Since Ollama v0.14.0, Ollama exposes an **Anthropic Messages API compatible endpoint**. PocketPaw points the same `AsyncAnthropic` client (or Claude SDK subprocess) at your local Ollama server instead of Anthropic’s cloud. Same tool format, same streaming, zero format conversion. ## Prerequisites ### Install Ollama ```bash curl -fsSL https://ollama.com/install.sh | sh ``` ### Pull a model ```bash ollama pull qwen2.5:7b # Good balance of speed and quality # or ollama pull llama3.2 # Default model ``` ### Start Ollama ```bash ollama serve ``` ## Quick Start Environment Variables Config File Dashboard ```bash export POCKETPAW_LLM_PROVIDER=ollama export POCKETPAW_OLLAMA_MODEL=qwen2.5:7b pocketpaw ``` Edit `~/.pocketpaw/config.json`: ```json { "llm_provider": "ollama", "ollama_host": "http://localhost:11434", "ollama_model": "qwen2.5:7b" } ``` Open the web dashboard, go to **Settings → General**: 1. Set **LLM Provider** to **Ollama** 2. Set **Ollama Host** (defaults to `http://localhost:11434`) 3. Set **Ollama Model** to the model you pulled (e.g., `qwen2.5:7b`, `deepseek-r1:8b`) Warning The Ollama Host and Ollama Model fields only appear when LLM Provider is set to **Ollama**. Make sure to set the model name to match what you have installed — run `ollama list` to check. ## Verify Setup Run the built-in connectivity check: ```bash pocketpaw --check-ollama ``` This performs 4 checks: | Check | What it tests | | ---------------- | ----------------------------------------------- | | Server reachable | Pings `{ollama_host}/api/tags` | | Model available | Verifies configured model is pulled locally | | Messages API | Tests Anthropic-compatible completion endpoint | | Tool calling | Sends a dummy tool and checks the model uses it | ## Configuration | Setting | Env Var | Default | Description | | -------------- | ------------------------ | -------------------------- | ------------------------------------------- | | `llm_provider` | `POCKETPAW_LLM_PROVIDER` | `"auto"` | Set to `"ollama"` for explicit Ollama usage | | `ollama_host` | `POCKETPAW_OLLAMA_HOST` | `"http://localhost:11434"` | Ollama server URL | | `ollama_model` | `POCKETPAW_OLLAMA_MODEL` | `"llama3.2"` | Model to use | ### Auto-Detection When `llm_provider` is `"auto"` (the default): 1. If `anthropic_api_key` is set → uses Anthropic 2. If no API key is set → falls back to Ollama automatically This means if you install PocketPaw and Ollama without any API keys, **it just works**. ## Compatible Backends | Backend | Ollama Support | How | | -------------------- | -------------- | ------------------------------------------------------------------------------ | | **Claude Agent SDK** | Yes | Sets `ANTHROPIC_BASE_URL` env var for the SDK subprocess | | **OpenAI Agents** | Yes | Wraps model in `OpenAIChatCompletionsModel` via Ollama’s OpenAI-compatible API | ### Claude Agent SDK + Ollama The default backend. The SDK subprocess receives these environment variables: * `ANTHROPIC_BASE_URL` → your Ollama host * `ANTHROPIC_API_KEY` → `"ollama"` (accepted but not validated) All SDK built-in tools (Bash, Read, Write, Edit, Glob, Grep, WebSearch, WebFetch) work as usual. ### OpenAI Agents + Ollama Set the provider to `ollama` and the model will be wrapped in `OpenAIChatCompletionsModel` from the OpenAI Agents SDK, communicating with Ollama’s OpenAI-compatible endpoint: ```bash export POCKETPAW_AGENT_BACKEND="openai_agents" export POCKETPAW_OPENAI_AGENTS_PROVIDER="ollama" export POCKETPAW_OLLAMA_MODEL="qwen2.5:7b" ``` ## Recommended Models | Model | Size | Tool Calling | Notes | | ---------------- | ------ | ------------ | --------------------------- | | `qwen2.5:7b` | 4.7 GB | Good | Best balance for most users | | `qwen2.5:14b` | 9 GB | Better | More reliable tool use | | `llama3.2` | 2 GB | Fair | Fast, lightweight | | `mistral:7b` | 4.1 GB | Good | Strong reasoning | | `deepseek-r1:8b` | 4.9 GB | Good | Strong at coding tasks | ## Limitations * **Smart Model Router is skipped** — When using Ollama, the [Model Router](/advanced/model-router) cannot switch between models. Smart routing is automatically disabled. * **Tool calling quality varies** — Smaller models may not use tools reliably. If tools aren’t being called, try a larger model. * **Ollama v0.14.0+ required** — Older versions don’t expose the Anthropic Messages API endpoint. ## Error Messages PocketPaw provides Ollama-specific error messages instead of generic API errors: | Error | Meaning | Fix | | ------------------------------------ | ----------------------------------------- | -------------------------------------------------------------------------------------- | | **Model ‘X’ not found in Ollama** | The configured model isn’t pulled locally | Run `ollama pull ` or change the model in **Settings → General → Ollama Model** | | **Ollama error: connection refused** | Ollama server isn’t running | Run `ollama serve` | | **Cannot connect to Ollama** | Wrong host or Ollama is down | Check **Ollama Host** in Settings matches where Ollama is running | ## Troubleshooting ### ”Model not found in Ollama” This means PocketPaw is trying to use a model you haven’t pulled. The default model is `llama3.2` — if you use a different model (e.g., `deepseek`), make sure to update the setting: ```bash # Check what models you have ollama list # Set the correct model export POCKETPAW_OLLAMA_MODEL="deepseek-r1:8b" ``` Or update it in the dashboard: **Settings → General → Ollama Model**. ### ”Cannot reach Ollama server" ```bash # Check Ollama is running ollama serve # Verify it's listening curl http://localhost:11434/api/tags ``` ### "Messages API failed” Your Ollama version may be too old. Update: ```bash # macOS brew upgrade ollama # Linux curl -fsSL https://ollama.com/install.sh | sh ``` ### “Model responded but did not use the tool” Try a more capable model: ```bash ollama pull qwen2.5:14b ``` Then set `ollama_model` to `qwen2.5:14b` in Settings or config. ## Implementation | File | Description | | ---------------------------- | ------------------------------------------------- | | `agents/claude_sdk.py` | Ollama env vars passed to SDK subprocess | | `agents/openai_agents.py` | Ollama via `OpenAIChatCompletionsModel` wrapper | | `agents/router.py` | Ollama detection logging in `_initialize_agent()` | | `__main__.py` | `--check-ollama` CLI command | | `tests/test_ollama_agent.py` | Tests covering Ollama backends | ## Related ### [Claude Agent SDK](/backends/claude-sdk) [The recommended backend — works with Ollama out of the box.](/backends/claude-sdk) ### [OpenAI Agents SDK](/backends/openai-agents) [Alternative backend that also supports Ollama for local inference.](/backends/openai-agents) ### [Local LLM Agent Guide](/guides/local-llm-agent) [Step-by-step guide to running PocketPaw with local models.](/guides/local-llm-agent) ### [Self-Host PocketPaw](/guides/self-host-ai-agent) [Deploy PocketPaw on your own server with no cloud dependencies.](/guides/self-host-ai-agent) Last updated: April 29, 2026 3 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/backends/ollama.mdx) Was this page helpful? Yes No --- # OpenAI Agents SDK: GPT & Ollama Backend > The OpenAI Agents SDK backend uses OpenAI's agent framework with GPT models and Ollama support. Features code interpreter, file search, and SQLite session persistence. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page The OpenAI Agents SDK backend uses OpenAI’s native agent framework (`openai-agents` package) with GPT models. It also supports Ollama and OpenAI-compatible providers for local inference. ## Overview * **Status**: Beta * **Provider support**: OpenAI, Ollama, OpenAI-compatible, OpenRouter, LiteLLM * **Built-in tools**: code\_interpreter, file\_search, computer\_use * **MCP support**: No * **Session persistence**: SQLite-based via the SDK ## Configuration ```bash export POCKETPAW_AGENT_BACKEND="openai_agents" export POCKETPAW_OPENAI_API_KEY="sk-..." ``` ### Backend-Specific Settings | Setting | Env Variable | Default | Description | | ------------------------- | ----------------------------------- | --------------- | ----------------------------------------------------------------------------- | | `openai_agents_provider` | `POCKETPAW_OPENAI_AGENTS_PROVIDER` | `""` (auto) | Provider: `openai`, `ollama`, `openai_compatible`, `openrouter`, or `litellm` | | `openai_agents_model` | `POCKETPAW_OPENAI_AGENTS_MODEL` | `""` (auto) | Model to use (e.g., `gpt-4o`, `gpt-4o-mini`) | | `openai_agents_max_turns` | `POCKETPAW_OPENAI_AGENTS_MAX_TURNS` | `0` (unlimited) | Max tool-use turns per query | ### Using with Ollama For local inference via Ollama’s OpenAI-compatible API: ```bash export POCKETPAW_AGENT_BACKEND="openai_agents" export POCKETPAW_OPENAI_AGENTS_PROVIDER="ollama" export POCKETPAW_OLLAMA_MODEL="qwen2.5:7b" ``` The backend wraps the Ollama model in `OpenAIChatCompletionsModel` from the SDK. ### Using with OpenRouter ```bash export POCKETPAW_AGENT_BACKEND="openai_agents" export POCKETPAW_OPENAI_AGENTS_PROVIDER="openrouter" export POCKETPAW_OPENROUTER_API_KEY="sk-or-v1-..." export POCKETPAW_OPENROUTER_MODEL="anthropic/claude-sonnet-4-6" ``` ### Using with LiteLLM **Proxy mode** (recommended when running a LiteLLM proxy): ```bash export POCKETPAW_AGENT_BACKEND="openai_agents" export POCKETPAW_OPENAI_AGENTS_PROVIDER="litellm" export POCKETPAW_LITELLM_API_BASE="http://localhost:4000" export POCKETPAW_LITELLM_MODEL="gpt-4o" ``` **Direct SDK mode** (no proxy, LiteLLM SDK calls providers directly): ```bash export POCKETPAW_AGENT_BACKEND="openai_agents" export POCKETPAW_OPENAI_AGENTS_PROVIDER="litellm" export POCKETPAW_LITELLM_API_BASE="" export POCKETPAW_LITELLM_API_KEY="sk-ant-..." export POCKETPAW_LITELLM_MODEL="anthropic/claude-sonnet-4-6" # must be LiteLLM-prefixed ``` Warning In direct SDK mode (no `LITELLM_API_BASE`), model names **must** use LiteLLM’s provider prefix format (e.g., `anthropic/claude-sonnet-4-6`, `openai/gpt-4o`). Without the prefix, LiteLLM cannot determine which provider to route to. ## Built-in Tools | SDK Tool | Policy Mapping | | ------------------ | -------------- | | `code_interpreter` | `shell` | | `file_search` | `read_file` | | `computer_use` | `shell` | PocketPaw’s custom tools (web\_search, image\_gen, etc.) are also registered via the `tool_bridge.py` wrapper. ## How It Works 1. PocketPaw creates an OpenAI `Agent` with the system prompt and tool definitions 2. Messages are sent via `Runner.run_streamed()` 3. The SDK handles multi-turn tool calling automatically 4. Responses stream back as `AgentEvent` objects 5. Session history is managed via `SQLiteSession` for multi-turn context ## Installation ```bash pip install pocketpaw[openai-agents] ``` This installs the `openai-agents` package as an optional dependency. ## Related ### [Ollama: Free Local Models](/backends/ollama) [Run the OpenAI Agents backend with local models via Ollama.](/backends/ollama) ### [Claude Agent SDK](/backends/claude-sdk) [The recommended backend with native tools and MCP integration.](/backends/claude-sdk) ### [All Agent Backends](/backends) [Compare all six backends side by side with capability badges.](/backends) ### [Local LLM Agent Guide](/guides/local-llm-agent) [Step-by-step guide to running PocketPaw with local models.](/guides/local-llm-agent) Last updated: April 29, 2026 2 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/backends/openai-agents.mdx) Was this page helpful? Yes No --- # OpenCode: External Server Backend via REST > The OpenCode backend connects to an external OpenCode server via REST API. A lightweight, thin-client option for teams already running OpenCode as a separate service. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page The OpenCode backend connects to an external **OpenCode server** via REST API. It’s a lightweight option for teams that already run OpenCode as a separate service. ## Overview * **Status**: Beta * **Provider support**: External server (model managed by OpenCode) * **Built-in tools**: Server-managed (no PocketPaw-side tool definitions) * **MCP support**: No * **Architecture**: HTTP client — communicates with a running OpenCode server ## Prerequisites Install and start the OpenCode server: ```bash # Install the OpenCode Go binary go install github.com/opencode-ai/opencode@latest # Start in server mode opencode --server ``` The server runs on `http://localhost:4096` by default. ## Configuration ```bash export POCKETPAW_AGENT_BACKEND="opencode" ``` ### Backend-Specific Settings | Setting | Env Variable | Default | Description | | -------------------- | ------------------------------ | ------------------------- | ------------------- | | `opencode_base_url` | `POCKETPAW_OPENCODE_BASE_URL` | `"http://localhost:4096"` | OpenCode server URL | | `opencode_model` | `POCKETPAW_OPENCODE_MODEL` | `""` (server default) | Model override | | `opencode_max_turns` | `POCKETPAW_OPENCODE_MAX_TURNS` | `0` (unlimited) | Max turns per query | ## How It Works 1. PocketPaw creates a session via `POST /session` → receives a session ID 2. Messages are sent via `POST /session/{id}/message` 3. Responses stream as NDJSON (newline-delimited JSON) 4. PocketPaw parses the NDJSON stream into `AgentEvent` objects 5. A health check (`GET /`) verifies the server is reachable before each request ## API Endpoints Used | Method | Endpoint | Purpose | | ------ | ----------------------- | ---------------------------------- | | `POST` | `/session` | Create a new session | | `POST` | `/session/{id}/message` | Send a message and stream response | | `GET` | `/` | Health check | ## When to Use Choose OpenCode when: * You already run OpenCode as a separate service * You want a backend where the model and tools are managed externally * You prefer a thin client architecture with PocketPaw as the frontend ## Related ### [Claude Agent SDK](/backends/claude-sdk) [The recommended backend with native tools and MCP integration.](/backends/claude-sdk) ### [Copilot SDK](/backends/copilot-sdk) [Another multi-provider backend with built-in git tools.](/backends/copilot-sdk) ### [All Agent Backends](/backends) [Compare all six backends side by side with capability badges.](/backends) ### [Self-Host PocketPaw](/guides/self-host-ai-agent) [Deploy PocketPaw on your own infrastructure.](/guides/self-host-ai-agent) Last updated: April 29, 2026 1 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/backends/opencode.mdx) Was this page helpful? Yes No --- # Channels Overview > Connect PocketPaw to 9+ messaging platforms simultaneously: Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Teams, Google Chat, and the built-in web dashboard. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page PocketPaw connects to multiple messaging platforms through **channel adapters**. Each adapter translates between the platform’s native protocol and PocketPaw’s internal message bus. ## Supported Channels ### [Web Dashboard](/channels/web-dashboard) [Built-in real-time web interface with streaming, sessions, and tool activity.](/channels/web-dashboard) ### [Telegram](/channels/telegram) [Full bot API with topic support, inline keyboards, and streaming via edit-in-place.](/channels/telegram) ### [Discord](/channels/discord) [Slash commands, DM and mention support, streaming with edit-in-place.](/channels/discord) ### [Slack](/channels/slack) [Socket Mode (no public URL needed), thread support, app\_mention events.](/channels/slack) ### [WhatsApp](/channels/whatsapp) [Business API or Personal mode via QR scan. No Meta account needed for personal.](/channels/whatsapp) ### [Signal](/channels/signal) [Privacy-focused messaging via signal-cli REST API.](/channels/signal) ### [Matrix](/channels/matrix) [Decentralized, federated protocol via matrix-nio.](/channels/matrix) ### [Microsoft Teams](/channels/teams) [Bot Framework SDK integration for enterprise collaboration.](/channels/teams) ### [Google Chat](/channels/google-chat) [Webhook and Pub/Sub modes via Google Chat API.](/channels/google-chat) ## Running Channels ### Web Dashboard (Default) The web dashboard is the default mode. Simply run: ```bash pocketpaw ``` The dashboard auto-starts all configured channel adapters on startup. You can manage channels from the Channels modal in the sidebar. ### Headless Mode Run specific channels without the web dashboard: ```bash # Single channel pocketpaw --telegram pocketpaw --discord pocketpaw --slack # Multiple channels pocketpaw --discord --slack --whatsapp # All channel flags pocketpaw --telegram --discord --slack --whatsapp --signal --matrix --teams --gchat ``` ### Channel Management API The web dashboard exposes REST endpoints for channel management: | Endpoint | Method | Description | | ---------------------- | ------ | -------------------------- | | `/api/channels/status` | GET | Get status of all channels | | `/api/channels/save` | POST | Save channel configuration | | `/api/channels/toggle` | POST | Start or stop a channel | ## Streaming Behavior Each channel handles streaming differently based on platform limitations: | Channel | Streaming Method | | ------------- | ------------------------------- | | Web Dashboard | Real-time WebSocket chunks | | Telegram | Edit-in-place (message updates) | | Discord | Edit-in-place (1.5s rate limit) | | Slack | Thread message updates | | WhatsApp | Accumulate + send on completion | | Signal | Accumulate + send on completion | | Matrix | Edit-in-place (m.replace) | | Teams | Accumulate + send on completion | | Google Chat | Accumulate + send on completion | ## Channel-Specific Session Keys Each channel generates unique session keys to maintain separate conversations: * **Telegram**: `{chat_id}` or `{chat_id}:topic:{topic_id}` * **Discord**: `{channel_id}` or `dm:{user_id}` * **Slack**: `{channel_id}:{thread_ts}` * **WhatsApp**: `{phone_number}` * **Signal**: `{phone_number}` * **Matrix**: `{room_id}` * **Teams**: `{conversation_id}` * **Google Chat**: `{space_name}` ## Access Control Each channel supports allow-listing to restrict who can interact with your agent: ```bash # Telegram export POCKETPAW_ALLOWED_TELEGRAM_IDS="123456,789012" # Discord export POCKETPAW_DISCORD_ALLOWED_GUILD_IDS="111,222" export POCKETPAW_DISCORD_ALLOWED_USER_IDS="333,444" # Slack export POCKETPAW_SLACK_ALLOWED_CHANNEL_IDS="C01,C02" # WhatsApp export POCKETPAW_WHATSAPP_ALLOWED_PHONE_NUMBERS="+1234567890" ``` ## Guides Step-by-step tutorials for setting up specific channels: ### [Build a Telegram AI Bot](/guides/telegram-ai-bot) [Create a personal AI assistant on Telegram in 5 minutes.](/guides/telegram-ai-bot) ### [Discord AI Bot](/guides/discord-ai-bot) [Add an AI assistant to your Discord server with slash commands.](/guides/discord-ai-bot) ### [Self-Host Guide](/guides/self-host-ai-agent) [Run your own AI agent on a laptop or home server.](/guides/self-host-ai-agent) Last updated: April 29, 2026 2 min read [ Edit this page](https://github.com/pocketpaw/pocketpaw/edit/main/docs/channels/index.mdx) Was this page helpful? Yes No --- # Discord Bot Setup: Add PocketPaw to Your Server > Run PocketPaw as a Discord bot with /paw slash commands, DM and mention support, streaming responses with edit-in-place, and configurable guild and user allow-lists. Copy page Copy as MarkdownCopy page content for LLM Open in ChatGPTAsk ChatGPT about this page Open in ClaudeAsk Claude about this page PocketPaw integrates with Discord via `discli` (Discord CLI agent). It supports slash commands, direct messages, @mention in channels, and full server management through an MCP-based tool layer that works across all agent backends. ## Setup ### Create a Discord application 1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) 2. Click “New Application” and name it 3. Go to the **Bot** section and create a bot 4. Copy the bot token Under **Privileged Gateway Intents**, enable: * **Message Content Intent** (required for reading messages and conversation mode) ### Set permissions Under OAuth2 → URL Generator, select: * Scopes: `bot`, `applications.commands` * Permissions: `Send Messages`, `Read Message History`, `Use Slash Commands`, `Embed Links`, `Attach Files` ### Invite to server Use the generated URL to invite the bot to your Discord server. ### Configure ```bash export POCKETPAW_DISCORD_BOT_TOKEN="your-discord-token" ``` ### Start ```bash pocketpaw --discord ``` ## Configuration | Setting | Env Variable | Description | | ----------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- | | Bot token | `POCKETPAW_DISCORD_BOT_TOKEN` | Discord bot token (required) | | Allowed guilds | `POCKETPAW_DISCORD_ALLOWED_GUILD_IDS` | Comma-separated guild IDs | | Allowed users | `POCKETPAW_DISCORD_ALLOWED_USER_IDS` | Comma-separated user IDs | | Allowed channels | `POCKETPAW_DISCORD_ALLOWED_CHANNEL_IDS` | Comma-separated channel IDs | | Conversation channels | `POCKETPAW_DISCORD_CONVERSATION_CHANNEL_IDS` | Channels with conversation mode enabled via env | | Conversation all channels | `POCKETPAW_DISCORD_CONVERSATION_ALL_CHANNELS` | Enable conversation mode server-wide (`true`/`false`) | | Conversation exclude channels | `POCKETPAW_DISCORD_CONVERSATION_EXCLUDE_CHANNEL_IDS` | Channels to exclude from server-wide conversation mode | | Bot name | `POCKETPAW_DISCORD_BOT_NAME` | Display name used in conversation prompts (default: `Paw`) | | Status type | `POCKETPAW_DISCORD_STATUS_TYPE` | Bot presence status: `online`, `idle`, `dnd`, or `invisible` | | Activity type | `POCKETPAW_DISCORD_ACTIVITY_TYPE` | Activity type: `playing`, `streaming`, `listening`, or `watching` | | Activity text | `POCKETPAW_DISCORD_ACTIVITY_TEXT` | Text shown next to the activity type | ## Features ### Slash Command The bot registers a `/paw` slash command. Users can interact with: ```plaintext /paw What files are in the home directory? ``` ### DM and Mention Support * **Direct messages** — Send a DM to the bot for private conversations * **@mention** — Mention the bot in any channel where it’s present ### Streaming Discord supports edit-in-place streaming with a 1.5-second rate limit. The bot sends an initial message and edits it as tokens arrive, batching updates to respect Discord’s rate limits. ### Access Control ```bash # Restrict to specific servers export POCKETPAW_DISCORD_ALLOWED_GUILD_IDS="111222333,444555666" # Restrict to specific users export POCKETPAW_DISCORD_ALLOWED_USER_IDS="777888999" ``` ### Conversation Mode Conversation mode lets the bot participate naturally in group channels without requiring explicit mentions or slash commands. When enabled for a channel, the bot: * **Tracks recent messages** in a rolling 30-message window * **Decides when to respond** based on context: responds when addressed by name, when it’s part of an active conversation, or when someone asks a question while it’s recently active * **Stays silent when appropriate** by returning a `[NO_RESPONSE]` marker that the adapter suppresses, allowing natural “lurking” * **Injects conversation context** from the last 30 messages (up to 12,000 characters) into the agent prompt for natural, context-aware replies **Per-channel:** Use the `/converse` slash command in any channel (requires Administrator or Manage Server permission). Run it again to toggle off. **Server-wide:** Enable conversation mode across all channels at once via environment variable: ```bash export POCKETPAW_DISCORD_CONVERSATION_ALL_CHANNELS=true # Optionally exclude specific channels (e.g. announcements, rules) export POCKETPAW_DISCORD_CONVERSATION_EXCLUDE_CHANNEL_IDS="123456789,987654321" ``` Idle channels are automatically cleaned up after 1 hour of inactivity. ### Bot Presence Customize the bot’s online status and activity in Discord: ```bash export POCKETPAW_DISCORD_STATUS_TYPE=online # online, idle, dnd, invisible export POCKETPAW_DISCORD_ACTIVITY_TYPE=watching # playing, streaming, listening, watching export POCKETPAW_DISCORD_ACTIVITY_TEXT="your code" ``` This shows the bot as “Watching your code” in the member list. ### Slash Commands | Command | Description | | ------------------ | ------------------------------------------------------------------ | | `/paw ` | Send a message to the AI agent | | `/new` | Start a fresh conversation | | `/sessions` | List your conversation sessions | | `/resume ` | Resume a previous session | | `/clear` | Clear the current session history | | `/rename