PiClaw packages the Pi Coding Agent into a self-hosted workspace with a streaming web UI, persistent state, multi-provider LLM support, and a practical built-in toolset that includes many add-ons.
It is for people who want one stateful agent workspace they can run locally or in a container without stitching together half a dozen separate services.
Why PiClaw
One workspace, one app — chat, editor, terminal, viewers, boards, uploads, and automation in the same web UI
Persistent state — SQLite-backed messages, media, tasks, token usage, encrypted keychain, and session-scoped SSH / Proxmox / Portainer profiles
Practical built-ins — code editing, Office/PDF/CSV/image/video viewing, draw.io, VNC, browser automation, image processing, MCP, infra tools, and optional cross-instance IPC for paired remote peers
Agent-first workflows — steering, queued follow-ups, side prompts, autoresearch loops, scheduled tasks, and visual artifact generation
Context conservation — small always-active tool baseline with staged discovery via list_tools / list_scripts
Optional auth/channels — passkeys/TOTP for the web UI, plus optional WhatsApp integration
First-time install walkthrough for Claude Code, Codex CLI, and ChatGPT.
Open http://localhost:8080 and type /login to configure your LLM provider, including custom OpenAI-compatible endpoints when you are not using one of the built-in hosted providers.
[!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 | Agent home (.pi/, .gitconfig, .bashrc) |
| Workspace | /workspace | Projects, notes, and piclaw state |
[!NOTE]
In the container image, /home/agent/.pi is backed by /config/.pi. With the stock docker run / docker-compose.yml examples above, Pi home state therefore 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
Mounting directly to /home/agent or /home/agent/.pi/agent can also work, but /config is the canonical documented persistence path for the container image.
[!WARNING]
Never delete /workspace/.piclaw/store/messages.db. It contains chat history, media, and task 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]
Power users can place workspace-scoped shell environment overrides in /workspace/.env.sh. PiClaw sources that file for the embedded terminal and on runtime startup, which is useful for things like PATH tweaks or persisting gh auth login with GH_CONFIG_DIR=/workspace/.config/gh. This hook is user-controlled: if its contents break PiClaw startup, shell behavior, or tool resolution, that breakage is the user's responsibility.
Web UI at a glance
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 |
| 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 | Ghostty-based web terminal as dock or tab; detachable popouts |
| Viewers | Draw.io, Office docs, CSV/TSV, PDF, images, video, code previews, kanban boards, VNC |
| Automation | /image, /flux, image_process, cdp_browser, mcp, experimental m365, Windows-only win_* tools |
| 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 Ghostty-based 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, auth setup (TOTP/passkeys), session-scoped SSH-backed remote tools, reverse proxy configuration, SSHFS/FUSE support, and the workspace environment hook, see docs/configuration.md.
On Windows, PiClaw remains a secondary / not-officially-supported target. Shell-like child processes now run attached there (detached=false) so stdout/stderr remain capturable; Unix-like hosts still use detached process groups for cleaner tree termination on abort/shutdown.
Experimental desktop shell
PiClaw also has an optional Electrobun desktop wrapper around the existing local web UI:
bun run build:desktop
The 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.
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 that leverages all of its core Pi functionality and builds additional runtime, tooling, and UI layers around it.
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.
