PiClaw
A self-hosted, persistent Pi Coding Agent workspace with a streaming web interface and built-in developer tools.
- Source repo
- rcarmo/piclaw
- Stars
- ★ 886
- Last updated
- today
- License
- MIT
- Primary language
- TypeScript
- FA score
- 48/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A solo developer who wants a browser-based coding assistant, editor, and terminal on a self-hosted machine or server.
- Not a fit if
- Teams needing reliable Windows support; it is experimental there
- Users wanting a ready-made model with no provider login or setup
- Multi-user or team collaboration setups; PiClaw is single-user
- Source review
- 48/100 · Major gaps 1 safety controls not found
What does this agent do, and when should you use it?
PiClaw packages Pi Coding Agent as a single-user, self-hosted AI workspace with a streaming web UI. Its interface combines chat, code editing, a terminal, file browsing, uploads, and several viewers, with updates delivered over SSE. SQLite persists messages, media, tasks, run logs, token usage, encrypted keychain entries, and session-scoped SSH profiles. It can run in Docker or be installed globally with Bun, and it also offers an experimental Electrobun desktop wrapper. The product operates as a Pi runtime and tool-enabled local or containerized workspace, with optional add-ons extending both runtime and web UI.
A user drives Pi Coding Agent through the web chat while editing code, using the embedded xterm.js terminal, uploading files, and browsing the workspace in the same application. Built-in panes view CSV/TSV, PDF, images, video, code previews, and VNC targets; automation includes image_process, cdp_browser, and mcp. PiClaw stores messages, media, tasks, token usage, and run records in /workspace/.piclaw/store/messages.db, while Pi state is persisted under /config/.pi. Tool loading is staged: a small always-active set exposes further capabilities through list_tools and list_scripts. Chat workflows include steering, queued follow-ups, side prompts, and scheduled tasks.
- A solo developer who wants a browser-based coding assistant, editor, and terminal on a self-hosted machine or server.
- A developer using Docker who needs Pi login state, model metadata, and project files to survive container recreation.
- An engineer who needs a coding session to inspect CSV files, PDFs, images, videos, or a VNC desktop from the same workspace.
- A single-user workflow that needs scheduled tasks, follow-up instructions, chat branches, and retained run logs in one interface.
- A self-hosting user who needs a custom OpenAI-compatible endpoint or a local llama.cpp router preset.
How do you install or deploy this agent?
Create persistent directories, then run:
mkdir -p ./home ./workspacedocker 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:latestAn experimental alternative is bun add -g github:rcarmo/piclaw. The container route requires Docker; the global-install route requires Bun.
How do you use this agent?
Open http://localhost:8080, type /login in chat, and configure provider credentials in Pi Agent settings; provider API keys do not need to be set as PiClaw environment variables. Then send coding tasks in chat, browse projects and uploads in Workspace, or open the Terminal, CSV/TSV, PDF, image, video, and VNC panes. Deployment behavior can be configured with environment variables including PICLAW_WEB_PORT, PICLAW_WEB_TERMINAL_ENABLED, PICLAW_WEB_TOTP_SECRET, PICLAW_WEB_PASSKEY_MODE, PICLAW_KEYCHAIN_KEY, and PICLAW_TRUST_PROXY.
What are this agent's strengths and limitations?
- Combines Pi Coding Agent, chat, a CodeMirror 6 editor, an xterm.js terminal, and file viewers in one self-hosted interface.
- SQLite persistence covers chats, tasks, media, token usage, run logs, encrypted keychain entries, and session-scoped SSH profiles.
- Includes image_process, cdp_browser, mcp, VNC, and viewers for CSV/TSV, PDF, images, and video.
- Supports custom OpenAI-compatible endpoints and local llama.cpp router presets, with add-ons for runtime and UI extensions.
- Use depends on Pi Agent provider login and model configuration; the supplied material does not document an included model or free inference service.
- Windows support is explicitly experimental, and PICLAW_WEB_TERMINAL_ENABLED defaults to off on Windows.
- messages.db is the source of truth for chats, tasks, token records, keychain entries, and sessions, so deleting it loses that persisted data.
- Some capabilities require optional add-ons, including the Ghostty terminal, Draw.io, Office rendering, Windows desktop automation, Proxmox, and Portainer.
How does this agent compare with similar options?
PiClaw is a derivative built on the Pi Coding Agent core, adding its own runtime, tooling, and web UI layers; the repository states that it is not directly affiliated with pi.dev.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| PiClaw This agent | 48 · Major gaps | Self-hosted serviceFree + model costs | ★ 886 | today | TypeScript | OpenAI API |
| ZhikunCode | 56 · Major gaps | Self-hosted serviceFree + model costs | ★ 540 | 3d ago | Java | OpenAI API · Claude API |
| OtoDock | 77 · Good | Self-hosted serviceFreemium | ★ 197 | 1d ago | Python | Codex · Claude Code |
| CamoFox Browser Server | 72 · Some gaps | Self-hosted serviceFree | ★ 436 | 12d ago | JavaScript | Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows permission controls (e.g., external route registration restrictions, data directory escape checks) and user confirmation mechanisms (e.g., m365 extension dry-run/confirm parameters), but not comprehensively across all tools. Data flow transparency: documentation exists for storage and key management, but not all data flows detailed. Sensitive data handling: key management and RAM-only caches present, but not fully assessed. Dependency security: exact versions and overrides used, but no vulnerability scan evidence. External effects: external routes and browser automation present, but not explicitly limited. Rollback: not mentioned. Source attribution: copyright and license present, but publisher not verified.
Self-consistency: code and tests show consistent architecture and naming. Dependency availability: dependencies pinned, but availability not verified. Failure messages: tests show error handling, but not fully assessed.
Audience and scenarios: README clearly defines target users and use cases. Capability boundaries: tools and extensions documented, but not all boundaries explicit. Trigger precision: commands and tools defined, but trigger conditions not detailed. Environment fit: multiple installation methods and platforms supported, but Windows support limited.
Information architecture: documentation structure clear, multiple docs. Install notes: Docker and source install guides provided. Naming stability: version number clear, but no changelog. Examples and FAQ: examples present but no FAQ. Known limitations: partially mentioned (e.g., Windows support limited). License: MIT. Versioning and changelog: version number but no detailed changelog. Maintenance responsibility: GitHub Issues present, but maintainer not explicit.
Output usability: Web UI feature-rich, multiple output formats. Marginal value: integrated workspace with unique features. Cost-benefit: self-hosted, but no performance or resource data.
Claim traceability: README features supported by docs, but no test results. Cross-source corroboration: multiple docs and tests, but not independently verified. Fact-inference separation: docs distinguish experimental and stable features, but not all inferences labeled.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Publisher identity unverified; assess supply chain risk carefully.
- Dependencies pinned but no vulnerability scan evidence; run security audit.
- Some tools (e.g., browser automation, external routes) may pose security risks; ensure least privilege configuration.
- Windows support limited; may affect cross-platform deployment.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v3.3.4 PiClaw v3.3.4 — “Galaxy Quest”
Release notes excerpt
PiClaw v3.3.4 — “Galaxy Quest” The ship’s computer has received several clarifications. A status report must describe the turn currently on the bridge, a message must reach the conversation that actually exists, and an instruction to finish without tools must not include directions to the armoury. The crew may still improvise; the routing system should not. Credential handling receives similar attention. A locked storage compartment is distinguishable from an invalid access code, reducing the occasions on which the captain is invited to log in again because someone misplaced the cupboard. …View on GitHub ↗ -
v3.3.3 PiClaw v3.3.3 — “Batteries Not Included”
Release notes excerpt
PiClaw v3.3.3 — “Batteries Not Included” The maintenance department has repaired the phone’s Delete button, fitted the GPU gauges with better instruments, and clarified which doors an add-on may use. The desktop application has meanwhile left the building. Its historical releases remain available, but new releases will concentrate on the web interface, server, containers and portable command-line packages. …View on GitHub ↗ -
v3.3.2 PiClaw v3.3.2 — “Apollo 13”
Release notes excerpt
> Locally tested hotfix. Local qualification for #1619 passed before merging. The artifact-only release workflow skipped repeat test suites, UX, integration and image smoke checks. Source: c4c7f699aa8fa5afc7d10cd416609cb2cd10149b. Actor: piclaw-bot. [Artifact run](https://github.com/rcarmo/piclaw/actions/runs/38050535667). PiClaw v3.3.2 — “Apollo 13” …View on GitHub ↗