paw

# 🐾 Paw **The self-hosted AI agent platform that runs Barefoot Digital's day-to-day operations** — CRM automation, scheduling, research, and client workflows, in production since 2025. Paw is proprietary, source-available software (see [LICENSE](LICENSE.md)): the code is public because we believe proof beats claims. It is built and operated by [Barefoot Digital](https://www.barefootdigital.dev), an AI adoption consultancy — the systems we recommend to clients are the kind we run ourselves. **What it does:** multi-provider LLM support, persistent memory (hybrid vector + full-text search), a sandboxed skill/plugin system, an MCP client over multiple transports, scheduled jobs, an encrypted credential vault, a white-label brand kit, and an operations console with a web UI. **Status:** active, in production. Not accepting external contributions at this time. > Interested in what a system like this could do inside your company? That's literally our job: [barefootdigital.dev/audit](https://www.barefootdigital.dev/audit) ## Trust & Autonomy Paw is built to be safe to run **unattended**. Three layers keep it honest: - **Objective ledger + evidence gate** (`/tasks`) — work is tracked as kanban cards, and a task **cannot be marked done without evidence** (a re-query, a diff, a URL). No silent "I did it." - **Run verdicts** (`/runs`) — after every run Paw scores itself against its own tool log and flags "claimed success, no actual work." - **Approve-leash + execute-on-approve** — side-effecting actions queue for human approval; on approval Paw runs the *exact* approved action and records the result. Propose → you approve → it proceeds. Net: Paw can't silently misreport its own work, surfaces every run for verification, and a human approves every consequential action. ## Quick Start ```bash # Install dependencies bun install # Interactive setup (configures provider + credentials) bun run bin/paw.ts init # Start bun start # Development mode (auto-reload) bun run dev ``` ## Features - **Objective ledger + board** (`/tasks`) — work is tracked as kanban cards; a task can't reach *done* without evidence. Cron runs surface as durable cards on the same board. - **Run verdicts** (`/runs`) — every run is scored against its own tool log and flagged when it claims success with no actual work (phantom-success detection). - **Approve-leash** — side-effecting actions queue for human approval; on approval Paw re-runs the *exact* approved action and records the result (execute-on-approve). - **Multi-provider AI** — Claude, OpenAI, Ollama, Gemini. Switch providers via config. Optional vision routing sends image-bearing turns to a configured vision model. - **Memory system** — Hybrid vector + full-text search. Auto-extracts facts from conversations. Persists across sessions. - **Skills ecosystem** — Tools grouped into skills that load on demand, reducing token usage. Manage via web UI at `/skills`. - **Plugin architecture** — Built-in Slack and Web Pilot (Playwright) plugins. Drop-in plugin discovery from `plugins/` directory. A `skill_scaffold` tool generates new (inert, review-then-restart) plugins. - **Native integrations** — First-class, vault-credentialed integrations that work out of the box: GitHub (App), Strapi, HubSpot, Supabase, WordPress, n8n. - **MCP support** — Connect external tool servers via stdio, SSE, or HTTP transport (bearer/header auth, JSON-paste import). Manage at `/mcp`. - **Cron scheduler** — Schedule prompts, tool calls, or events on cron expressions. - **Live Canvas** — Agent-driven visual workspace with a live preview iframe; plus authed `apps/<space>/` production-app surfaces with per-space CSP. Toggle canvas mode in `/chat`. - **Chat** — Attachments for all file types (PDF text extraction, inline previews) and browser voice (speech-to-text / text-to-speech). - **Brand Kit** — A library of brand profiles (one active) that white-labels the agent, canvas output, and the entire console. - **Credential vault** — Encrypted, web-managed secrets (AES-256-GCM); resolved server-side and never exposed to the model. - **Agent Ops console** — The `/` dashboard: a live operation feed (Stream + Swarm lenses over the real tool stream) with in-flight tracking and session attribution. - **Web UI** — Agent Ops dashboard, chat + canvas, memory browser, session history, config editor, brand/vault/GitHub admin, and skill/cron/MCP management. - **Security** — Class-tiered rate limiting, user allowlist/blocklist, pairing code approval, optional TOTP 2FA, sandboxed tool execution, and untrusted tool-result framing (external tool output is delimited as data, never instructions). ## Configuration Paw loads config from multiple sources (highest priority first): 1. Runtime overrides 2. `~/.paw/config.json` (saved via web UI or CLI) 3. Environment variables 4. Credential store (`bun run bin/paw.ts auth login`) 5. Built-in defaults ### Environment Variables ```bash # AI Provider (claude, ollama, openai, gemini) PAW_PROVIDER=claude ANTHROPIC_API_KEY=sk-ant-... # Ollama PAW_OLLAMA_BASE_URL=http://localhost:11434 PAW_OLLAMA_MODEL=llama3.1 # OpenAI OPENAI_API_KEY=sk-... PAW_OPENAI_MODEL=gpt-4o # Gemini GEMINI_API_KEY=... PAW_GEMINI_MODEL=gemini-2.0-flash # Web UI PAW_WEB_ENABLED=true PAW_WEB_PORT=3000 # Slack SLACK_BOT_TOKEN=xoxb-... SLACK_APP_TOKEN=xapp-... SLACK_SIGNING_SECRET=... # Logging PAW_LOG_LEVEL=info # Access control — durable owner/allow/block ids (comma- or space-separated). # Unlike most PAW_* vars (which config.json overrides), these are UNIONED in # AFTER the file merge, so an env-declared owner is recognized on every boot # regardless of config.json or DB state — immune to the config writer. An owner # id needs no approved_users row or pairing code. PAW_SECURITY_OWNER_USER_IDS=U0XXXXXXXXX PAW_SECURITY_ALLOWED_USERS= PAW_SECURITY_BLOCKED_USERS= ``` > **Note on precedence:** environment variables normally sit *below* `config.json` > in the cascade, but the infra paths (`PAW_DB_PATH`, `PAW_CANVAS_ROOT`) and the > `PAW_SECURITY_*` id lists are applied *after* the file merge so a stale or wiped > `config.json` can't shadow them. The security lists **union** (never replace) > with whatever config/DB already recognize. ### Config File The web UI config page writes to `~/.paw/config.json`. Any key from the schema can be overridden: ```json { "provider": "claude", "ai": { "model": "claude-sonnet-4-5-20250929", "maxTokens": 4096 }, "agent": { "name": "Paw", "systemPrompt": "You are a marketing assistant." }, "web": { "enabled": true, "port": 3000 }, "memory": { "enabled": true, "autoExtract": true }, "skills": { "slack": { "alwaysActive": true } } } ``` ## Web UI Start with `PAW_WEB_ENABLED=true` (or set in config). Default: `http://127.0.0.1:3000` | Page | Path | Description | |------|------|-------------| | Agent Ops | `/` | Live operation feed (Stream + Swarm lenses), in-flight tracking, session attribution | | Chat | `/chat` | Interactive chat with session persistence; toggle canvas mode for the live visual workspace | | Tasks | `/tasks` | Objective-ledger kanban; work advances only with evidence | | Runs | `/runs` | Per-run verdicts (phantom-success detection) | | Memory | `/memory` | Browse, search, and manage stored memories | | Sessions | `/sessions` | View past conversation sessions | | Skills | `/skills` | View/toggle/edit skill groups and their tools | | Cron | `/cron` | Create and manage scheduled jobs | | MCP | `/mcp` | Connect and manage MCP tool servers | | Brand | `/brand` | Manage brand profiles and activate white-label theming | | Vault | `/vault` | Store and rotate encrypted credentials | | GitHub | `/github` | GitHub App status, PRs, approvals inbox, activity feed | | Submissions | `/submissions` | Durable inbox of canvas form submissions | | Config | `/config` | Edit all configuration live | Optional HTTP basic auth: set `web.password` in config. ## Skills Tools are automatically grouped into skills based on their source plugin. Only always-active skills (memory by default) are sent with every AI request. Other skills are loaded on demand when the AI calls `activate_skill`. This reduces input tokens from ~15-25k to ~1k per request. Manage skills at `/skills` in the web UI: toggle always-active, edit descriptions, view tool lists. ## Canvas The live canvas (toggle canvas mode in `/chat`) is a split-pane workspace where the AI generates HTML/CSS/JS and the result renders in a live preview iframe. - **How it works** — Send a prompt (e.g. "Create a landing page for a car dealer"), the AI uses `canvas_write` to create files in `./data/canvas/`, and the preview auto-refreshes. - **Persistence** — Canvas files survive server restarts. Use the trash icon in the toolbar to clear all files and start fresh. - **Tools** — `canvas_write`, `canvas_read`, `canvas_list` — sandboxed to the canvas root directory. - **Config** — `web.canvas.enabled` (default: true), `web.canvas.root` (default: `./data/canvas`). ## Plugins Built-in plugins live in `plugins/`: - **slack** — Slack integration via Socket Mode. Posts messages and reactions. - **web-pilot** — Browser automation with Playwright. Navigate, click, fill forms, screenshot. Plugins register tools and declare permissions via `manifest.json`. The kernel enforces sandboxed execution. ### MCP Servers Add external tool servers in config: ```json { "mcpServers": { "n8n": { "command": "npx", "args": ["-y", "@n8n/mcp-server"], "transport": "stdio" } } } ``` ## CLI Commands ```bash bun run bin/paw.ts init # Interactive setup bun run bin/paw.ts start # Start the kernel bun run bin/paw.ts auth login # Configure credentials bun run bin/paw.ts auth status # Check auth state bun run bin/paw.ts config # Show current config bun run bin/paw.ts status # Plugin health check bun run bin/paw.ts cron list # List cron jobs bun run bin/paw.ts cron add # Add a cron job bun run bin/paw.ts cron remove # Remove a cron job ``` ## Development ```bash bun test # Run tests bun run dev # Start with auto-reload bun run lint # Check with Biome bun run format # Format with Biome ``` ## Architecture ``` bin/paw.ts CLI entry point src/ kernel/ Kernel, event bus, sandbox, plugin loader ai/ Providers (Claude, OpenAI, Ollama, Gemini), tool registry, skills memory/ Vector + FTS memory store, auto-extraction store/ SQLite database, sessions, messages, agent-work ledger observability/ Run verdicts (phantom-success detection), tool log, logger config/ Schema validation (Zod), config loader/writer auth/ Credential storage per provider cron/ Cron scheduler with expression parser heartbeat/ System health monitoring security/ Access control, rate limiting, untrusted tool-result framing mcp/ MCP client manager (stdio, SSE, HTTP) web/ Hono web server, JSX views, REST API tools/ Built-in file, exec, and canvas tools types/ TypeScript interfaces plugins/ slack/ Slack channel plugin web-pilot/ Playwright browser plugin tests/ Test suite (Bun test runner) ``` ## Requirements - [Bun](https://bun.sh) v1.0+ - An AI provider API key (Anthropic, OpenAI, or Gemini) or a local Ollama instance ## License Paw is proprietary, source-available software — © Astral Events Miami LLC d/b/a Barefoot Digital, all rights reserved. The source is published for transparency, evaluation, and educational reading; no use, deployment, or redistribution rights are granted. See [LICENSE.md](./LICENSE.md) for the full terms. For commercial licensing, partnership, or deployment inquiries: info@barefootdigital.dev · [barefootdigital.dev](https://www.barefootdigital.dev)