claudeclaw CLAUDE.md

ClaudeClaw

Persistent agent orchestrator plugin for Claude Code.

Entry Points

Two separate entry points — plugin and service must not be conflated:

• src/index.ts → dist/index.js — Plugin entry. Loaded by Claude Code via --plugin-dir. Returns immediately, no side effects. No channel/extension imports.
• src/service.ts → dist/service.js — Service entry. Run by launchd/systemd as persistent background process. Imports channels/extensions, starts the message loop.

The plugin entry is what .claude-plugin/plugin.json points to. The service entry is what npm start, npm run dev, and the launchd plist/systemd unit run.

Modes

ClaudeClaw runs in two modes, detected by .claude-plugin/plugin.json in cwd:

Plugin mode (no .claude-plugin/ in cwd):

• Loaded via claude --plugin-dir /path/to/claudeclaw
• Current directory IS the instance — all state lives in cwd
• No hidden paths, no ~/.claude/plugin-data/
• Multiple instances = multiple directories (cd is the instance switcher)
• Service per directory: com.claudeclaw.<dirname>.plist (macOS), claudeclaw-<dirname>.service (Linux)
• Upgrade to developer mode: clone the repo INTO the data directory

Developer mode (.claude-plugin/plugin.json exists in cwd):

• Cloned repo, claude runs from inside it
• Code and state in the same directory
• Full self-improvement — Claude edits its own source
• Git/fork workflow

Directory = Instance

No instance manager. No switching commands. The directory you run claude from IS the ClaudeClaw instance.

~/assistants/personal/    ← one instance (cd here, run claude)
  .env, store/, groups/, logs/, .claudeclaw.json
~/assistants/work/        ← another instance
  .env, store/, groups/, logs/, .claudeclaw.json

Path resolution: STATE_ROOT = process.cwd() always. STORE_DIR, GROUPS_DIR, LOG_DIR derive from it. readEnvFile() checks CLAUDECLAW_ENV_FILE then cwd/.env.

Architecture

src/
  index.ts                    # Plugin entry (Claude Code --plugin-dir, non-blocking)
  service.ts                  # Service entry (launchd/systemd, runs message loop)
  orchestrator/               # Core
    message-loop.ts           # THE HEART: poll, trigger, thread, queue, dispatch
    group-queue.ts            # Concurrency control for agent execution
    extensions.ts             # Pluggable extension system (registerExtension API)
    extension-loader.ts       # Scans extensions/ dir, loads manifests, dynamic imports
    extension-manifest.ts     # Manifest schema + validation
    channel-registry.ts       # Channel self-registration
    ingestion.ts              # Inbound message processing (pre/post hooks)
    outbound-router.ts        # Outbound message routing (pre/post hooks)
    db.ts                     # SQLite with extension schema support
    config.ts                 # Core config (from .env)
    env.ts                    # .env reader
    logger.ts                 # Pino logger
    types.ts                  # Core types (Channel, RegisteredGroup, NewMessage)
  runtimes/                   # Agent execution backends
    container-runtime.ts      # Container runtime abstraction (binary detection, lifecycle)
    container-runner.ts       # Container-based agent runner (Docker/Apple Container)
    sandbox-runner.ts         # Sandbox-based agent runner (srt, OS-level sandboxing)
  channels/                   # Built-in channels (whatsapp, telegram)
  cost-tracking/              # Built-in: token usage + cost estimation
  webhook/                    # Built-in: HTTP webhook triggers
extensions/                   # Installable extensions (gitignored, per-instance)
  claudeclaw-slack/           # Slack channel (install with /install slack)
  claudeclaw-triage/          # Triage + SWE agents (install with /install triage)