piclaw
by rcarmo
pi coding agent in a technicolor web trenchcoat
819stars
78forks
TypeScript
Added 3/31/2026
View on GitHubDownload ZIPScan for vulnerabilities
Requires a passing catalog security scan. Resolve the flagged issues and resubmit to enable featuring.
AI Agentsadaptive-cardsai-agentbuncoding-agentdockerllmpi-agentself-hostedtypescriptvncweb-uiworkspace
Installation
# Add to your Claude Code skills
git clone https://github.com/rcarmo/piclawGetting Started
Guides for using ai agents skills like piclaw.
- Caveman: Cut Claude Token Use by 65%How agent-side prompt compression works, when to use it, and when not to.
- What is an AI Skills Marketplace?Definitions, how marketplaces work, and how to choose between them in 2026.
- Getting Started with AI SkillsFirst-time install walkthrough for Claude Code, Codex CLI, and ChatGPT.
Security ReportWarning
Last scanned: 5/10/2026
{
"issues": [
{
"type": "npm-audit",
"message": "xlsx: Prototype Pollution in sheetJS",
"severity": "high"
}
],
"status": "WARNING",
"scannedAt": "2026-05-10T06:34:19.979Z",
"semgrepRan": false,
"npmAuditRan": true,
"pipAuditRan": true
}PiClaw — self-hosted AI workspace
[!IMPORTANT]
Temporary submission pause: Bug reports and pull-request submissions are disabled while we complete repository housekeeping and planning. Follow the draft Earendil-aligned agent harness integration ADR for the current work and reopening criteria.
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.
Capabilities
| 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 |
Quick start
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:latest
Open http://localhost:8080 and type /login to configure your LLM provider, including custom OpenAI-compatible endpoints and local llama.cpp router presets. The web UI ships with English, Simplified Chinese, and Japanese strings; switch languages in Settings.
[!TIP] Keep
--initenabled fordocker run/podman runso the runtime inserts a tiny init process for signal forwarding and zombie reaping. The bundleddocker-compose.ymlnow sets the equivalentinit: trueflag.
| 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/.piis backed by/config/.pi. With thedocker runexample above or the bundleddocker-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, and chat branches.
[!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 asPATHchanges or a persistent GitHub CLI directory withGH_CONFIG_DIR=/workspace/.config/gh. Invalid contents can break startup, shell behavior, or tool resolution.
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 |
| 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-terminaladd-on.
Configuration
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.
Other install methods
Install without Docker
bun add -g github:rcarmo/piclaw
Experimental. 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.
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.
Build from source
See docs/development.md.
Documentation
| Area | Docs |
|---|---|
| Getting started | Configuration, Web UI, Install from repo |
| Operations | Azure VM deployment, Azure OpenAI extension, Reverse proxy, Release process |
| Runtime internals | Architecture, Add-on runtime API, 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, Remote Peer add-on, Experimental M365 extension, Development |
| Platform study | Azure Functions feasibility study |
Contributing
Work items and bug reports are tracked in GitHub Issues.
Use the issue templates and project board labels for lane definitions and triage taxonomy.
Credi
Frequently Asked Questions
What is piclaw?
piclaw is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by rcarmo. pi coding agent in a technicolor web trenchcoat. It has 819 GitHub stars.
Is piclaw safe to use?
piclaw returned warnings in SkillsLLM's automated security scan. It has no critical vulnerabilities, but review the flagged issues in the Security Report section before adding it to your workflow.
How do I install piclaw?
Clone the repository with "git clone https://github.com/rcarmo/piclaw" and add it to your Claude Code skills directory (see the Installation section above).
What programming language is piclaw written in?
piclaw is primarily written in TypeScript. It is open-source under rcarmo on GitHub, so you can review or fork the full source.
Are there alternatives to piclaw?
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh piclaw against similar tools.
Comments (0)
to leave a comment.
No comments yet. Be the first to share your thoughts!
Related Skills
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
239,787
36,396
JavaScript
AI Agentsai-agentsanthropic
An agentic skills framework & software development methodology that works.
234,966
20,863
Shell
AI Agentsaibrainstorming
Fair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
200,415
60,102
TypeScript
MCP Serversaiapis
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
185,940
28,768
JavaScript
AI Agentsai-agentsanthropic
A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Grok Build & Hermes Agent. Only official website: ccswitch.io
126,799
8,655
Rust
AI Agentsai-toolsclaude-code