piclaw

PiClaw

PiClaw is your personal AI OS in the browser. Spin it up, open a chat, and you’ve got a persistent coding agent with memory, tools, files, terminal tabs, and external channels.

[!NOTE] This project is in private beta. Feel free to try it at your own risk, but please don't share it publicly.

Join the Discord for feedback!

🚀 Quick Start

Choose one of the options below.

Option A: Run on host (fastest)

Prerequisite: Node.js or Bun

# Node.js
npx -y piclaw@latest

# Bun
bunx piclaw@latest

Then open: http://localhost:3737

[!TIP] PiClaw stores state in ~/.pi/claw.

Option B: Run with Docker (recommended)

Prerequisite: Docker Desktop or OrbStack

This keeps PiClaw isolated from your host environment.

docker run -it -p 3737:3737 -v piclaw:/home/pi ghcr.io/pi0/piclaw:latest

[!TIP] /home/pi is a default volume — data persists even without -v. The named volume (piclaw) just makes it easier to find and manage.

Then open: http://localhost:3737

Docker Compose:

services:
  piclaw:
    image: ghcr.io/pi0/piclaw:latest
    ports: ["3737:3737"]
    volumes: ["piclaw:/home/pi"]
    restart: unless-stopped

volumes:
  piclaw:

⚡ Feature tour

🖥️ AI + Desktop

• Desktop-like UI multi window system
• Launcher + taskbar workflow
• Mobile-friendly full-screen experience
• Quick welcome screen to get you online fast
• Optional PWA install prompt for app-like usage

💬 Multi-chat, multi-group, multi-context

Each group/chat has its own:

• agent session
• workspace folder
• persisted memory + session state
• model + thinking settings
• optional persona/soul (custom role injected into system prompt)

Trigger behavior is configurable:

• Trigger off: process every message
• Trigger on: process only @assistant-name ...

🛠️ Agent tools

Every agent session comes with built-in tools:

• Code tools — read, write, edit files + bash execution scoped to group workspace
• Terminal — create/exec/read/write PTY sessions programmatically
• Web search — query the web (Brave API) and fetch page content as markdown
• Browser — open, navigate, and manage browser tabs in the admin UI
• Notes — markdown notes organized by category for persistent knowledge
• Notify — send push notifications (ntfy.sh) with priority, tags, and actions
• Message — inter-group messaging lets agents communicate across groups

🤖 Serious agent controls

Configure providers and model behavior from the UI (no config-file spelunking needed):

• 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)
• API key providers: Anthropic, OpenAI, Vercel AI Gateway, OpenRouter, Kimi, OpenCode Zen, Azure OpenAI, Google Gemini, Mistral, Groq, Cerebras, xAI, ZAI, MiniMax, Hugging Face

Per-chat command controls include:

• /model → list/set model
• /thinking → tune reasoning depth
• /compact → compact active context
• /stop + /new → immediate session control
• /info + /help → inspect current runtime state
• ! <cmd> → quick bash execution from chat

📡 Real-time streaming + tool telemetry

• Token-by-token response streaming into chat UI
• Live tool lifecycle events (tool start/end)
• Crash-safe cursor/session recovery after restarts
• Logs window for fast diagnosis

📁 Files + editor + viewer built in

• Group-scoped file browser
• In-app editor and file viewer windows
• Live file change watching (SSE)
• Keyboard navigation in file explorer

⬛ Persistent terminal tabs

• Real PTY terminal sessions in the dashboard
• Sessions survive window close/reopen
• Label sync + reconnect across views
• Sandboxed virtual terminal mode (powered by just-bash)

⏰ Scheduler + automation hooks

• One-time and recurring task scheduling
• Attach tasks to specific chat groups
• Automated prompts executed by the right agent context

🖼️ Image attachments

• Send images in chat via file picker, clipboard paste, or drag-and-drop
• Thumbnail previews in compose area
• Telegram inbound photo/document support

📲 External channels + notifications

• Telegram bot integration (DMs + groups)
• Adaptive Telegram streaming throttling
• ntfy push notifications

🔒 Device authentication

• No-password device-based auth (httpOnly cookies)
• First device auto-approved, subsequent devices need approval
• Device management UI (approve/revoke)

🌐 Localtunnel

• Expose PiClaw via a public URL with one click
• Subdomain support + auto-reconnect on boot
• Setup and status via admin UI

📊 Resource monitoring

• Live CPU, memory, and disk usage graphs
• Process list with CPU/RAM breakdown
• Port monitoring and process management

📝 Notes

• Markdown notes organized by category
• Agent-accessible for persistent knowledge storage
• Browse, read, edit, and delete from admin UI

🎨 Personalization

• Wallpapers + desktop appearance settings
• Dash density/size preferences
• Clean, modern typography and icon set

🧱 Built with

• Pi SDK — Agents SDK
• Nitro and H3 — Server
• Vite and Rolldown — Builder
• Vue.js — UI
• WinBox — window manager (modernized fork)
• Md4x - Markdown rendering and parsing
• Modern Monaco — code editor
• Visual JSON — schema-aware JSON editor
• Xterm.js and zigpty — terminal
• just-bash — sandboxed bash for virtual terminal
• Electrobun — desktop app packaging
• Geist — typography (Sans, Mono, Pixel)
• Iconify — icons

💡 Inspired by

• Apple Design
• OpenClaw and Nanoclaw

License

MIT — Made with ❤️ by @pi0