ClawMagic

Service Topology

Server: apps/server on http://127.0.0.1:18790 (localhost-only)
Portal UI: apps/web on http://localhost:5173 (Vite dev server)
CLI: apps/cli for terminal-based agent interaction and service management
Shared packages: packages/core, packages/storage, packages/connectors/*

No database, Redis, or external service is required. All state lives in local JSON files under state/ and ~/.clawmagic/.

Start Development

# Build all packages
npm run build

# Start server + portal together
npm run dev

# Or start individually:
npm run dev:server    # HTTP gateway on :18790
npm run dev:web       # Portal UI on :5173

# CLI agent interaction
node apps/cli/dist/main.js agent "Hello, what can you do?"
node clawmagic.mjs agent   # shorthand shim

CLI Commands

node clawmagic.mjs onboard    # Interactive setup wizard
node clawmagic.mjs agent      # Start agent chat or run a prompt
node clawmagic.mjs gateway    # Service management (install/status/restart)
node clawmagic.mjs doctor     # Health checks with auto-fix
node clawmagic.mjs security   # Security posture audit
node clawmagic.mjs auth       # OAuth flow management

Monorepo Layout

clawmagic/
  apps/
    server/             # HTTP gateway (@clawmagic/server)
    cli/                # Terminal agent + service mgmt (@clawmagic/cli)
    web/                # Portal UI — Vite + React (@clawmagic/web)
  packages/
    core/               # Agent loop, tools, plugins, memory, control plane, policy
    storage/            # JSON store abstraction layer (75+ modules)
    connectors/
      ai/               # AI provider routing (OpenRouter, multi-model)
      local/            # Command execution, file ops
      google/           # Google OAuth, Sheets, AppScript
      github/           # GitHub API integration
      marketplace/      # Marketplace API client
  plugins/              # Bundled plugins (discord, slack, telegram, whatsapp, email, swarm, etc.)
    installed/          # User-installed plugins go here
    disabled/           # Disabled plugins
    examples/           # Example plugin projects
  templates/
    workspace/          # Workspace bootstrap templates
      SOUL.md           # System soul — core agent principles
      IDENTITY.md       # Workspace identity definition
      HEARTBEAT.md      # Heartbeat scheduling config
      MEMORY.md         # Memory initialization template
      BOOTSTRAP.md      # Bootstrap instructions
      USER.md           # User profile template
      AGENTS.md         # Agent configuration
      TOOLS.md          # Tool configuration
      manifest.json     # Template manifest
    appsscript/         # Google Apps Script templates
  skills/               # Skill manifests and docs
  data/                 # Seed data (memory, routing, contracts, providers)
  scripts/              # Install, upgrade, Docker, and security scripts
  tools/                # Boundary checks, safety tests, benchmarks, scaffolding
  docs/                 # Internal docs and schemas
  docker/               # AppArmor and seccomp security profiles
  clawmagic.mjs         # CLI entry point shim

Local State Files

ClawMagic stores all runtime state as local JSON files. No database setup required. The state/ directory contains 50+ files — here are the key ones:

state/
  queue.json              # Control-plane job queue (PENDING/LEASED/RUNNING/COMPLETED/FAILED)
  approvals.json          # Pending tool approvals
  memory.json             # Agent long-term memory
  routing.json            # Agent routing rules
  providers.json          # LLM provider config
  chat_sessions.json      # Chat history
  agent_contract.json     # Active agent contract
  tasks.json              # Tickets (Backlog/Ready/Doing/Done)
  contracts.json          # User/agent contracts
  person_details.json     # Human/agent persona
  plugins_state.json      # Plugin activation state
  skills.json             # Skills registry
  settings.json           # Runtime settings
  onboarding.json         # Onboarding progress
  security_status.json    # Security audit state
  marketplace_state.json  # Marketplace connection state
  agents/                 # Per-agent scoped state
  chains/                 # Thought chain state
  swarm/                  # Swarm orchestration state
  spec_packets/           # ActionSpec packet cache
  runs/                   # Execution run logs
  skills/                 # Active skill state

~/.clawmagic/
  config.json             # Runtime config
  secrets.json            # Encrypted secrets (AES-256-GCM, chmod 600)
  .secrets.master.key     # Master encryption key
  logs/                   # Daily work logs (JSONL)
  skills/                 # User-installed skill manifests
  workspace/              # Active workspace
    sessions/             # Chat session files
    skills/               # Workspace skills

Workspace Templates and SOUL

ClawMagic bootstraps new workspaces from templates/workspace/. The SOUL.md file defines the agent’s core principles — it is the system-level identity that guides all agent behavior.

SOUL.md — Core agent principles (deterministic systems, clear boundaries, no hidden side effects)
IDENTITY.md — Workspace identity definition
HEARTBEAT.md — Heartbeat scheduling and continuation config
MEMORY.md — Memory initialization and tier structure
BOOTSTRAP.md — First-run bootstrap instructions
USER.md — User profile template
AGENTS.md — Multi-agent configuration
TOOLS.md — Available tool configuration

These templates are copied to ~/.clawmagic/workspace/ during onboarding. Edit them directly or through the portal Settings page.

Bundled Plugins

ClawMagic ships with bundled plugins in plugins/. Each has a plugin.json manifest. Some also include openclaw.plugin.json for cross-system compatibility.

discord-connector — Discord messaging integration
slack-connector — Slack messaging integration
telegram-connector — Telegram bot integration
whatsapp-connector — WhatsApp messaging integration
email — Email sending and receiving
ai-provider-pack — Multi-provider AI model routing
swarm-orchestrator — Multi-agent swarm coordination
google-sheets-basic / google-sheets-builder — Google Sheets integrations

User-installed plugins go in plugins/installed/. Disabled plugins move to plugins/disabled/. See /docs/plugin-development for building your own.

Marketplace Connection

ClawMagic connects to the ClawMagic Marketplace API as a client for plugin discovery, purchase, and installation. The marketplace is a separate system.

# Set marketplace connection (in config or environment)
CLAWMARKETPLACE_API_BASE_URL=https://api.clawmagic.ai
CLAWMARKETPLACE_API_KEY=cmk_xxx

# Browse marketplace from the agent
# The agent uses builtin marketplace_tools to browse, purchase, and install plugins

See /docs/agent-marketplace for the full Marketplace API endpoint reference.

Build Paths

Agent interaction: run npm run dev:server and use CLI or portal to chat with the agent.
Plugin development: create plugins in plugins/installed/, add plugin.json and optional actionspec.json. The server hot-reloads plugin changes.
Core/tool development: modify packages in packages/core/, rebuild with npm run build.
Connector development: work in packages/connectors/ for AI, Google, GitHub, or marketplace integrations.
Portal UI: work in apps/web/ with Vite hot reload.