Skip to content
Back to search

claudeclaw

SkillWorks with Claude CodeGitHub

Use Claude to orchestrate agents like OpenClaw

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sbusso--claudeclaw/badge.svg)](/listings/sbusso--claudeclaw)

HTML

<a href="/listings/sbusso--claudeclaw"><img src="/api/listings/sbusso--claudeclaw/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/sbusso/claudeclaw.git
cd claudeclaw
claude
# type: /setup

`/setup` handles everything interactively: dependencies, runtime selection (sandbox is the default), channel authentication via platform APIs, group registration, and service startup.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 439 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="assets/logo.webp" alt="ClaudeClaw" width="200" />
  3. </p>
  4. <h1 align="center">ClaudeClaw</h1>
  5. <p align="center">Persistent agent orchestrator plugin for Claude Code. Multi-channel message routing, structured memory, webhook triggers, cost tracking — with OS-level sandbox isolation.</p>
  6. <p align="center">
  7. <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  8. <a href="https://github.com/sbusso/claudeclaw/stargazers"><img src="https://img.shields.io/github/stars/sbusso/claudeclaw?style=flat" alt="GitHub Stars"></a>
  9. <a href="https://github.com/sbusso/claudeclaw/issues"><img src="https://img.shields.io/github/issues/sbusso/claudeclaw" alt="Issues"></a>
  10. <a href="https://github.com/sbusso/claudeclaw/discussions"><img src="https://img.shields.io/github/discussions/sbusso/claudeclaw" alt="Discussions"></a>
  11. <a href="https://github.com/sbusso/claudeclaw"><img src="https://img.shields.io/badge/Claude_Code-Plugin-blueviolet" alt="Claude Code Plugin"></a>
  12. </p>
  13. Built on [NanoClaw](https://github.com/qwibitai/nanoclaw) — ported to a Claude Code plugin architecture with a pluggable extension system and Anthropic's sandbox runtime.
  14. ## What It Does
  15. ClaudeClaw is a Claude Code plugin that provides an always-on message loop. It listens to channels (Slack, WhatsApp, Telegram), routes messages to Claude agents running in isolated sandboxes, and manages ongoing conversations with structured memory.
  16. ### Core (Orchestrator)
  17. - **Always-on message loop** — persistent listener, not one-shot
  18. - **Multi-channel routing** — Slack, WhatsApp, Telegram (pluggable)
  19. - **Thread management** — auto-create threads, follow-ups without re-mentioning
  20. - **Context accumulation** — messages batch between triggers
  21. - **Structured memory** — daily logs, topic files, searchable archive with QMD upgrade path
  22. - **Webhook triggers** — HTTP POST with HMAC-SHA256 auth for CI/CD, GitHub, monitoring
  23. - **Per-group agent config** — model, tools, system prompt, cost limits per group
  24. - **Cost tracking** — token usage and estimated cost per agent run
  25. - **Extension system** — plug in triage, SWE queue, or custom capabilities
  26. - **Dual runtime** — OS-level sandbox (default) or container isolation
  27. ### Triage Extension
  28. - First-level support agent — investigates bugs, analyzes feature requests
  29. - Answers users in plain language (no code in user threads)
  30. - Creates GitHub issues when code changes are needed
  31. - Posts to dev channel for technical visibility
  32. - SWE task queue for sequential coding work
  33. ## Quick Start
  34. ```bash
  35. git clone https://github.com/sbusso/claudeclaw.git
  36. cd claudeclaw
  37. claude
  38. # type: /setup
  39. ```
  40. `/setup` handles everything interactively: dependencies, runtime selection (sandbox is the default), channel authentication via platform APIs, group registration, and service startup.
  41. ## Runtime Options
  42. ClaudeClaw supports two agent execution runtimes. Set `RUNTIME` in `.env`:
  43. | | Sandbox (default) | Container |
  44. |---|---|---|
  45. | **Cold start** | <10ms | ~2-5s |
  46. | **Memory overhead** | None | VM per container |
  47. | **Network isolation** | OS-level `allowedDomains` | Full outbound (credential proxy mitigates) |
  48. | **Credential model** | Direct credentials + restricted network | Proxy service |
  49. | **Setup** | `npm install` | Container daemon + image build |
  50. | **Filesystem isolation** | Kernel-enforced read/write boundaries | Volume mounts |
  51. ### Sandbox Runtime (Recommended)
  52. Uses Anthropic's `@anthropic-ai/sandbox-runtime` for OS-level process sandboxing. On macOS it uses Apple's Seatbelt framework; on Linux, bubblewrap. No containers, no VMs — kernel-level restrictions on an ordinary process.
  53. ```bash
  54. # .env
  55. RUNTIME=sandbox
  56. ```
  57. **Security model:** Real credentials are passed to the agent, but network is restricted to `api.anthropic.com` and `localhost` only. There's nowhere to exfiltrate credentials to. Filesystem access is kernel-enforced per the generated settings file — the agent for a family chat literally cannot read files from a work channel's directory.
  58. Agents run with `permissionMode: 'bypassPermissions'` — the sandbox IS the trust boundary, not application-level permission checks.
  59. ### Container Runtime
  60. Uses Apple Container (macOS) or Docker for container-based isolation. Agents run in Linux VMs with volume mounts. A credential proxy on localhost injects real API keys — containers never see actual credentials.
  61. ```bash
  62. # .env
  63. RUNTIME=container
  64. ```
  65. Per-group override: set `"runtime": "sandbox"` in the registered group config to use sandbox for specific groups while others use containers.
  66. ## Agent Triggers
  67. ClaudeClaw agents can be triggered three ways:
  68. | Trigger | How | Use Case |
  69. |---------|-----|----------|
  70. | **Channel message** | @mention in Slack/WhatsApp/Telegram | Interactive conversations |
  71. | **Scheduled task** | Cron, interval, or one-shot | Daily briefings, monitoring, reminders |
  72. | **Webhook** | `POST /webhook/:group` with HMAC-SHA256 | CI/CD pipelines, GitHub events, monitoring alerts |
  73. ### Webhook Triggers
  74. External systems can trigger agent runs via HTTP POST. Requires `WEBHOOK_SECRET` in `.env`.
  75. ```bash
  76. # Trigger an agent run
  77. PAYLOAD='{"prompt":"CI build failed on main — investigate and summarize"}'
  78. SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')
  79. curl -X POST http://localhost:3100/webhook/dev-team \
  80. -H "X-Signature: $SIGNATURE" \
  81. -d "$PAYLOAD"
  82. ```
  83. - HMAC-SHA256 signature verification (timing-safe)
  84. - Per-group rate limiting (10 req/min)
  85. - Health check: `GET /health`
  86. - Response routes through the group's channel
  87. ## Memory System
  88. Agents have structured memory tools for persistent recall across conversations:
  89. | Tool | What it does |
  90. |------|-------------|
  91. | **`memory_save`** | Append facts/notes to daily logs, topic files, or long-term CLAUDE.md |
  92. | **`memory_search`** | Search across all memory files and archived conversations |
  93. | **`memory_get`** | Read a specific memory file by path |
  94. ```
  95. groups/{folder}/
  96. CLAUDE.md # Long-term memory (loaded every session)
  97. memory/
  98. YYYY-MM-DD.md # Daily append-only logs
  99. topics/{name}.md # Topic-specific memory (projects, people, domains)
  100. conversations/ # Archived transcripts (auto-saved before compaction)
  101. ```
  102. Claude's built-in auto-memory and our `memory_save` tool write to the same `memory/` directory — unified store, nothing gets lost.
  103. Before context compaction, the PreCompact hook archives the conversation and writes a summary to the daily memory log. PostCompact verifies the flush succeeded. On API errors (rate limits, auth failures), the StopFailure hook notifies you through your channel instead of failing silently.
  104. **QMD upgrade:** Run `/add-qmd` to replace grep-based search with [QMD](https://github.com/tobi/qmd)'s hybrid BM25 + vector semantic search + LLM re-ranking, fully local.
  105. ## Per-Group Agent Config
  106. Each group can customize its agent behavior:
  107. ```typescript
  108. agentConfig: {
  109. model: 'haiku', // sonnet | opus | haiku | full model ID
  110. effort: 'low', // low | medium | high — reasoning effort
  111. systemPrompt: 'You are a ...', // Appended to agent system context
  112. allowedTools: ['Bash', 'Read'], // Override default tool allowlist
  113. disallowedTools: ['WebSearch'], // Blacklist specific tools
  114. maxTurns: 10, // Limit conversation turns
  115. costLimitUsd: 0.50, // Per-run budget cap
  116. }
  117. ```
  118. ## Cost Tracking
  119. Every agent run is logged with token usage and estimated cost:
  120. ```bash
  121. # Total cost per group
  122. sqlite3 store/messages.db \
  123. "SELECT group_folder, SUM(estimated_cost_usd) as cost, COUNT(*) as runs FROM agent_runs GROUP BY group_folder"
  124. # Recent runs with details
  125. sqlite3 store/messages.db \
  126. "SELECT group_folder, trigger_type, model, input_tokens+output_tokens as tokens, estimated_cost_usd, duration_ms FROM agent_runs ORDER BY run_at DESC LIMIT 10"
  127. ```
  128. ## As a Claude Code Plugin
  129. ```bash
  130. # Create a directory for your assistant
  131. mkdir ~/my-assistant && cd ~/my-assistant
  132. # Load ClaudeClaw as a plugin
  133. claude --plugin-dir /path/to/claudeclaw
  134. # Run /setup to configure channels and start the service
  135. ```
  136. **Directory = Instance.** The current directory IS the ClaudeClaw instance. All state (`.env`, `store/`, `groups/`, `logs/`) lives in cwd. No hidden paths, no `~/.claude/plugin-data/`.
  137. **Multiple instances = multiple directories:**
  138. ```bash
  139. ~/assistants/personal/ # cd here, run claude
  140. ~/assistants/work/ # cd here, run claude
  141. ```
  142. Services are named per directory (`com.claudeclaw.personal.plist` on macOS). Want to customize the code? Clone the repo into your data directory — `.env`, `store/`, `groups/` are gitignored, so they survive the clone. Now you're in developer mode with full self-improvement.
  143. ## Philosophy
  144. **Small enough to understand.** One process, a few source files, no microservices. The entire codebase fits in Claude's context window (~35K tokens).
  145. **Secure by isolation.** Agents run in OS-level sandboxes or containers — not behind application-level permission checks. The kernel enforces what files are readable and what hosts are reachable.
  146. **Built for the individual user.** Not a monolithic framework; software that fits each user's exact needs. Fork it, modify it, own it.
  147. **Customization = code changes.** No configuration sprawl. Want different behavior? Modify the code. The codebase is small enough that Claude can safely change it.
  148. **AI-native.** No installation wizard — Claude Code guides setup. No monitoring dashboard — ask Claude what's happening. No debugging tools — describe the problem and Claude fixes it.
  149. **Skills over features.** Instead of adding features to the core, contributors submit Claude Code skills (like `/add-telegram`) that transform your fork. You end up with clean code that does exactly what you need.
  150. ## What It Supports
  151. - **Multi-channel messaging** — Slack, WhatsApp, Telegram, Discord, Gmail. Add channels with skills like `/add-whatsapp` or `/add-telegram`.
  152. - **Isolated group context** — Each group has its own `CLAUDE.md` memory, isolated filesystem, and sandbox/container with only that directory mounted.
  153. - **Main channel** — Your private channel for admin control; every other group is completely isolated.
  154. - **Structured memory** — Daily logs, topic files, long-term CLAUDE.md, searchable archive.
  155. - **Scheduled tasks** — Recurring jobs that run Claude and can message you back.
  156. - **Webhook triggers** — External systems invoke agents via authenticated HTTP POST.
  157. - **Web access** — Search and fetch content from the Web.
  158. - **Agent Swarms** — Spin up teams of specialized agents that collaborate on complex tasks.
  159. - **Per-group agent config** — Model, tools, system prompt, cost limits per group.
  160. - **Cost tracking** — Token usage and estimated cost logged per run.
  161. - **Extension system** — Plug in triage, SWE queue, or custom capabilities without modifying core.
  162. ## Usage
  163. Talk to your assistant with the trigger word (default: `@ClaudeClaw`):
  164. ```
  165. @ClaudeClaw send an overview of the sales pipeline every weekday morning at 9am
  166. @ClaudeClaw review the git history for the past week each Friday and update the README if there's drift
  167. @ClaudeClaw every Monday at 8am, compile news on AI developments and message me a briefing
  168. ```
  169. From the main channel, manage groups and tasks:
  170. ```
  171. @ClaudeClaw list all scheduled tasks across groups
  172. @ClaudeClaw pause the Monday briefing task
  173. @ClaudeClaw join the Family Chat group
  174. ```
  175. ## Architecture
  176. ```
  177. Channels → SQLite → Polling loop → Sandbox/Container (Claude Agent SDK) → Response
  178. ↑
  179. Webhooks → HTTP server → HMAC verify → Queue
  180. ```
  181. Single Node.js process. Channels self-register at startup — the orchestrator connects whichever ones have credentials in `.env`. Messages land in SQLite, a polling loop picks them up, and the runtime spawns an isolated agent per group. IPC via filesystem.
  182. ### Key Files
  183. ```
  184. src/
  185. index.ts # Plugin entry (Claude Code --plugin-dir, non-blocking)
  186. service.ts # Service entry (launchd/systemd, runs message loop)
  187. orchestrator/
  188. message-loop.ts # THE HEART: poll, trigger, thread, queue, dispatch
  189. extensions.ts # Pluggable extension system
  190. channel-registry.ts # Channel self-registration
  191. config.ts # Configuration (from .env, including RUNTIME)
  192. env.ts # .env reader (secrets never in process.env)
  193. db.ts # SQLite operations
  194. group-queue.ts # Concurrency control
  195. ipc.ts # File-based IPC watcher
  196. types.ts # Core types (AgentConfig, RegisteredGroup, etc.)
  197. runtimes/
  198. sandbox-runner.ts # Sandbox runtime (srt CLI, settings, credentials)
  199. container-runner.ts # Container runtime (Apple Container / Docker)
  200. container-runtime.ts # Container binary abstraction
  201. channels/ # Built-in channels (whatsapp, telegram)
  202. webhook/
  203. server.ts # HTTP server with HMAC-SHA256 auth
  204. index.ts # Webhook extension registration
  205. cost-tracking/
  206. index.ts # Cost tracking extension (agent_runs table)
  207. extensions/ # Installable extensions (per-instance)
  208. claudeclaw-slack/ # Slack channel (/install-extension slack)
  209. claudeclaw-triage/ # Triage + SWE agents (/install-extension triage)
  210. agent/
  211. runner/src/index.ts # Runs inside sandbox/container — Claude Agent SDK
  212. runner/src/ipc-mcp-stdio.ts # MCP server (memory, tasks, messaging tools)
  213. skills/ # Skills available to agents
  214. docker/
  215. Dockerfile # Container image definition
  216. build.sh # Container build script
  217. groups/*/CLAUDE.md # Per-group memory (isolated)
  218. groups/*/memory/ # Daily logs and topic files
  219. ```
  220. ### Sandbox Runtime Internals
  221. The sandbox runner (`sandbox-runner.ts`) generates a per-agent srt settings JSON:
  222. ```json
  223. {
  224. "network": {
  225. "allowedDomains": ["api.anthropic.com", "*.anthropic.com", "localhost", "127.0.0.1"],
  226. "deniedDomains": [],
  227. "allowLocalBinding": true
  228. },
  229. "filesystem": {
  230. "denyRead": ["/path/to/project/.env"],
  231. "allowRead": ["/path/to/project"],
  232. "allowWrite": ["/path/to/group"],
  233. "denyWrite": ["/path/to/project/.env"]
  234. }
  235. }
  236. ```
  237. Path mapping via `CLAUDECLAW_*_DIR` env vars makes the agent runner runtime-agnostic — same binary works in both sandbox and container mode.
  238. ## Extension System
  239. Extensions register capabilities without modifying core:
  240. ```typescript
  241. import { registerExtension } from '../orchestrator/extensions.js';
  242. registerExtension({
  243. name: 'my-extension',
  244. ipcHandlers: { 'my_action': handler },
  245. onStartup: (deps) => { ... },
  246. dbSchema: ['CREATE TABLE IF NOT EXISTS ...'],
  247. containerEnvKeys: ['MY_API_KEY'],
  248. });
  249. ```
  250. Built-in extensions: **webhook triggers**, **cost tracking**. Installable:
  251. | Extension | Type | Install |
  252. |-----------|------|---------|
  253. | [claudeclaw-slack](https://github.com/sbusso/claudeclaw-slack) | Channel | `/install-extension slack` |
  254. | [claudeclaw-triage](https://github.com/sbusso/claudeclaw-triage) | Agent | `/install-extension triage` |
  255. More planned: [Discord](#future-extensions), [Gmail](#future-extensions), [QMD Memory](#qmd-semantic-memory), [Obsidian](#future-extensions), [TUI](#future-extensions).
  256. ## Customizing
  257. ClaudeClaw doesn't use configuration files. To make changes, just tell Claude Code what you want:
  258. - "Change the trigger word to @Bob"
  259. - "Add a morning briefing that runs at 7am and posts to Slack"
  260. - "Give the family group access to my Obsidian vault"
  261. - "Use opus for the dev-team group and haiku for everything else"
  262. Or run `/customize` for guided changes. Each change is a code change, committed to your fork, reversible with `git revert`.
  263. ## Requirements
  264. - macOS or Linux
  265. - Node.js 20+
  266. - [Claude Code](https://claude.ai/download)
  267. - No Docker required (sandbox mode is the default)
  268. ## FAQ
  269. **Why sandbox over Docker?**
  270. Sandbox provides better security (kernel-enforced vs proxy-based credential protection), faster startup (<10ms vs seconds), and simpler setup (no daemon, no image builds). Docker/Apple Container is available as a per-group fallback for cases needing custom agent-runner customization.
  271. **Is this secure?**
  272. Agents run in OS-level sandboxes, not behind application-level permission checks. Network is restricted to Anthropic's API. Filesystem access is kernel-enforced. The attack surface is a JSON settings file and ~150 lines of runtime configuration, not 500K lines of application logic. You should still review what you're running, but the codebase is small enough that you actually can.
  273. **Can I run this on Linux?**
  274. Yes. Sandbox uses bubblewrap on Linux. Container mode uses Docker. Just run `/setup`.
  275. **Why no configuration files?**
  276. We don't want configuration sprawl. Every user should customize ClaudeClaw so that the code does exactly what they want, rather than configuring a generic system.
  277. **How do I debug issues?**
  278. Ask Claude Code. "Why isn't the scheduler running?" "What's in the recent logs?" Or run `/debug` for guided troubleshooting.
  279. ## Roadmap
  280. ### Multi-Model Agent Routing
  281. Support multiple LLM providers per agent, similar to [pi.dev](https://pi.dev). The `agentConfig.model` field expands to accept provider-prefixed model strings:
  282. ```typescript
  283. agentConfig: {
  284. model: 'anthropic/opus', // Current default
  285. model: 'openai/gpt-4o', // OpenAI
  286. model: 'google/gemini-pro', // Google
  287. model: 'ollama/llama3', // Local via Ollama
  288. }
  289. ```
  290. **Phased approach:**
  291. 1. **Provider-aware model field** — Agent runner switches SDK based on prefix. Per-group model selection already works; this adds provider routing.
  292. 2. **Provider abstraction layer** — `Provider` interface wrapping each SDK. Tool schemas translated per provider. Unified streaming response format.
  293. 3. **Smart routing engine** — Pick provider/model based on task type, cost budget, latency. Fallback chains (try Opus → fall back to GPT-4 on rate limit). Cost-aware routing (triage on Haiku, SWE on Opus).
  294. ### QMD Semantic Memory
  295. Replace grep-based `memory_search` with [QMD](https://github.com/tobi/qmd) for hybrid BM25 + vector semantic search with LLM re-ranking. Fully local, no API calls for search.
  296. **What changes:**
  297. - `memory_search` tool calls QMD instead of grep
  298. - Automatic indexing of daily logs, topic files, CLAUDE.md, and archived conversations
  299. - Semantic queries: "what did we discuss about the API redesign last week" instead of keyword matching
  300. - QMD runs as a local process — no external dependencies, no data leaves the machine
  301. **Install:** `/add-qmd` skill sets up the QMD binary, indexes existing memory, and swaps the search implementation.
  302. ### Future Extensions
  303. | Extension | Purpose | Status |
  304. |-----------|---------|--------|
  305. | `claudeclaw-discord` | Discord channel integration | Planned |
  306. | `claudeclaw-gmail` | Gmail as a full channel (not just a tool) | Planned |
  307. | `claudeclaw-memory` | [QMD](https://github.com/tobi/qmd)-powered semantic memory (replaces grep search) | Planned |
  308. | `claudeclaw-obsidian` | Obsidian vault integration — sync memory, articles, notes | Planned |
  309. | `claudeclaw-tui` | Terminal UI for managing instances, groups, tasks | Planned |
  310. See the [discussions](https://github.com/sbusso/claudeclaw/discussions) for feature requests and ideas.
  311. ## Development
  312. ```bash
  313. npm run build # Compile TypeScript
  314. npm run dev # Run with tsx
  315. npm test # Run tests (355 core tests)
  316. ```
  317. ## Related Projects
  318. - [NanoClaw](https://github.com/qwibitai/nanoclaw) — upstream project, minimal agent orchestrator
  319. - [dotclaude.com](https://dotclaude.com) — Claude Code reference site (skills, hooks, plugins, MCP)
  320. - [Anthropic sandbox-runtime](https://www.npmjs.com/package/@anthropic-ai/sandbox-runtime) — OS-level sandboxing used by ClaudeClaw
  321. - [QMD](https://github.com/tobi/qmd) — hybrid semantic search engine (planned memory upgrade)
  322. - [Claude Agent SDK](https://docs.anthropic.com/en/docs/agents) — the SDK powering ClaudeClaw's agents
  323. ## License
  324. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.