claudeclaw

Purpose

ClaudeClaw is a persistent agent orchestrator for individual users, running as a Claude Code plugin. It provides an always-on message loop that listens to channels such as Slack, WhatsApp, and Telegram, routes messages to Claude agents running in isolated sandboxes, and manages ongoing conversations. The project is built on NanoClaw, ported to the Claude Code plugin architecture, and uses Anthropic's sandbox runtime.

Main Capabilities

Core Orchestrator

• Persistent message loop: a persistent listener, rather than one-off execution
• Multi-channel routing: Slack, WhatsApp, Telegram (pluggable)
• Thread management: automatically creates threads, subsequent replies require no new mention
• Context accumulation: messages are batched between triggers
• Structured memory: daily logs, topic files, searchable archives, with a QMD upgrade path
• Webhook triggers: HTTP POST with HMAC-SHA256 authentication, for CI/CD, GitHub, monitoring
• Per-group agent configuration: each group can set model, tools, system prompt, cost limits
• Cost tracking: records token usage and estimated cost for each agent run
• Extension system: pluggable triage, SWE queue, or custom capabilities
• Dual runtime: OS-level sandbox (default) or container isolation

Triage Extension

• Tier-one support agent: investigates bugs, analyzes feature requests
• Replies to users in plain language (no code appears in user threads)
• Creates GitHub issues when code changes are needed
• Posts to a development channel for technical visibility
• SWE task queue for sequential coding work

Memory System

The agent has structured memory tools for persistent recall across conversations. Claude's built-in automatic memory and the memory_save tool write to the same memory/ directory, forming unified storage. Before context compaction, the PreCompact hook archives the conversation and writes a summary to the daily memory log; PostCompact verifies that the refresh succeeded. On API errors (rate limits, authentication failures), the StopFailure hook notifies the user through the channel rather than failing silently. QMD upgrade: running /add-qmd can replace grep-based search with QMD's hybrid BM25 + vector voSemantic search + LLM reranking, fully local.

Usage

Installation and Setup

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

Runtime Options

Set RUNTIME in .env:

Sandbox Runtime (Recommended) Uses Anthropic's @anthropic-ai/sandbox-runtime for OS-level process sandboxing. Uses the Apple Seatbelt framework on macOS and bubblewrap on Linux. No containers or virtual machines required; enforces kernel-level restrictions on ordinary processes. Security model: real credentials are passed to the agent, but network access is limited to api.anthropic.com and localhost. Filesystem access is enforced by the kernel based on a generated settings file. The agent runs with permissionMode: 'bypassPermissions'—the sandbox is the trust boundary.

Container Runtime Uses Apple Container (macOS) or Docker for container isolation. The agent runs in a Linux VM with volume mounts. A credential proxy on localhost injects the real API key, and the container never sees the actual credentials.

Per-group override: set "runtime": "sandbox" in a registered group's configuration to use the sandbox for a specific group while other groups use containers.

Trigger Methods

1. Channel messages: use the trigger word (default @ClaudeClaw) to converse with the assistant
2. Webhook triggers: external systems trigger agent runs via HTTP POST; requires setting WEBHOOK_SECRET in .env, supports HMAC-SHA256 signature verification (timing-safe), per-group rate limiting (10 requests/minute), health check GET /health, and responses routed through the group's channel
3. Main channel management: manage groups and tasks

How to Customize

ClaudeClaw does not use configuration files. To change behavior, tell Claude Code directly what you need, for example:

• "Change the trigger word to @Bob"
• "Add a morning briefing that runs at 7 AM and posts to Slack"
• "Let the family group access my Obsidian vault"
• "Use opus for the dev team group and haiku for all other groups"

Or run /customize for guided changes. Every change is a code change, committed to your fork and reversible with git revert.

Use Cases

• Individual users who want a persistent AI assistant that can interact through multiple messaging channels
• Need to fully isolate conversation contexts for different groups (such as family and work)
• Need to trigger agents from CI/CD, GitHub, or monitoring systems via Webhook
• Ongoing conversation scenarios that require structured memory and a searchable archive
• Developers who want to customize behavior through code rather than configuration

Limitations and Notes

• The project is positioned for individual users, not as a monolithic framework
• Customization means code changes; there is no configuration sprawl
• Sandbox mode does not require Docker; container mode serves as a per-group fallback
• The codebase is about 35K tokens and can fit into Claude's context window
• The security model relies on OS-level sandboxing, with network access limited to the Anthropic API and localhost
• More extensions (Discord, Gmail, QMD Memory, Obsidian, TUI) are planned features
• Multi-model agent routing (supporting multiple LLM providers) is a phased planned feature

Related Projects

• NanoClaw: the upstream project, a minimal agent orchestrator
• dotclaude.com: Claude Code reference site
• Anthropic sandbox-runtime: the OS-level sandbox used by ClaudeClaw
• QMD: hybrid semantic search engine (planned memory upgrade)
• Claude Agent SDK: the SDK that powers ClaudeClaw agents