\n\n# PiClaw\n\n**PiClaw is your personal AI OS in the browser.**\nSpin it up, open a chat, and you’ve got a persistent coding agent with memory, tools, files, terminal tabs, and external channels.\n\n
\n \n
\n
\n \n
\n
\n \n
\n\n> [!NOTE]\n> This project is in private beta. Feel free to try it at your own risk, but please don't share it publicly.\n>\n> Join the [Discord](https://discord.gg/dwywNcnZ) for feedback!\n\n## 🚀 Quick Start\n\nChoose one of the options below.\n\n### Option A: Run on host (fastest)\n\n**Prerequisite:** [Node.js](https://nodejs.org/en/download) or [Bun](https://bun.sh/)\n\n```sh\n# Node.js\nnpx -y piclaw@latest\n\n# Bun\nbunx piclaw@latest\n```\n\nThen open: **http://localhost:3737**\n\n> [!TIP]\n> PiClaw stores state in `~/.pi/claw`.\n\n### Option B: Run with Docker (recommended)\n\n**Prerequisite:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) or [OrbStack](https://orbstack.dev/)\n\nThis keeps PiClaw isolated from your host environment.\n\n```sh\ndocker run -it -p 3737:3737 -v piclaw:/home/pi ghcr.io/pi0/piclaw:latest\n```\n\n> [!TIP]\n> `/home/pi` is a default volume — data persists even without `-v`. The named volume (`piclaw`) just makes it easier to find and manage.\n\nThen open: **http://localhost:3737**\n\n**Docker Compose:**\n\n```yaml\nservices:\n piclaw:\n image: ghcr.io/pi0/piclaw:latest\n ports: [\"3737:3737\"]\n volumes: [\"piclaw:/home/pi\"]\n restart: unless-stopped\n\nvolumes:\n piclaw:\n```\n\n## ⚡ Feature tour\n\n### 🖥️ AI + Desktop\n\n- Desktop-like UI multi window system\n- Launcher + taskbar workflow\n- Mobile-friendly full-screen experience\n- Quick welcome screen to get you online fast\n- Optional PWA install prompt for app-like usage\n\n### 💬 Multi-chat, multi-group, multi-context\n\nEach group/chat has its own:\n\n- agent session\n- workspace folder\n- persisted memory + session state\n- model + thinking settings\n- optional persona/soul (custom role injected into system prompt)\n\nTrigger behavior is configurable:\n\n- **Trigger off:** process every message\n- **Trigger on:** process only `@assistant-name ...`\n\n### 🛠️ Agent tools\n\nEvery agent session comes with built-in tools:\n\n- **Code tools** — read, write, edit files + bash execution scoped to group workspace\n- **Terminal** — create/exec/read/write PTY sessions programmatically\n- **Web search** — query the web (Brave API) and fetch page content as markdown\n- **Browser** — open, navigate, and manage browser tabs in the admin UI\n- **Notes** — markdown notes organized by category for persistent knowledge\n- **Notify** — send push notifications (ntfy.sh) with priority, tags, and actions\n- **Message** — inter-group messaging lets agents communicate across groups\n\n### 🤖 Serious agent controls\n\nConfigure providers and model behavior from the UI (no config-file spelunking needed):\n\n- **OAuth providers:** Anthropic (Claude Pro/Max), GitHub Copilot, Antigravity (Gemini 3, Claude, GPT-OSS), Google Cloud Code Assist (Gemini CLI), ChatGPT Plus/Pro (Codex Subscription)\n- **API key providers:** Anthropic, OpenAI, Vercel AI Gateway, OpenRouter, Kimi, OpenCode Zen, Azure OpenAI, Google Gemini, Mistral, Groq, Cerebras, xAI, ZAI, MiniMax, Hugging Face\n\nPer-chat command controls include:\n\n- `/model` → list/set model\n- `/thinking` → tune reasoning depth\n- `/compact` → compact active context\n- `/stop` + `/new` → immediate session control\n- `/info` + `/help` → inspect current runtime state\n- `! ` → quick bash execution from chat\n\n### 📡 Real-time streaming + tool telemetry\n\n- Token-by-token response streaming into chat UI\n- Live tool lifecycle events (tool start/end)\n- Crash-safe cursor/session recovery after restarts\n- Logs window for fast diagnosis\n\n### 📁 Files + editor + viewer built in\n\n- Group-scoped file browser\n- In-app editor and file viewer windows\n- Live file change watching (SSE)\n- Keyboard navigation in file explorer\n\n### ⬛ Persistent terminal tabs\n\n- Real PTY terminal sessions in the dashboard\n- Sessions survive window close/reopen\n- Label sync + reconnect across views\n- Sandboxed virtual terminal mode (powered by [just-bash](https://justbash.dev/))\n\n### ⏰ Scheduler + automation hooks\n\n- One-time and recurring task scheduling\n- Attach tasks to specific chat groups\n- Automated prompts executed by the right agent context\n\n### 🖼️ Image attachments\n\n- Send images in chat via file picker, clipboard paste, or drag-and-drop\n- Thumbnail previews in compose area\n- Telegram inbound photo/document support\n\n### 📲 External channels + notifications\n\n- Telegram bot integration (DMs + groups)\n- Adaptive Telegram streaming throttling\n- ntfy push notifications\n\n### 🔒 Device authentication\n\n- No-password device-based auth (httpOnly cookies)\n- First device auto-approved, subsequent devices need approval\n- Device management UI (approve/revoke)\n\n### 🌐 Localtunnel\n\n- Expose PiClaw via a public URL with one click\n- Subdomain support + auto-reconnect on boot\n- Setup and status via admin UI\n\n### 📊 Resource monitoring\n\n- Live CPU, memory, and disk usage graphs\n- Process list with CPU/RAM breakdown\n- Port monitoring and process management\n\n### 📝 Notes\n\n- Markdown notes organized by category\n- Agent-accessible for persistent knowledge storage\n- Browse, read, edit, and delete from admin UI\n\n### 🎨 Personalization\n\n- Wallpapers + desktop appearance settings\n- Dash density/size preferences\n- Clean, modern typography and icon set\n\n## 🧱 Built with\n\n- [Pi SDK](https://github.com/badlogic/pi-mono) — Agents SDK\n- [Nitro](https://nitro.build) and [H3](https://h3.dev/) — Server\n- [Vite](https://vite.dev/) and [Rolldown](https://rolldown.rs/) — Builder\n- [Vue.js](https://vuejs.org/) — UI\n- [WinBox](https://nextapps-de.github.io/winbox/) — window manager (modernized fork)\n- [Md4x](https://github.com/pi0/md4x) - Markdown rendering and parsing\n- [Modern Monaco](https://github.com/esm-dev/modern-monaco) — code editor\n- [Visual JSON](https://github.com/vercel-labs/visual-json) — schema-aware JSON editor\n- [Xterm.js](https://github.com/xtermjs/xterm.js) and [zigpty](https://github.com/pithings/zigpty) — terminal\n- [just-bash](https://justbash.dev/) — sandboxed bash for virtual terminal\n- [Electrobun](https://electrobun.dev/) — desktop app packaging\n- [Geist](https://vercel.com/font) — typography (Sans, Mono, Pixel)\n- [Iconify](https://github.com/iconify/iconify) — icons\n\n## 💡 Inspired by\n\n- [Apple Design](https://developer.apple.com/design/resources/)\n- [OpenClaw](https://github.com/openclaw/openclaw) and [Nanoclaw](https://github.com/user/nanoclaw)\n\n## License\n\n[MIT](./LICENSE) — Made with ❤️ by [@pi0](https://github.com/pi0)\n","readmeFilename":"README.md"}
![\"PiClaw](\"./public/icon.svg\"){kind=icon}
![\"PiClaw](\"./website/public/shot2.png\")
\n![\"PiClaw](\"./website/public/shot3.png\")
\n![\"PiClaw](\"./website/public/shot4.jpg\")
\n