PersonalClaw

PersonalClaw

Your self-hosted personal AI agent — an agentic operating system for one person.

Chat, autonomous goal loops, long-term memory, a knowledge base, skills, scheduled automation, and channel integrations — all behind one gateway process and one web dashboard you own. Local-first, provider-agnostic, no analytics, MIT.

[](https://github.com/PersonalClaw/PersonalClaw/actions/workflows/full.yml?query=branch%3Amain) [](LICENSE) [](pyproject.toml) [](#privacy) [](#) [](#-pre-10-heads-up)

The dashboard — tasks, active work, and context-aware suggestions at a glance. Dark theme shown; PersonalClaw ships light and dark.

📸 See the full visual showcase » — dashboard, chat, goal loops, knowledge, memory, tasks, skills, automation, agents, and settings, in light and dark.

---

⚠️ Pre-1.0 — breaking changes expected

PersonalClaw is at v0.1.3 and moving fast toward a deeper architecture (see the roadmap). It follows a clean-break engineering doctrine: when a design is replaced, the old path is removed in the same change rather than carried along behind compatibility shims. The upshot for you as an early user:

• **The next few minor (0.x) releases may introduce breaking changes with no automatic

migration of your existing data** — sessions, memory, knowledge, config, and app state under ~/.personalclaw may need to be recreated after an update.

• Back up before every update. Run personalclaw snapshot to create a portable state

archive first (restore with personalclaw restore), and keep the archive somewhere safe.

• Don't make this your only system of record yet. Treat anything you put in

PersonalClaw as reproducible or backed up elsewhere until backward compatibility becomes the default posture — the point at which gated, migration-backed changes replace clean breaks (the lifecycle mental model in [CONTRIBUTING.md](CONTRIBUTING.md#breaking-changes)). Until then, run it as a power-user's second machine, not your primary driver.

• This is expected to last a while. Migration-backed change discipline is scheduled

deliberately late — it lands once the architecture has stopped moving, near the end of the current roadmap, because freezing compatibility around a half-built architecture is worse than breaking it honestly now. Plan for breaking 0.x updates as the norm, not the exception, for the foreseeable future.

This warning is relaxed only when that discipline lands — not on a date. We'd rather tell you plainly now than surprise you on an update.

Contributing? None of this asks you to break compatibility: contributor changes stay additive, and breaking changes are the maintainer's call. See [CONTRIBUTING.md → Breaking changes](CONTRIBUTING.md#breaking-changes).

---

What is PersonalClaw?

PersonalClaw runs AI agents that accomplish your work with a rich, user-assembled set of capabilities. Every vendor — model providers, search, speech, channels, agent runtimes — is a removable app, so nothing ties you to a single LLM vendor or service. All state lives under one ~/.personalclaw home on your machine; the system degrades gracefully to local-only and never requires the network for core operation.

flowchart TB
    subgraph you[" "]
        U["👤 You — dashboard · CLI · channels"]
    end
    U --> GW["🦞 Gateway (one process)"]
    subgraph core["Provider-agnostic core"]
        GW --> CHAT["Agentic Chat"]
        GW --> LOOP["Goal Loops"]
        GW --> AUTO["Automation · Triggers · Inbox"]
        CHAT & LOOP & AUTO --> ENG["Context Engine · Approvals · Guardrails"]
        ENG --> MEM["Memory"]
        ENG --> KN["Knowledge"]
        ENG --> SK["Skills"]
    end
    ENG --> APPS["App Platform (permission-gated, scanner-gated)"]
    APPS --> P1["Model providers"]
    APPS --> P2["Search · Speech · Local models"]
    APPS --> P3["Channels · Agent runtimes (ACP)"]
    APPS -. "removable, sandboxed" .-> EXT[("Your vendors\n& tools")]

Highlights

🗣️ Agentic chat

Multi-session chat with tool use and approval controls, session forking/undo, answer variants, folders/tags/kanban, side conversations, per-session model overrides, and temporary/incognito memory modes.

🎯 Goal loops

Give the agent a target and let it work autonomously — it classifies the goal, plans it, then loops cycle by cycle under a deterministic supervisor you can pause, nudge, or stop.

🧠 Memory that learns

Layered semantic + episodic + procedural memory with active recall, after-turn learning from your corrections, automatic promotion of repeated facts, and an optional Obsidian-compatible markdown vault.

📚 Knowledge base

Ingest documents (PDF/DOCX/PPTX/HTML/…), web pages, and media; AI enrichment, entity extraction, a knowledge graph, and semantic search wired into chat context.

🧩 Skills & 🔌 App platform

Reusable SKILL.md procedures with a marketplace and supply-chain scanning; a permission-gated Store where model providers, search, speech, local models, channels, agent runtimes, and full backend+UI apps install through a quarantine → scan → consent lifecycle.

⏰ Automation

Cron/interval/webhook triggers, background subagents, an inbox that watches channels and drafts replies, and workflow SOPs surfaced automatically when they match. Built to be left alone: a run that fails reaches your inbox even when the automation is set to deliver nothing, a run that was gated is labelled inert rather than green, and a run whose process died is terminalized instead of reading as running forever — with a recipe that [falsifies all three](docs/guides/automations.md).

🛡️ Security-first

Tool approval modes, a shell-command denylist, an egress guard with allow/deny host policy, a tamper-evident (HMAC) security event log, app-scoped tokens, and honest labeling of the one permission it can't technically enforce. Controls are enforced at the point of execution, not merely requested in a prompt — the [threat model](docs/security/threat-model.md) maps each to the OWASP Agentic Top-10 with code citations and states the limitations plainly. Found a security issue? Report it privately via [our security policy](SECURITY.md). See also the [security model](docs/architecture/security.md).

Does it do…?

Scanning for one specific word? Here it is, with what actually ships behind it today. The caveat is part of the answer — where a capability needs an app installed or a provider bound, the row says so rather than letting you find out after installing.

| Looking for | What ships today | Details | |---|---|---| | RAG · retrieval · vector search | A knowledge base over your own documents: keyword search (SQLite FTS5) is always available, and on top of it semantic vector retrieval, entity extraction, and a knowledge graph feed chat context with citations. Caveat: the vector half needs an embedding-provider app bound — with none bound, embeddings are off and retrieval stays keyword-only. | [Knowledge & memory](docs/architecture/knowledge-memory.md) | | Ollama · local models | Run chat against a local Ollama with no API key: setup probes localhost:11434, and an opt-in, time-bounded sweep can find one elsewhere on your own private network. Downloading and managing local models is a first-class provider axis. Caveat: the ollama-models provider is a removable app you install from the Store — core ships the detection and the binding, not the vendor. | [App platform](docs/architecture/app-platform.md) | | web search | web_search and web_fetch tools, plus the research flows built on them, served by a search-provider app you bind. Caveat: no search provider ships bundled, so nothing is bound out of the box — this is a provider seam you fill, not a batteries-included search feature. | [App platform](docs/architecture/app-platform.md) | | MCP — both directions | PersonalClaw connects out to any MCP server you configure in ~/.personalclaw/mcp.json — stdio or remote SSE/HTTP — and calls its tools inside the native agent loop. It also works the other way: it exposes six read-only tools of its own to your editor's assistant. Caveat: the outbound client needs the optional personalclaw[mcp] extra; without it the server registry is simply empty. | [Use it from your editor](docs/guides/use-from-your-ide.md) · [API](docs/reference/api-overview.md#mcp-servers) | | SSO · SAML · OIDC login | Not shipped, by design — PersonalClaw is single-user and self-hosted, so there is no directory to federate with. The gateway's selectable auth is a local token, or none when bound to loopback only; api_key and oauth2 exist as half-implementations that no configuration can select, and the runtime says so out loud. Reaching it from outside is a tunnel plus password and TOTP 2FA instead. | [Remote access](docs/guides/remote-access.md) · [Security model](docs/architecture/security.md) | | Document upload | Resumable chunked upload of large files — size-policed before the first byte and content-scanned on assembly — routed to a chat attachment, knowledge ingest, or your workspace. Documents ingest as PDF/DOCX/PPTX/HTML, web pages, and media. Caveat: PDFs/DOCX/PPTX/HTML/web pages parse with no model needed, but media (image OCR/vision, audio/video transcription) is model-gated — with none bound, the file still ingests, extraction just gracefully skips. | [Getting started](docs/guides/getting-started.md) |

Quickstart

Install with one command — every path installs the same release artifact (no per-channel special builds), and you don't need to install Python or Node yourself:

uv tool install personalclaw && personalclaw setup     # recommended — uv brings Python 3.12

Or use the bootstrap one-liner (installs uv if it's missing, then the above):

curl -fsSL https://personalclaw.dev/install | sh

Rather check the bytes before executing them? The script's digest is committed in this repo, so you can verify it from a second origin first — see [Verify the one-liner](docs/guides/getting-started.md#verify-the-one-liner).

Then start the gateway:

personalclaw gateway

Install matrix

| Path | Command | Best for | |---|---|---| | uv tool (recommended) | uv tool install personalclaw | anyone — uv provides Python 3.12 | | Bootstrap | curl -fsSL https://personalclaw.dev/install \| sh | the fastest start | | pipx | pipx install personalclaw | isolated Python tools | | pip | pip install personalclaw | inside an existing Python 3.12+ venv | | Docker Compose | see below | self-hosters · Windows | | Git checkout | [CONTRIBUTING](CONTRIBUTING.md#development-setup) | contributors / development |

Docker Compose

cp .env.example .env && docker compose -f deploy/compose/compose.yaml up -d

Brings up the gateway + a TLS web proxy with a persistent volume — details, backups, and updates in the [container guide](docs/guides/containers.md).

The dashboard opens at http://localhost:10000. Install a model-provider app from the Store, add your API key under Settings → Providers, and bind a chat model under Settings → Models — full walkthrough in [Getting started](docs/guides/getting-started.md).

Updating

personalclaw update advances the install you actually have — the wheel, the checkout's release tag, or the container's image tag. It tracks releases, not main: a git clone checks out the resolved tag rather than fast-forwarding a branch.

personalclaw snapshot                        # pre-1.0: no automatic data migration
personalclaw update                          # → the newest release on your channel
personalclaw config set updates.pin 0.2.1    # …or stay exactly here
personalclaw update --to 0.2.0               # roll back: pins that release and installs it

Everything is in Settings → Updates too: the channel (stable · beta · nightly for contributors), a version pin, automatic applies (updates.auto=staged, opt-in, held while work is in flight), the check cadence, and one-click rollback. The release check is the one outbound call this project makes and it can be switched off — see [Privacy](#privacy). Per-platform details: [Updating](docs/guides/getting-started.md#updating) · [containers](docs/guides/containers.md#updates) · [desktop](docs/guides/desktop.md#updating).

> Tech stack: Python 3.12 · aiohttp gateway · React + Vite SPA · SQLite · MIT. > Run modes: local process · Docker Compose · systemd/launchd service. (A macOS-only > Electron desktop shell exists but is experimental — not built, signed, or released by CI, > and has no auto-update channel.)

Platform support. Every row names what proves it — CI: is a workflow job, checklist: is a documented manual walkthrough, community is user-reported and not verified by us. Details and the [models]-extra per-arch reality: [Platforms](docs/guides/platforms.md).

| Platform | Support | Proof | |---|---|---| | Linux x86-64 | first-class | CI:full/matrix (ubuntu-latest) + release smoke | | Linux arm64 | first-class | CI:full/matrix (ubuntu-24.04-arm) + release smoke | | macOS Apple silicon | first-class | CI:full/matrix (macos-14) | | macOS Intel | best-effort | community | | Windows via WSL2 | supported | checklist:Windows via WSL2 — [Platforms](docs/guides/platforms.md) | | Windows via Docker Desktop | supported | checklist:Windows via Docker Desktop — [Platforms](docs/guides/platforms.md) | | Windows native | not supported | — |

Privacy

No analytics, no crash reporting, no usage tracking. PersonalClaw collects nothing about how you use it and sends no usage data anywhere. It's single-user and self-hosted; your conversations, memory, and knowledge never leave your machine unless you wire up a remote provider app. Exports exclude credentials by design.

One outbound call you should know about. PersonalClaw asks GitHub whether a newer release exists, on a schedule — by default at most once every 12 hours (updates.check_interval_hours, config/loader.py) — identifying itself with a personalclaw-update-check User-Agent. It sends no usage data, but it is a network request, so GitHub sees your IP, as it would for any HTTP call.

You can turn that check off. Set updates.check_enabled to false in your config and PersonalClaw makes zero outbound calls to GitHub: no scheduled release check and no egress from the updater at all. While the check is on, updates.check_interval_hours (1–168) tunes how often it runs. updates.auto is a separate, orthogonal control — it gates whether an available update is applied, not whether the check happens: off (the default) only notifies, while staged applies at the next safe point (held while a session or subagent is running, and only ever the resolved release tag, never raw main).

Supply chain

The release pipeline practices the install-time gating the product itself preaches: builds run in CI from a committed lockfile (uv.lock, installed with uv sync --locked); PyPI publishing uses Trusted Publishing (OIDC — no long-lived tokens stored anywhere) behind a manual owner-approval gate; every release attaches a syft SBOM and build-provenance attestations on the wheel and images; and Dependabot watches the pip, npm, and GitHub-Actions ecosystems weekly. pip-audit and npm audit run on every push to main.

Documentation

• [Getting started](docs/guides/getting-started.md) — install → first chat.
• [Working inside a chat](docs/guides/chat-surface.md) — the nine things the chat surface does beyond a send button: rewind to any earlier message, branch a conversation two ways, have a plan approved before anything runs, let a queued message cut in, find and quote, follow-up suggestions, the streaming reveal, and putting part of your screen into the conversation.
• [Automations yo

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: PersonalClaw
• Source: PersonalClaw/PersonalClaw
• License: MIT
• Homepage: https://personalclaw.dev

Install and usage instructions live in the source repository linked above.