+
+
+
+```
+
+### State Management
+
+Stores are singleton class instances using `$state` and `$derived`:
+
+```typescript
+// src/lib/stores/example.svelte.ts
+class ExampleStore {
+ items = $state([]);
+ loading = $state(false);
+ count = $derived(this.items.length);
+
+ async load() {
+ this.loading = true;
+ this.items = await api.getItems();
+ this.loading = false;
+ }
+}
+
+export const exampleStore = new ExampleStore();
+```
+
+### API Layer
+
+The REST client handles authentication and retries:
+
+```typescript
+import { client } from '$lib/api/client';
+
+// GET request
+const sessions = await client.get('/sessions');
+
+// POST with body
+const result = await client.post('/chat', { message: 'Hello' });
+
+// Streaming via SSE
+const stream = client.stream('/chat/stream', { message: 'Hello' });
+for await (const event of stream) {
+ // handle chunks
+}
+```
+
+## Contributing
+
+1. Create a feature branch off `dev`
+2. Make your changes in `client/`
+3. Run `bun run check` to verify type safety
+4. Test with `bun run tauri dev`
+5. Open a PR targeting `dev`
+
+See the [Contributing Guide](https://github.com/pocketpaw/pocketpaw/blob/dev/CONTRIBUTING.md) for full details.
+
+
+
+ Architecture and feature overview.
+
+
+ REST and WebSocket API documentation.
+
+
diff --git a/docs/desktop-client/index.mdx b/docs/desktop-client/index.mdx
new file mode 100644
index 00000000..3126e59c
--- /dev/null
+++ b/docs/desktop-client/index.mdx
@@ -0,0 +1,99 @@
+---
+title: "Desktop Client: Native App for PocketPaw"
+description: "PocketPaw's native desktop app built with Tauri and SvelteKit. System tray, global shortcuts, multi-window support, and one-click backend installation."
+section: Desktop Client
+ogType: article
+keywords: ["pocketpaw desktop", "tauri app", "sveltekit desktop", "native ai client", "desktop ai agent"]
+tags: ["desktop", "client", "tauri", "sveltekit"]
+---
+
+# Desktop Client
+
+The PocketPaw desktop client is a native application built with **Tauri 2.0** and **SvelteKit**. It connects to the Python backend over REST and WebSocket, providing a polished native experience on Windows, macOS, and Linux.
+
+## Why a Desktop App?
+
+The web dashboard works great in a browser, but a native app unlocks features that browsers can't provide:
+
+- **System tray** with quick access menu and background operation
+- **Global keyboard shortcuts** that work even when the app isn't focused
+- **Multi-window support** with a side panel and quick-ask popup
+- **One-click installation** that sets up the Python backend automatically
+- **Auto-updates** via Tauri's built-in updater
+- **Native notifications** for reminders, task completions, and agent alerts
+
+## Downloads
+
+| Platform | Download |
+| --- | --- |
+| **Windows** | [PocketPaw-Setup.exe](https://github.com/pocketpaw/pocketpaw/releases/latest/download/PocketPaw-Setup.exe) |
+| **macOS** | [PocketPaw.dmg](https://github.com/pocketpaw/pocketpaw/releases/latest/download/PocketPaw.dmg) |
+| **Linux** | [PocketPaw.AppImage](https://github.com/pocketpaw/pocketpaw/releases/latest/download/PocketPaw.AppImage) |
+
+## Architecture
+
+The client is split into two layers:
+
+### Frontend (SvelteKit)
+
+- **SvelteKit 2** with **Svelte 5** runes for reactive state management
+- **Tailwind CSS 4** with oklch-based design tokens
+- **shadcn-svelte** (bits-ui) component library
+- Static SPA mode (no SSR), bundled into the Tauri shell
+
+### Rust Backend (Tauri)
+
+- **System tray** with Open, Quick Ask, Settings, and Quit actions
+- **Close-to-tray** behavior (window hides instead of closing)
+- **Multi-window management** for side panel and quick-ask windows
+- **Global shortcuts** registered from the frontend
+- **OAuth token storage** and IPC commands
+
+### How It Connects
+
+The desktop client communicates with the PocketPaw Python backend (running on `localhost:8888`) through:
+
+1. **REST API** (`/api/v1/`) for CRUD operations (sessions, settings, memory, etc.)
+2. **WebSocket** (`/api/v1/ws`) for real-time streaming (chat responses, system events)
+3. **SSE** (`/api/v1/chat/stream`) for chat message streaming
+
+Authentication uses an OAuth2 PKCE flow or a master access token read from `~/.pocketpaw/access_token`.
+
+## Key Features
+
+### Onboarding Wizard
+
+First-time users get a guided setup that:
+1. Detects if the Python backend is installed
+2. Offers one-click installation (downloads and configures Python + PocketPaw)
+3. Walks through API key configuration
+4. Connects to the running backend
+
+### Chat Interface
+
+Full-featured chat with:
+- Real-time streaming responses
+- Tool call visualization (tool start, result, thinking indicators)
+- Code block syntax highlighting via CodeMirror
+- File attachment support
+- Session management (create, rename, delete, search, export)
+
+### Side Panel
+
+A compact secondary window for quick interactions without leaving your current task. Accessible via global shortcut or system tray.
+
+### Quick Ask
+
+A lightweight popup window for fast one-off questions. Opens and closes instantly.
+
+
+
+ Download and set up the desktop app.
+
+
+ Build and contribute to the desktop client.
+
+
+ Run the headless API server for external clients.
+
+
diff --git a/docs/desktop-client/installation.mdx b/docs/desktop-client/installation.mdx
new file mode 100644
index 00000000..9aeef8e7
--- /dev/null
+++ b/docs/desktop-client/installation.mdx
@@ -0,0 +1,111 @@
+---
+title: "Desktop Client Installation: Download and Setup"
+description: "Install the PocketPaw desktop app on Windows, macOS, or Linux. Includes one-click backend setup and manual installation options."
+section: Desktop Client
+ogType: article
+keywords: ["pocketpaw install", "desktop app download", "tauri install", "pocketpaw setup"]
+tags: ["desktop", "installation", "setup"]
+---
+
+# Desktop Client Installation
+
+## Download
+
+Grab the latest release for your platform:
+
+| Platform | Download | Format |
+| --- | --- | --- |
+| **Windows** | [PocketPaw-Setup.exe](https://github.com/pocketpaw/pocketpaw/releases/latest/download/PocketPaw-Setup.exe) | NSIS installer |
+| **macOS** | [PocketPaw.dmg](https://github.com/pocketpaw/pocketpaw/releases/latest/download/PocketPaw.dmg) | DMG disk image |
+| **Linux** | [PocketPaw.AppImage](https://github.com/pocketpaw/pocketpaw/releases/latest/download/PocketPaw.AppImage) | AppImage |
+
+## First Launch
+
+When you open the desktop app for the first time, the onboarding wizard will guide you through setup:
+
+
+
+ **Backend Detection** - The app checks if the PocketPaw Python backend is installed on your machine. If found, it connects automatically.
+
+
+ **One-Click Install** (if needed) - If the backend isn't installed, the app offers to set it up for you. This downloads Python (if needed) and installs PocketPaw via pip.
+
+
+ **API Key Configuration** - Enter your Anthropic API key (or configure Ollama for free local inference). You can skip this and add it later from Settings.
+
+
+ **Ready to Chat** - The app connects to the backend and opens the chat interface. You're good to go.
+
+
+
+## Requirements
+
+### All Platforms
+
+- The PocketPaw Python backend must be running on `localhost:8888` (the app can install it for you)
+- An LLM provider API key (Anthropic, OpenAI, etc.) or Ollama for local inference
+
+### Windows
+
+- Windows 10 or later
+- WebView2 runtime (included in Windows 10 1803+ and Windows 11)
+
+### macOS
+
+- macOS 10.15 (Catalina) or later
+
+### Linux
+
+- WebKitGTK 4.1+
+- `libappindicator3` (for system tray support)
+
+## Manual Backend Setup
+
+If you prefer to install the backend separately:
+
+```bash
+# Install via pip
+pip install pocketpaw
+
+# Or use uv
+uv pip install pocketpaw
+
+# Start the backend
+pocketpaw
+```
+
+The desktop app will automatically detect the running backend on `localhost:8888`.
+
+## Running the API Server
+
+For headless operation (no web dashboard), use the `serve` command:
+
+```bash
+pocketpaw serve
+```
+
+This starts the REST API and WebSocket server without serving the web dashboard frontend. The desktop client connects to it the same way. See the [API Server guide](/desktop-client/api-server) for details.
+
+## Auto-Updates
+
+The desktop app checks for updates automatically via GitHub releases. When an update is available, you'll see a notification with the option to download and install it.
+
+## Uninstalling
+
+### Windows
+Use "Add or Remove Programs" in Windows Settings, or run the uninstaller from the Start Menu.
+
+### macOS
+Drag PocketPaw from Applications to the Trash.
+
+### Linux
+Delete the AppImage file. Remove `~/.local/share/com.pocketpaw.app/` for app data.
+
+
+
+ Get up and running with PocketPaw in 5 minutes.
+
+
+ Configure API keys, backends, and channels.
+
+
diff --git a/docs/docs-config.json b/docs/docs-config.json
index 251f0144..e2d1479b 100644
--- a/docs/docs-config.json
+++ b/docs/docs-config.json
@@ -1,7 +1,7 @@
{
"metadata": {
"name": "PocketPaw",
- "description": "Self-hosted AI agent controlled via Telegram, Discord, Slack, WhatsApp, or a web dashboard",
+ "description": "Self-hosted AI agent with a native desktop app. Controlled via Telegram, Discord, Slack, WhatsApp, or a web dashboard.",
"url": "https://pocketpaw.xyz",
"version": "1.0.0"
},
@@ -114,7 +114,7 @@
"label": "Documentation",
"href": "/introduction",
"icon": "lucide:book-open",
- "groups": ["Introduction", "Getting Started", "Guides", "Core Concepts", "Channels", "Agent Backends", "Tools", "Integrations", "Security", "Memory", "Advanced", "Deployment"]
+ "groups": ["Introduction", "Getting Started", "Guides", "Core Concepts", "Desktop Client", "Channels", "Agent Backends", "Tools", "Integrations", "Security", "Memory", "Advanced", "Deployment"]
},
{
"label": "API Reference",
@@ -206,6 +206,31 @@
}
]
},
+ {
+ "label": "Desktop Client",
+ "items": [
+ {
+ "label": "Overview",
+ "href": "/desktop-client",
+ "icon": "lucide:monitor"
+ },
+ {
+ "label": "Installation",
+ "href": "/desktop-client/installation",
+ "icon": "lucide:download"
+ },
+ {
+ "label": "Development",
+ "href": "/desktop-client/development",
+ "icon": "lucide:code"
+ },
+ {
+ "label": "API Server (serve)",
+ "href": "/desktop-client/api-server",
+ "icon": "lucide:server"
+ }
+ ]
+ },
{
"label": "Core Concepts",
"items": [