* feat(cli): add 10 new subcommands for local agent management
New CLI commands:
- doctor: full diagnostics with connectivity checks
- health: quick startup-only health check (no network)
- channels: list channel status, start/stop adapters via REST
- skills: list and search available skills
- sessions: list, delete, and search chat sessions
- memory: show stats and search long-term memories
- config: show (masked), set, validate, path
- errors: show recent errors with --limit and --search
- logs: show/tail audit log with --follow
All commands support --json for scripting. Refactored __main__.py
to subcommand-based parser while keeping full backwards compat
with existing flags (--doctor, --telegram, --discord, etc).
* docs: add new CLI subcommands to CLAUDE.md
* docs: add CLI reference page with all subcommands
New docs page at getting-started/cli covering all 15+ CLI commands
with usage examples, flags, and descriptions. Added to sidebar nav
after Quick Start.
* feat: add LiteLLM provider support and unified env resolution
Add LiteLLM as a provider option for all backends (Claude SDK, OpenAI
Agents, Google ADK, Copilot SDK), enabling access to 100+ LLM providers
including HuggingFace, Ollama, vLLM, Together AI, Groq, Mistral, and
more through a single proxy or direct SDK integration.
Key changes:
- New config fields: litellm_api_base, litellm_api_key, litellm_model
- OpenAI Agents: native LitellmModel extension with proxy fallback
- Google ADK: LiteLlm model wrapper for cross-provider support
- Claude SDK: routes through LiteLLM proxy via ANTHROPIC_BASE_URL
- Copilot SDK: LiteLLM via OpenAI-compatible BYOK config
- resolve_backend_env() pushes unified POCKETPAW_* keys to env vars
each SDK expects, fixing the issue where switching backends required
manually reconfiguring environment variables
* fix: complete LiteLLM integration across dashboard, health checks, and WS
- Fix health check false warning: add 'litellm' to provider skip list
in check_api_key_primary() for Claude SDK, OpenAI Agents, and
Google ADK backends
- Add google_adk_provider to WS settings handler and broadcast
- Add litellm_api_base, litellm_api_key, litellm_model to WS handler
- Add 'LiteLLM (100+ Providers)' option to provider dropdowns in
settings UI for Claude SDK and OpenAI Agents backends
- Add LiteLLM config fields (proxy URL, API key, model) shown when
litellm provider is selected in the settings modal
* fix: add LiteLLM provider to Copilot SDK and Google ADK settings UI
- Add LiteLLM option to Copilot SDK provider dropdown
- Add provider dropdown to Google ADK settings (was missing entirely)
- Add LiteLLM config fields (proxy URL, API key, model) for Google ADK
when litellm provider is selected
* fix: sync env vars at runtime when API keys change via dashboard
resolve_backend_env() now accepts force=True to overwrite existing env
vars. Called after every settings/API-key save so backends immediately
see updated keys without a restart. Codex CLI subprocess gets an
explicit env snapshot via env=os.environ.copy().
* refactor: provider adapter pattern for LLM providers
Extract provider-specific logic (config resolution, client creation,
env var setup, error formatting) into adapter classes under
llm/providers/. Six adapters: Anthropic, Ollama, OpenAICompatible,
OpenRouter, Gemini, LiteLLM.
LLMClient delegates to adapters internally while keeping its public
API stable. Backends (OpenAI Agents, Google ADK, Copilot SDK) now use
adapters directly, replacing 70+ line if/elif chains with ~5 line
adapter calls. Adding a new provider means adding one adapter file
and registering it, no backend changes needed.
30 new tests for adapters, registry, model resolution, and LLMClient
delegation.
* fix: _stderr_lines UnboundLocalError and test_fast_path failures
Move _stderr_lines initialization before the try block so the except
handler can always access it. Add missing _HookMatcher and is_litellm
to test mocks.
* style: format test files and fix UP038 lint
* docs: add Discord deployment config with multi-provider support
Add Docker Compose, Dockerfile, env example, and identity files for
headless Discord bot deployment. Supports direct Anthropic, LiteLLM
proxy, OpenAI-compatible, and OpenAI Agents backends out of the box.
* chore: remove Discord deploy files (moved to separate PR #597)
Deploy config now lives under deploy/discord/ in the
deploy/discord-docker branch to keep this PR focused on
the provider adapter pattern and LiteLLM integration.
* fix: LiteLLM max_tokens setting, config persistence, and health recheck
- Add litellm_max_tokens config option so users can cap output tokens
for models like DeepSeek (8192 limit)
- Fix LiteLLM settings not persisting on reload: litellmApiBase,
litellmModel, litellmMaxTokens were missing from SETTINGS_MAP in
app.js, so the frontend never loaded them back from the server
- Also add 13 other missing backend settings to SETTINGS_MAP
(openaiAgentsModel, googleAdkProvider, codexCliModel, etc.)
- Re-run health checks after settings save so switching to LiteLLM
immediately clears the "no Anthropic API key" degraded warning
- Claude SDK fast-path respects provider max_tokens instead of
hardcoding 1024
* fix: LiteLLM proxy routing, adapter bugs, and remove plan docs
- Fix LiteLLM + OpenAI Agents: use OpenAI-compat proxy path when
base_url is set instead of native LitellmModel which tried to route
directly (causing Vertex AI credential errors)
- Fix operator precedence in _to_provider_config() base_url resolution
- Fix dashboard unable to clear LiteLLM API key (falsy vs None check)
- Fix fragile hasattr duck-typing in openai_agents, add explicit
provider == "litellm" guard
- Replace unnecessary getattr() with direct attribute access in
google_adk now that the field exists in Settings
- Pass api_key and base_url to ADK LiteLlm wrapper explicitly
- Remove plan design doc
* docs: add OpenRouter and LiteLLM provider documentation
- Add dedicated OpenRouter and LiteLLM sections to LLM providers guide
with configuration examples for proxy vs direct SDK mode
- Update backend compatibility matrix to include both new providers
- Update per-backend provider tables (Claude SDK, OpenAI Agents,
Google ADK, Copilot SDK) with LiteLLM and OpenRouter support
- Add OpenRouter and LiteLLM config fields to configuration reference
- Update getting-started configuration with OpenRouter and LiteLLM
environment variable examples
- Replace OpenRouter-only section in backends index with combined
OpenRouter + LiteLLM section
Comprehensive SEO optimization across 80 documentation pages:
Title optimization (all pages):
- Replaced generic titles like "Architecture", "Discord", "Slack"
with search-intent titles like "PocketPaw Architecture: Event-Driven
Message Bus", "Discord Bot Setup: Add PocketPaw to Your Server"
- All titles now 50-70 characters with qualifying keywords
Meta descriptions:
- Expanded 7 short descriptions (under 145 chars) to 150-160 chars
- Roadmap description expanded from 76 to 196 chars
- Troubleshooting, Codex CLI, OpenCode, WebMCP all expanded
H1 heading fixes:
- Ensured single H1 per page matching the frontmatter title
- All H1 headings updated to match new optimized titles
Internal cross-links:
- Added Related CardGroup sections to 60+ individual pages
- Each links to 2-3 related pages within and across sections
- Channels link to channel guides, backends link to Ollama guide, etc.
Em dash cleanup:
- Replaced em dashes with colons, periods, or double hyphens
across multiple files in tools/, channels/, integrations/
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(agents): add backend protocol, registry, and capability system
Introduce the foundational types for the multi-SDK architecture:
- AgentBackend Protocol with info() staticmethod and async run() generator
- BackendInfo dataclass (name, description, capabilities, config fields)
- Capability flag enum (STREAMING, TOOLS, MCP, MULTI_TURN, CUSTOM_SYSTEM_PROMPT)
- AgentEvent dataclass replacing raw dicts for backend output
- Lazy-import backend registry with _LEGACY_BACKENDS for graceful migration
* refactor(agents): update Claude SDK backend to new protocol
Rename ClaudeAgentSDK to ClaudeSDKBackend, add info() staticmethod
returning BackendInfo with capability flags, rename _SDK_TO_POLICY
to _TOOL_POLICY_MAP. Backward-compat alias preserved.
* refactor(agents): remove legacy backends
Remove pocketpaw_native, open_interpreter, and claude_code backends
along with their associated test files (test_mcp_native, verify_oi_direct).
These are replaced by the new multi-SDK backend architecture.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat(agents): add OpenAI Agents backend
Runner.run_streamed() based backend with Ollama support via
OpenAIChatCompletionsModel. Yields AgentEvent for streaming.
* feat(agents): add Google ADK backend with tool bridge
Native Google ADK SDK integration using LlmAgent + InMemoryRunner.
MCP support via McpToolset. tool_bridge.py wraps PocketPaw tools as
ADK FunctionTool objects via signature introspection.
Replaces the old gemini_cli subprocess wrapper.
* feat(agents): add OpenCode backend
Subprocess wrapper for the OpenCode Go binary.
Streams stdout/stderr as AgentEvent.
* feat(agents): add Codex CLI backend
Subprocess wrapper for the Codex CLI tool.
Supports streaming output as AgentEvent.
* feat(agents): add Copilot SDK backend
Microsoft Copilot SDK integration with streaming support.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(agents): router uses registry, loop uses AgentEvent
Router now delegates to registry.get_backend_class() instead of
if/elif chain. AgentLoop consumes AgentEvent from backends
(event.type, event.content, event.metadata) instead of raw dicts.
* feat(config): add per-backend model and settings fields
New config fields: openai_agents_model, openai_agents_max_turns,
google_adk_model, google_adk_max_turns, opencode_model,
opencode_max_turns, codex_cli_model, copilot_sdk_model.
All added to Settings.save() dict.
* feat(dashboard): backend selector with capability badges
Add /api/backends endpoint returning registered backends with
capabilities. Dynamic dropdown in settings modal replaces hardcoded
backend list. Capability badges (streaming, tools, MCP, etc.)
displayed per backend. Frontend updated accordingly.
* refactor: update health, MCP, bootstrap for new backend system
Health checks reference new backend names. MCP manager updated for
registry-based backend detection. Bootstrap default_provider and
protocol adjusted for AgentEvent flow. CLI tools updated.
* test: update existing tests for architecture v2
Update mock paths and assertions for renamed backends, AgentEvent
protocol, and registry-based routing. Add test_channel_autostart.py
for dashboard channel auto-start behavior.
* chore(deps): add openai-agents, google-adk, and backend extras
New optional dependency groups: openai-agents, google-adk.
Updated uv.lock with resolved dependencies.
* feat: add stop button to cancel in-flight agent responses
Wire up session-aware task tracking in AgentLoop so the web dashboard
can cancel a running response mid-stream.
- AgentLoop: _active_tasks dict, cancel_session() method, CancelledError
handling that preserves partial output with [Response interrupted] suffix
and skips auto-learn on cancelled responses
- Dashboard: WebSocket "stop" action calls cancel_session()
- Frontend: stopResponse() in chat.js/websocket.js, send/stop button swap
via Alpine x-show in chat.html
Closes#244
* feat: add /backend, /backends, /model, /tools slash commands
Enable users on messaging channels (Telegram, Discord, Slack, etc.) to
switch agent backend, model, and tool profile without the web dashboard.
- Add 4 new commands to CommandHandler with settings mutation + callback
- Wire settings-changed callback in AgentLoop to reset router on switch
- Register commands in Telegram, Discord, and Slack adapters
- Add 31 new tests covering all commands and callback mechanism
* feat(deps): add copilot-sdk to optional dependencies
* feat(backends): mark all non-Claude agent backends as beta
Add `beta` field to BackendInfo dataclass and set it for OpenAI Agents,
Google ADK, OpenCode, Codex CLI, and Copilot SDK backends. Claude Agent
SDK remains stable (beta=False). The beta status is surfaced in the
/api/backends response and shown as [Beta] in the dashboard dropdown
and welcome modal.
* chore(config): update default models to latest and set max_turns to 0
Models updated:
- Anthropic: claude-sonnet-4-5-20250929 → claude-sonnet-4-6
- OpenAI: gpt-4o → gpt-5.2
- Gemini: gemini-2.5-flash → gemini-2.5-pro
- Codex CLI: o4-mini → gpt-5.3-codex
- Copilot SDK fallback: gpt-4o → gpt-5.2
- Model router moderate tier: claude-sonnet-4-6
Max turns default changed from 25 to 0 (unlimited) across all backends.
Backend code updated to skip turn limits when max_turns is 0.
* chore(config): upgrade default Gemini model to gemini-3-pro-preview
Replace gemini-2.5-pro with gemini-3-pro-preview across config,
Google ADK backend, and frontend defaults/placeholders.
* test: remove 12 consistently failing tests
- test_app_returns_object: stale check for removed `messages:` property
- test_installer_version_matches: installer/pyproject version drift
- test_installer_prompt_fallback (7 tests): import-order dependent failures
- test_preflight_check_raises/mentions_vpn: neonize mock state leaks
- test_get_directory_keyboard_returns_markup: telegram import side effects
Full suite now passes: 2100 passed, 0 failed.
* fix(google-adk): enforce MCP server tool policy filtering
Google ADK backend's _build_mcp_toolsets() was passing all enabled MCP
servers to the agent without checking ToolPolicy, unlike the Claude SDK
backend which correctly filters via is_mcp_server_allowed(). This meant
deny rules like "mcp:server:*" or "group:mcp" had no effect on ADK.
* fix: resolve /backends Telegram parse error and slash command routing in web dashboard
- Escape underscores in capability names (/backends output) to prevent
Telegram Markdown entity parse errors
- Add parse_mode fallback in Telegram adapter: retry without formatting
on entity parse failure
- Enhance channel format hints with detailed per-channel formatting rules
so the LLM generates native-format output directly
- Fix /backend, /model, /tools not working in web dashboard: frontend now
checks skill registry before intercepting / commands, and backend
run_skill handler forwards unknown commands to the message bus
* feat: add branded preloader to prevent FOUC on dashboard load
Inline paw-print SVG + progress bar renders instantly before external
CSS/fonts/scripts arrive, then fades out on window load.
* docs: update all docs for 6-backend architecture, slim down README
- Replace 3 deleted backends (PocketPaw Native, Open Interpreter, Gemini CLI)
with 6 current backends (Claude SDK, OpenAI Agents, Google ADK, Codex CLI,
OpenCode, Copilot SDK) across all docs
- Add new backend doc pages: openai-agents, google-adk, codex-cli, opencode,
copilot-sdk
- Remove deleted backend pages: pocketpaw-native.mdx, open-interpreter.mdx
- Update docs-config.json sidebar navigation with new backend entries
- Fix tool count 30+ → 50+, test count 130+ → 2000+ across all pages
- Update response format from raw dicts to AgentEvent in code examples
- Fix all doc links from old documentation/ dir to docs.pocketpaw.xyz
- Condense README from ~460 to ~230 lines: collapse Docker/extras into
details, merge feature rows, trim verbose sections
- Add star history chart and contributor graph to README
* fix: enforce API key auth for Claude SDK backend, block OAuth fallback
Anthropic's policy prohibits third-party applications from using OAuth
tokens from Free/Pro/Max plans. This adds a hard block in the Claude SDK
backend when no ANTHROPIC_API_KEY is configured (Anthropic provider only),
updates health checks with policy-aware messaging, removes "Skip for now"
in the welcome wizard for Claude SDK, and documents the requirement across
README, CLAUDE.md, and all relevant docs pages.
* docs: expand README install section with platform-specific instructions
Add desktop app download table (macOS .dmg, Windows .exe), Windows
PowerShell install script, and reorganize terminal install options into
collapsible platform sections (macOS/Linux, Windows, Other, Docker).
* docs: remove 'recommended' label from desktop app section
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: default max_turns to 100 instead of unlimited (0)
Prevents runaway agent loops from burning API credits silently. 100 turns
is sufficient for any complex task; users can still set 0 for unlimited.
Addresses PR #243 review feedback.
---------
- backends/claude-sdk: add Claude SDK Settings section with model
override, max turns, and callouts about auto-select vs smart routing
- advanced/model-router: note disabled by default, add configuration
env vars, update callout text
- api/configuration-reference: add claude_sdk_model, claude_sdk_max_turns,
smart_routing_enabled, and model tier settings to the table
- getting-started/configuration: add Claude SDK env vars and config.json
fields with info callout
- README: update smart router description, add SDK fields to config example
- CLAUDE.md: mention SDK-specific settings in backend description
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Complete the package rename: src/pocketclaw/ → src/pocketpaw/,
all imports, pyproject.toml entry point, docs code examples,
installer references, and test patch targets updated.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Complete the user-facing rename from pocketclaw to pocketpaw across
env vars, Docker paths (~/.pocketclaw → ~/.pocketpaw), and all
documentation references.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds a production-ready Dockerfile (multi-stage, non-root user, Playwright
Chromium, tesseract OCR) and docker-compose.yml with optional Ollama and
Qdrant services behind Compose profiles. Includes .env.example template,
.dockerignore, and updated README + docs.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Consolidate duplicated provider detection, AsyncAnthropic client creation,
env var construction, and error formatting into a single LLMClient dataclass
with a resolve_llm_client() factory. Refactor 10 consumer files to use it.
- New llm/client.py: LLMClient frozen dataclass + resolve_llm_client()
- Claude SDK backend: Ollama env vars via llm.to_sdk_env(), --check-ollama CLI
- PocketPaw Native: replace _llm_provider tracking with LLMClient
- Security modules: force_provider="anthropic" for Guardian + InjectionScanner
- Dashboard: Ollama settings UI, provider selection
- Docs: Ollama backend documentation
- Tests: 19 new LLMClient tests, updated Ollama + concurrency tests
Closes#53
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace colon with em dash in frontmatter description to prevent
Astro from misinterpreting "layout: src/pocketclaw" as a layout
directive, which caused the page to render without HTML structure.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Consolidate documentation from the separate pocketpaw-web repo into the
main pocketpaw repo. This keeps docs and code in sync so PRs can update
both atomically.
- Remove docs/ from .gitignore
- Remove docs' own .git (was pocketpaw/pocketpaw-web)
- Add .github/workflows/deploy-docs.yml (builds from docs/ subdirectory)
- Track all 120+ MDX pages, config, landing page, and public assets
The separate pocketpaw-web repo can now be archived.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
