\n\n---\n\n## Why I Built ClawBridge\n\n[OpenClaw](https://github.com/openclaw/openclaw) is an impressive project, but I wouldn't have been able to sleep if I had given complex software I didn't understand full access to my life. OpenClaw has nearly half a million lines of code, 53 config files, and 70+ dependencies. Its security is at the application level (allowlists, pairing codes) rather than true OS-level isolation. Everything runs in one Node process with shared memory.\n\nClawBridge provides that same core functionality, but in a codebase small enough to understand: one process and a handful of files. Claude agents run in their own Linux containers with filesystem isolation, not merely behind permission checks.\n\n## Quick Start\n\n```bash\nbash <(curl -fsSL https://raw.githubusercontent.com/other2368-byte/clawbridge-agent/main/clawbridge.sh)\n```\n\nOne command — installs Node, pnpm, and Docker if missing, then walks you through setup interactively. Works on a fresh machine.\n\nOr if you already have Node installed:\n\n```bash\nnpx clawbridge-agent setup\n```\n\nTo migrate from an existing install:\n\n```bash\nnpx clawbridge-agent setup --migrate\n```\n\n\n## Features\n\n- 🤖 **Multi-channel AI agents** — Telegram, WhatsApp, Discord, Slack, and more\n- 🤖 **Claude (Anthropic OAuth)** — no per-message API billing, uses your Claude Pro/Max subscription\n- 🧠 **Persistent memory** — Hindsight memory system with retain, recall, and reflect — agents remember context across sessions\n- 🔌 **Connect your tools** — Google, HubSpot, Slack, and more via MCP\n- 👁 **Vision & document analysis** via Claude\n- 🔒 **Container-isolated, self-hosted** — your data stays yours, agents run in Docker sandboxes\n- 🛡️ **Prompt injection protection** — built-in skill guards against malicious message injection attacks\n- 🤝 **Multi-agent orchestration** — agents can delegate tasks to other specialist agents, pass files between them, and run parallel workflows\n- ⚡ **In-session subagents** — spawn parallel subagents natively within a single session for faster task execution, no extra setup needed\n- ⚡ **Skills system** — browser automation, web search, scheduling, self-customization, and more\n- 🚀 **Migrate from OpenClaw or NanoClaw** in minutes\n\n## Architecture\n\n```\nmessaging apps → host process (router) → inbound.db → container (Bun, Claude Agent) → outbound.db → host process (delivery) → messaging apps\n```\n\nA single Node host orchestrates per-session agent containers. Agents run in Docker with explicit filesystem mounts. Credentials are injected directly from `~/.clawbridge/.env` into container environment variables at spawn time. See [docs/architecture.md](docs/architecture.md) for the full writeup.\n\n## AI Provider\n\nClawBridge uses Claude via Anthropic's official Claude Agent SDK. Authenticate once with `claude setup-token`. Hindsight memory uses Claude Haiku for retain/recall and Sonnet for reflect.\n\n## Philosophy\n\n**Small enough to understand.** One process, a few source files and no microservices. If you want to understand the full ClawBridge codebase, just ask Claude Code to walk you through it.\n\n**Secure by isolation.** Agents run in Linux containers and they can only see what's explicitly mounted. Bash access is safe because commands run inside the container, not on your host.\n\n**Built for the individual user.** ClawBridge isn't a monolithic framework; it's software that fits each user's exact needs. Instead of becoming bloatware, ClawBridge is designed to be bespoke. You make your own fork and have Claude Code modify it to match your needs.\n\n**Customization = code changes.** No configuration sprawl. Want different behavior? Modify the code. The codebase is small enough that it's safe to make changes.\n\n**AI-native, hybrid by design.** The install and onboarding flow is an optimized scripted path, fast and deterministic. When a step needs judgment, whether a failed install, a guided decision, or a customization, control hands off to Claude Code seamlessly. Beyond setup there's no monitoring dashboard or debugging UI either: describe the problem in chat and Claude Code handles it.\n\n**Skills over features.** Trunk ships the registry and infrastructure, not specific channel adapters or alternative agent providers. Channels (Discord, Slack, Telegram, WhatsApp, …) live on a long-lived `channels` branch; Ollama lives on `providers`. You run `/add-telegram`, etc. and the skill copies exactly the module(s) you need into your fork. No feature you didn't ask for.\n\n**Best harness, best model.** ClawBridge natively uses Claude Code via Anthropic's official Claude Agent SDK, so you get the latest Claude models and Claude Code's full toolset, including the ability to modify and expand your own ClawBridge fork. For local open-weight models, use `/add-ollama-provider`.\n\n## What It Supports\n\n- **Multi-channel messaging** — WhatsApp, Telegram, Discord, Slack, Microsoft Teams, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, and email via Resend. Installed on demand with `/add-` skills. Run one or many at the same time.\n- **Flexible isolation** — connect each channel to its own agent for full privacy, share one agent across many channels for unified memory with separate conversations, or fold multiple channels into a single shared session so one conversation spans many surfaces. Pick per channel via `/manage-channels`. See [docs/isolation-model.md](docs/isolation-model.md).\n- **Per-agent workspace** — each agent group has its own persona, its own memory, its own container, and only the mounts you allow. Nothing crosses the boundary unless you wire it to.\n- **Scheduled tasks** — recurring jobs that run Claude and can message you back\n- **Web access** — search and fetch content from the web\n- **Container isolation** — agents are sandboxed in Docker (macOS/Linux/WSL2), with optional [Docker Sandboxes](docs/docker-sandboxes.md) micro-VM isolation or Apple Container as a macOS-native opt-in\n- **Credential security** — agents never hold raw API keys. Credentials are injected directly from ~/.clawbridge/.env at container spawn time, so the agent process never sees them as environment variables it can exfiltrate.\n\n## Usage\n\nTalk to your assistant with the trigger word (default: `@Andy`):\n\n```\n@Andy send an overview of the sales pipeline every weekday morning at 9am\n@Andy review the git history for the past week each Friday and update the README if there's drift\n@Andy every Monday at 8am, compile news on AI developments from Hacker News and TechCrunch and message me a briefing\n```\n\nFrom a channel you own or administer, you can manage groups and tasks:\n```\n@Andy list all scheduled tasks across groups\n@Andy pause the Monday briefing task\n@Andy join the Family Chat group\n```\n\n## Customizing your agent\n\nEdit `~/.clawbridge/groups/main/CLAUDE.local.md` to customize your agent's persona. This is the only file you need to touch — the system configuration is managed automatically.\n\nThe file is created with a default template on first run. Open it and change anything:\n- Agent name and personality\n- Background knowledge about you or your team\n- Behavioral preferences and response style\n\n## Customizing\n\nClawBridge doesn't use configuration files. To make changes, just tell Claude Code what you want:\n\n- \"Change the trigger word to @Bob\"\n- \"Remember in the future to make responses shorter and more direct\"\n- \"Add a custom greeting when I say good morning\"\n- \"Store conversation summaries weekly\"\n\nOr run `/customize` for guided changes.\n\n## Contributing\n\n**Don't add features. Add skills.**\n\nIf you want to add a new channel or agent provider, don't add it to trunk. New channel adapters land on the `channels` branch; new agent providers land on `providers`. Users install them in their own fork with `/add-` skills, which copy the relevant module(s) into the standard paths, wire the registration, and pin dependencies.\n\nThis keeps trunk as pure registry and infra, and every fork stays lean.\n\nThis keeps trunk as pure registry and infra, and every fork stays lean — users get the channels and providers they asked for and nothing else.\n\n### RFS (Request for Skills)\n\nSkills we'd like to see:\n\n**Communication Channels**\n- `/add-signal` — Add Signal as a channel\n\n## Requirements\n\n- macOS or Linux VPS (Ubuntu, Debian, CentOS — any distro with Docker)\n- Node.js 20+ and pnpm 10+ (the installer will install both if missing)\n- [Docker Desktop](https://docker.com/products/docker-desktop) (macOS/Windows) or Docker Engine (Linux)\n- [Claude Code](https://claude.ai/download) for `/customize`, `/debug`, error recovery during setup, and all `/add-` skills\n\n## Key Files\n\n- `src/index.ts` — entry point: DB init, channel adapters, delivery polls, sweep\n- `src/router.ts` — inbound routing: messaging group → agent group → session → `inbound.db`\n- `src/delivery.ts` — polls `outbound.db`, delivers via adapter, handles system actions\n- `src/host-sweep.ts` — 60s sweep: stale detection, due-message wake, recurrence\n- `src/session-manager.ts` — resolves sessions, opens `inbound.db` / `outbound.db`\n- `src/container-runner.ts` — spawns per-agent-group containers, credential injection\n- `src/providers/` — host-side provider config (Claude built in)\n- `src/db/` — central DB (users, roles, agent groups, messaging groups, wiring, migrations)\n- `src/channels/` — channel adapter infra (adapters installed via `/add-` skills)\n- `container/agent-runner/` — Bun agent-runner: poll loop, MCP tools, provider abstraction\n- `container/Dockerfile` — Claude container image\n- `groups//` — per-agent-group filesystem (persona, memory, skills, container config)\n\n## FAQ\n\n**Why Docker?**\n\nDocker provides cross-platform support (macOS, Linux and Windows via WSL2) and a mature ecosystem. On macOS, you can optionally switch to Apple Container via `/convert-to-apple-container` for a lighter-weight native runtime.\n\n**Can I run this on Linux or Windows?**\n\nYes. ClawBridge runs on macOS (local machine) and Linux VPS (Ubuntu, Debian, CentOS, etc.). Just run `bash clawbridge.sh` on either. Windows via WSL2 also works.\n\n**Is this secure?**\n\nAgents run in containers, not behind application-level permission checks. They can only access explicitly mounted directories. Credentials never enter the container raw — they're injected at spawn time and never written to disk inside the container. For VPS hardening (SSH keys, firewall, fail2ban), see the [VPS hardening guide](docs/vps-hardening.md).\n\n**Do I need to pay per message?**\n\nNo. ClawBridge uses OAuth subscriptions, not API billing. You pay a flat monthly rate to Anthropic — not per token.\n\n**Can I use third-party or open-source models?**\n\nYes. Use `/add-ollama-provider` for local open-weight models via Ollama.\n\n**How do I debug issues?**\n\nAsk Claude Code. \"Why isn't the scheduler running?\" \"What's in the recent logs?\" \"Why did this message not get a response?\" That's the AI-native approach that underlies ClawBridge.\n\n**Why isn't the setup working for me?**\n\nIf a step fails, `clawbridge.sh` hands off to Claude Code to diagnose and resume. If that doesn't resolve it, run `claude`, then `/debug`.\n\n**What changes will be accepted into the codebase?**\n\nOnly security fixes, bug fixes, and clear improvements will be accepted to the base configuration. Everything else (new capabilities, OS compatibility, enhancements) should be contributed as skills on the `channels` or `providers` branch.\n\n## Community\n\nQuestions? Ideas? [Join the Discord](https://discord.gg/VDdww8qS42).\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for breaking changes, or the [full release history](https://docs.clawbridge.dev/changelog) on the documentation site.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}
![\"ClawBridge\"](\"assets/clawbridge-logo.png\"){kind=logo}
\n![\"Discord\"](\"https://img.shields.io/discord/1470188214710046894?label=Discord&logo=discord&v=2\")
![\"repo](\"repo-tokens/badge.svg\"){kind=icon}
\n