{"id":45037529,"url":"https://github.com/rcarmo/piclaw","last_synced_at":"2026-05-07T01:15:41.802Z","repository":{"id":339055440,"uuid":"1160289313","full_name":"rcarmo/piclaw","owner":"rcarmo","description":"I'm going to build my own OpenClaw, with blackjack... and bun!","archived":false,"fork":false,"pushed_at":"2026-04-22T07:03:18.000Z","size":119608,"stargazers_count":547,"open_issues_count":1,"forks_count":38,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-04-22T08:03:58.422Z","etag":null,"topics":["adaptive-cards","ai-agent","bun","coding-agent","docker","llm","pi-agent","self-hosted","typescript","vnc","web-ui","workspace"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rcarmo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-17T19:06:49.000Z","updated_at":"2026-04-22T07:03:20.000Z","dependencies_parsed_at":"2026-02-22T10:00:45.529Z","dependency_job_id":"9150e47c-023e-41dd-b80a-27f0db9caf8b","html_url":"https://github.com/rcarmo/piclaw","commit_stats":null,"previous_names":["rcarmo/piclaw"],"tags_count":74,"template":false,"template_full_name":null,"purl":"pkg:github/rcarmo/piclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcarmo%2Fpiclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcarmo%2Fpiclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcarmo%2Fpiclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcarmo%2Fpiclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rcarmo","download_url":"https://codeload.github.com/rcarmo/piclaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rcarmo%2Fpiclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32278249,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adaptive-cards","ai-agent","bun","coding-agent","docker","llm","pi-agent","self-hosted","typescript","vnc","web-ui","workspace"],"created_at":"2026-02-19T07:16:18.033Z","updated_at":"2026-05-07T01:15:41.796Z","avatar_url":"https://github.com/rcarmo.png","language":"TypeScript","funding_links":[],"categories":["Personal Assistants","Agent Frameworks"],"sub_categories":[],"readme":"# `piclaw` — your self-hosted AI workspace\n\n![PiClaw](docs/icon-256.png)\n\nPiClaw packages the [Pi Coding Agent](https://github.com/badlogic/pi-mono) 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](https://rcarmo.github.io/piclaw-addons/).\n\nIt 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.\n\n## Why PiClaw\n\n![Demo Animation](docs/demo.gif)\n\n- **One workspace, one app** — chat, editor, terminal, viewers, boards, uploads, and automation in the same web UI\n- **Persistent state** — SQLite-backed messages, media, tasks, token usage, encrypted keychain, and session-scoped SSH / Proxmox / Portainer profiles\n- **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\n- **Agent-first workflows** — steering, queued follow-ups, side prompts, autoresearch loops, scheduled tasks, and visual artifact generation\n- **Context conservation** — small always-active tool baseline with staged discovery via `list_tools` / `list_scripts`\n- **Optional auth/channels** — passkeys/TOTP for the web UI, plus optional WhatsApp integration\n\n## Quick start\n\n```bash\nmkdir -p ./home ./workspace\n\ndocker run -d \\\n  --init \\\n  --name piclaw \\\n  --restart unless-stopped \\\n  -p 8080:8080 \\\n  -e PICLAW_WEB_PORT=8080 \\\n  -v \"$(pwd)/home:/config\" \\\n  -v \"$(pwd)/workspace:/workspace\" \\\n  ghcr.io/rcarmo/piclaw:latest\n```\n\nOpen `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.\n\n\u003e [!TIP]\n\u003e 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.\n\n| Mount | Container path | Contents |\n|---|---|---|\n| Home | `/config` | Agent home (`.pi/`, `.gitconfig`, `.bashrc`) |\n| Workspace | `/workspace` | Projects, notes, and piclaw state |\n\n\u003e [!NOTE]\n\u003e 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/`.\n\u003e\n\u003e That means provider login state and model metadata should survive rebuilds/recreates when stored under files such as:\n\u003e\n\u003e - `./home/.pi/agent/auth.json`\n\u003e - `./home/.pi/agent/models.json`\n\u003e\n\u003e 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.\n\n\u003e [!WARNING]\n\u003e Never delete `/workspace/.piclaw/store/messages.db`. It contains chat history, media, and task state.\n\n\u003e [!IMPORTANT]\n\u003e You do **not** need to set provider API keys in piclaw environment variables. PiClaw reuses provider credentials configured in Pi Agent settings.\n\n\u003e [!NOTE]\n\u003e 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.\n\n## Web UI at a glance\n\nPiClaw is single-user, mobile-friendly, and streams updates over SSE.\n\n| Area | Highlights |\n|---|---|\n| Chat | Thought/draft panels, steering, queued follow-ups, Adaptive Cards, `/btw`, link previews, threaded turns, recovery/timeout chips |\n| 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 |\n| Workspace | Sidebar browser, drag-and-drop uploads, file-reference pills, explorer search/reindex status |\n| Editor | CodeMirror 6, search/replace, dirty-state tracking, syntax highlighting, lazy local bundle |\n| Terminal | Ghostty-based web terminal as dock or tab; detachable popouts |\n| Viewers | Draw.io, Office docs, CSV/TSV, PDF, images, video, code previews, kanban boards, mindmaps, VNC |\n| Automation | `/image`, `/flux`, `image_process`, `cdp_browser`, `mcp`, experimental `m365`, Windows-only `win_*` tools |\n\nFor the full feature tour, see [docs/web-ui.md](docs/web-ui.md).\n\n## Configuration\n\nMost users only need a few environment variables:\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `PICLAW_WEB_PORT` | `8080` | Web UI port |\n| `PICLAW_WEB_TERMINAL_ENABLED` | `1` on Linux/macOS, `0` on Windows | Enable or disable the authenticated Ghostty-based web terminal |\n| `PICLAW_WEB_VNC_ALLOW_DIRECT` | `1` on Linux/macOS/Windows | Allow or disable direct VNC targets supplied at runtime |\n| `PICLAW_WEB_TOTP_SECRET` | _(empty)_ | Base32 TOTP secret; enables login gate (or initialize with `/totp`) |\n| `PICLAW_WEB_PASSKEY_MODE` | `totp-fallback` | `totp-fallback`, `passkey-only`, or `totp-only` |\n| `PICLAW_ASSISTANT_NAME` | `PiClaw` | Display name in the UI |\n| `PICLAW_ENABLE_M365_EXPERIMENTAL` | `0` | Enable the experimental Microsoft 365 extension bundle |\n| `PICLAW_KEYCHAIN_KEY` | _(empty)_ | Master key for encrypted secret storage |\n| `PICLAW_TRUST_PROXY` | `0` | Enable when behind a reverse proxy or tunnel |\n\nFor 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](docs/configuration.md).\n\n## Other install methods\n\n### Install without Docker\n\n```bash\nbun add -g github:rcarmo/piclaw\n```\n\nExperimental. Linux/macOS/Windows. See [docs/install-from-repo.md](docs/install-from-repo.md).\n\nOn 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.\n\n### Experimental desktop shell\n\nPiClaw also has an optional Electrobun desktop wrapper around the existing local web UI:\n\n```bash\nbun run build:desktop\n```\n\nThe 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.\n\n### Build from source\n\nSee [docs/development.md](docs/development.md).\n\n## Documentation\n\n| Area | Docs |\n|---|---|\n| Getting started | [Configuration](docs/configuration.md), [Web UI](docs/web-ui.md), [Install from repo](docs/install-from-repo.md) |\n| Operations | [Azure VM deployment](docs/azure/README.md), [Reverse proxy](docs/reverse-proxy.md), [Release process](docs/release.md) |\n| Runtime internals | [Architecture](docs/architecture.md), [Runtime flows](docs/runtime-flows.md), [Runtime stream sessions](docs/runtime-stream-sessions.md), [Storage model](docs/storage.md), [Observability](docs/observability.md) |\n| UI extension model | [Web pane extensions](docs/web-pane-extensions.md), [Extension UI contract](docs/extension-ui-contract.md), [Vendored widget libraries](docs/vendored-widget-libraries.md) |\n| Agent capabilities | [Tools and skills](docs/tools-and-skills.md), [Visual artifact generator](docs/visual-artifact-generator.md), [MCP via pi-mcp-adapter](docs/mcp.md), [Keychain](docs/keychain.md) |\n| Other references | [Dream memory system](docs/dream-memory.md), [Web notification delivery policy](docs/web-notification-delivery-policy.md), [iOS PWA reference](docs/PWA.md), [WhatsApp](docs/whatsapp.md), [Cross-instance interop](docs/cross-instance-ipc.md), [Experimental M365 extension](docs/m365-experimental-extension.md), [Development](docs/development.md) |\n| Platform study | [Azure Functions feasibility study](docs/azure/azure-functions-feasibility-study-2026-04-17.md) |\n\n## Contributing\n\nWork items and bug reports are tracked in **[GitHub Issues](https://github.com/rcarmo/piclaw/issues)**.\n\n- [Open a work item or bug report](https://github.com/rcarmo/piclaw/issues/new?template=workitem.md)\n- [Ask a question](https://github.com/rcarmo/piclaw/issues/new?template=question.md)\n- [View the project board](https://github.com/users/rcarmo/projects/13)\n\nSee [WORKITEMS.md](WORKITEMS.md) for board lane definitions and label taxonomy.\n\n## Credits\n\n- [pi.dev](http://pi.dev) for a stupendously flexible and extensible core\n- [rcarmo/agentbox](https://github.com/rcarmo/agentbox)\n- [qwibitai/nanoclaw](https://github.com/qwibitai/nanoclaw)\n- [badlogic/pi-mono](https://github.com/badlogic/pi-mono)\n- [davebcn87/pi-autoresearch](https://github.com/davebcn87/pi-autoresearch) — autonomous experiment loop by Tobi Lutke and David Cortés (now carried by the autoresearch add-on in `rcarmo/piclaw-addons`)\n- [nicobailon/visual-explainer](https://github.com/nicobailon/visual-explainer) — visual artifact generation skill philosophy, prompt workflow, and template patterns by Nico Bailon (adapted, not vendored)\n\n\u003e [!NOTE]\n\u003e piclaw is **not** directly affiliated with [pi.dev](https://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.\n\n## Licence\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frcarmo%2Fpiclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frcarmo%2Fpiclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frcarmo%2Fpiclaw/lists"}