Languages: English · 简体中文 · 日本語
PiClaw packages the Pi Coding Agent into a self-hosted workspace with a trilingual streaming web UI, persistent state, multi-provider LLM support, and built-in tools. Optional add-ons extend the runtime and web UI.
Run it locally or in a container as one stateful agent workspace.
| Capability | Details |
|---|---|
| Web workspace | Chat, editor, terminal, viewers, uploads, and automation in the same UI |
| Persistent state | SQLite-backed messages, media, tasks, token usage, encrypted keychain, and session-scoped SSH profiles |
| Built-in tools | Code editing, CSV/PDF/image/video viewing, VNC, browser automation, image processing, MCP, and optional cross-instance IPC for paired remote peers |
| Agent workflows | Steering, queued follow-ups, side prompts, scheduled tasks, and visual artifact generation; the optional autoresearch add-on supplies experiment loops |
| Staged tool loading | A small always-active tool set with discovery through list_tools and list_scripts |
| Optional authentication and channels | Passkeys or TOTP for the web UI, plus optional WhatsApp integration |
| Optional add-ons | Extra tools, skills, viewers, terminals, settings panes, Draw.io, Office document rendering and tools, Windows desktop automation, Proxmox, and Portainer |
mkdir -p ./home ./workspace
docker run -d \
--init \
--name piclaw \
--restart unless-stopped \
-p 8080:8080 \
-e PICLAW_WEB_PORT=8080 \
-v "$(pwd)/home:/config" \
-v "$(pwd)/workspace:/workspace" \
ghcr.io/rcarmo/piclaw:latestOpen http://localhost:8080 and type /login to configure your LLM provider, including custom OpenAI-compatible endpoints. The web UI ships with English, Simplified Chinese, and Japanese strings; switch languages in Settings.
Tip
Keep --init enabled for docker run / podman run so the runtime inserts a tiny init process for signal forwarding and zombie reaping. The bundled docker-compose.yml now sets the equivalent init: true flag.
| Mount | Container path | Contents |
|---|---|---|
| Home | /config |
Persistent Pi state (.pi/) and Git configuration (.gitconfig) |
| Workspace | /workspace |
Projects, notes, and piclaw state |
Note
In the container image, /home/agent/.pi is backed by /config/.pi. With the docker run example above or the bundled docker-compose.yml, Pi home state persists on the host under ./home/.pi/agent/.
That means provider login state and model metadata should survive rebuilds/recreates when stored under files such as:
./home/.pi/agent/auth.json./home/.pi/agent/models.json
Warning
Never delete /workspace/.piclaw/store/messages.db. It is the source of truth for chat history, media, tasks and run logs, token usage, encrypted keychain entries, passkeys, web sessions, chat branches, and remote-peer state.
Important
You do not need to set provider API keys in piclaw environment variables. PiClaw reuses provider credentials configured in Pi Agent settings.
Note
Workspace-scoped shell environment overrides can go in /workspace/.env.sh. PiClaw sources that file for the embedded terminal and during runtime startup. Use it for settings such as PATH changes or a persistent GitHub CLI directory with GH_CONFIG_DIR=/workspace/.config/gh. Invalid contents can break startup, shell behavior, or tool resolution.
PiClaw is single-user, mobile-friendly, and streams updates over SSE.
| Area | Highlights |
|---|---|
| Chat | Thought/draft panels, steering, queued follow-ups, Adaptive Cards, /btw, link previews, threaded turns, recovery/timeout chips |
| Language | English, Simplified Chinese, and Japanese UI strings with a Settings language switcher |
| Status UX | Tool/intended status stays visible during silence probing, recent activity restores useful context, and tool rows can show compact x ago hints in the meta row |
| Workspace | Sidebar browser, drag-and-drop uploads, file-reference pills, explorer search/reindex status |
| Editor | CodeMirror 6, search/replace, dirty-state tracking, syntax highlighting, lazy local bundle |
| Terminal | Bundled xterm.js web terminal as dock or tab; detachable popouts; Ghostty is available separately as an optional add-on |
| Viewers | Built-in CSV/TSV, PDF, image, video, code-preview, and VNC panes; optional add-ons supply Draw.io, the Office viewer backend, and kanban support |
| Automation | Built-in image_process, cdp_browser, and mcp; experimental m365; /image and /flux when Azure OpenAI/Foundry is configured; Windows desktop automation through the optional win-ui add-on |
For the full feature tour, see docs/web-ui.md.
Note
The bundled xterm.js implementation is the default terminal renderer. The Ghostty/WASM renderer is available separately through the optional @rcarmo/piclaw-addon-ghostty-terminal add-on.
Common environment variables:
| Variable | Default | Purpose |
|---|---|---|
PICLAW_WEB_PORT |
8080 |
Web UI port |
PICLAW_WEB_TERMINAL_ENABLED |
1 on Linux/macOS, 0 on Windows |
Enable or disable the authenticated bundled web terminal |
PICLAW_WEB_VNC_ALLOW_DIRECT |
1 on Linux/macOS/Windows |
Allow or disable direct VNC targets supplied at runtime |
PICLAW_WEB_TOTP_SECRET |
(empty) | Base32 TOTP secret; enables login gate (or initialize with /totp) |
PICLAW_WEB_PASSKEY_MODE |
totp-fallback |
totp-fallback, passkey-only, or totp-only |
PICLAW_ASSISTANT_NAME |
PiClaw |
Display name in the UI |
PICLAW_ENABLE_M365_EXPERIMENTAL |
0 |
Enable the experimental Microsoft 365 extension bundle |
PICLAW_KEYCHAIN_KEY |
(empty) | Master key for encrypted secret storage |
PICLAW_TRUST_PROXY |
0 |
Enable when behind a reverse proxy or tunnel |
For the full list, TOTP/passkey setup, session-scoped SSH-backed remote tools, reverse proxy configuration, and the workspace environment hook, see docs/configuration.md.
bun add -g github:rcarmo/piclawExperimental. Linux/macOS/Windows. See docs/install-from-repo.md.
Windows support is experimental. Shell-like child processes run attached there (detached=false) so stdout and stderr remain capturable. Unix-like hosts use detached process groups so abort and shutdown can terminate the process tree.
PiClaw also has an optional Electrobun desktop wrapper around the existing local web UI:
bun run build:desktopThe desktop shell starts Piclaw on 127.0.0.1 using an available port starting at 18080, opens a native window, and stores its default workspace under the platform application-data directory. Set PICLAW_DESKTOP_URL to wrap an already-running Piclaw web server instead of starting one.
See docs/development.md.
| Area | Docs |
|---|---|
| Getting started | Configuration, Web UI, Install from repo |
| Operations | Azure VM deployment, Azure OpenAI extension, Reverse proxy, Release process |
| Runtime internals | Architecture, Pipelined smart compaction, Runtime flows, Runtime stream sessions, Storage model, Observability |
| UI extension model | Web pane extensions, Extension UI contract, Vendored widget libraries |
| Agent capabilities | Tools and skills, Visual artifact generator, MCP via pi-mcp-adapter, Keychain |
| Other references | Dream memory system, Thinking persistence, Web notification delivery policy, iOS PWA reference, WhatsApp, Cross-instance interop, Experimental M365 extension, Development |
| Platform study | Azure Functions feasibility study |
Work items and bug reports are tracked in GitHub Issues.
Use the issue templates and project board labels for lane definitions and triage taxonomy.
- pi.dev for the Pi core used by piclaw
- rcarmo/agentbox
- qwibitai/nanoclaw
- badlogic/pi-mono
- davebcn87/pi-autoresearch — autonomous experiment loop by Tobi Lutke and David Cortés (now carried by the autoresearch add-on in
rcarmo/piclaw-addons) - nicobailon/visual-explainer — visual artifact generation skill philosophy, prompt workflow, and template patterns by Nico Bailon (adapted, not vendored)
Note
piclaw is not directly affiliated with pi.dev. It is a derivative work built on the Pi core and adds its own runtime, tooling, and UI layers.
MIT