ClawSouls

ClawSouls — AI Persona Manager

Manage Soul packages that define an AI agent's personality, behavior, and identity.

Souls use owner/name namespacing (e.g., clawsouls/surgical-coder, TomLeeLive/my-soul).

Prerequisites

Ensure clawsouls CLI is available:

npx clawsouls --version

If not installed, install globally:

npm install -g clawsouls

Current version: v0.6.2

Commands

Install a Soul

npx clawsouls install clawsouls/surgical-coder
npx clawsouls install clawsouls/surgical-coder --force       # overwrite existing
npx clawsouls install clawsouls/surgical-coder@0.1.0         # specific version

80+ souls available. Browse all at https://clawsouls.ai

Official souls (owner: clawsouls):

Activate a Soul

npx clawsouls use clawsouls/surgical-coder

Restore Previous Soul

npx clawsouls restore

Reverts to the most recent backup created by use.

List Installed Souls

npx clawsouls list

Shows installed souls in owner/name format.

Create a New Soul

npx clawsouls init my-soul

Scaffolds a new soul directory with soul.json, SOUL.md, IDENTITY.md, AGENTS.md, HEARTBEAT.md, README.md.

Export a Soul

npx clawsouls export claude-md           # generate CLAUDE.md from current workspace soul files
npx clawsouls export system-prompt       # generate a system prompt string

Combines SOUL.md, IDENTITY.md, AGENTS.md, HEARTBEAT.md, STYLE.md into a single file. Useful for Claude Code, Cursor, Windsurf, and other tools that use a single config file.

Version Management

npx clawsouls version bump patch    # 1.0.0 → 1.0.1
npx clawsouls version bump minor    # 1.0.0 → 1.1.0
npx clawsouls version bump major    # 1.0.0 → 2.0.0
npx clawsouls diff                  # colored diff of soul files

Soul Testing (Phase 9)

npx clawsouls test                  # Level 1 (schema) + Level 2 (soulscan)
npx clawsouls test --level 3       # + Level 3 (behavioral LLM tests)

Level 3 requires soul.test.yaml in the soul directory and an LLM provider (OpenAI/Anthropic/Ollama).

Doctor, Migrate, Search, Info, Update (Phase 10)

npx clawsouls doctor                # 12 environment checks
npx clawsouls migrate               # migrate soul from v0.3 → v0.4 → v0.5
npx clawsouls search "engineer"     # search souls from registry
npx clawsouls info clawsouls/brad  # show soul metadata
npx clawsouls update                # update installed soul to latest

Validate a Soul

npx clawsouls validate ./my-soul/
npx clawsouls validate --soulscan ./my-soul/   # with SoulScan security analysis
npx clawsouls check ./my-soul/                 # alias

Validates against the spec: schema, required files. Add --soulscan for full security & quality analysis with scoring. Also runs automatically before publish.

SoulScan — Security & Integrity Scanner

npx clawsouls soulscan              # scan current OpenClaw workspace
npx clawsouls soulscan ./my-soul/   # scan a specific directory
npx clawsouls soulscan --init       # initialize baseline checksums
npx clawsouls soulscan -q           # quiet mode for cron (SOULSCAN_OK / SOULSCAN_ALERT)
npx clawsouls scan                  # alias

SoulScan checks active soul files for:

Cron usage — periodic tamper detection:

# Run every hour to monitor workspace integrity
npx clawsouls soulscan -q
Exit code 0 = OK, 1 = alert (tampered or security issue)

First run: Use --init to establish baseline checksums without triggering alerts.

SOULSCAN™ — Score: 0-100, Grades: Verified (90+) / Low Risk (70+) / Medium Risk (40+) / High Risk / Blocked

Publish a Soul

export CLAWSOULS_TOKEN=
npx clawsouls publish ./my-soul/

Publishes to username/soul-name namespace automatically. Requires authentication token. Runs validation automatically before publishing — blocks on failure.

Login / Get Token

npx clawsouls login

Instructions to get API token: Sign in at https://clawsouls.ai → Dashboard → Generate API Token.

Workflow

Installing & Switching Personas

1. Browse — Check available souls at https://clawsouls.ai or suggest from the categorized list above 2. Install — npx clawsouls install clawsouls/surgical-coder 3. Activate — npx clawsouls use clawsouls/surgical-coder 4. Restart — Run soulclaw gateway restart to apply the new persona 5. New Session — Send /new in chat to clear previous persona context from conversation history 6. Restore — If they want to go back, npx clawsouls restore

Publishing a Soul

1. Login — npx clawsouls login → get token from dashboard 2. Set token — export CLAWSOULS_TOKEN= 3. Create — npx clawsouls init my-soul → edit files 4. Publish — npx clawsouls publish ./my-soul/ 5. Manage — Dashboard at https://clawsouls.ai/dashboard (delete, view downloads)

Memory Sync (Swarm)

npx clawsouls sync                  # sync encrypted memory to/from GitHub
npx clawsouls swarm                 # multi-agent memory branch & merge system

Sync agent memory across machines via encrypted Git. Uses age encryption for local-first privacy.

Soul Checkpoints (Rollback)

npx clawsouls checkpoint            # manage soul checkpoints
npx clawsouls checkpoint create     # create a checkpoint of current soul state
npx clawsouls checkpoint list       # list available checkpoints
npx clawsouls checkpoint restore    # restore from a checkpoint

Checkpoint-based rollback for persona contamination detection and recovery.

Platform Detection

npx clawsouls platform              # show detected agent platform(s) and workspace path
npx clawsouls detect                # alias

Detects which agent platform is running (OpenClaw, SoulClaw, ZeroClaw, etc.) and shows workspace paths.

MCP Server (for Claude Desktop / Cowork)

For Claude Desktop or Cowork users, there's also a dedicated MCP server:

npx -y soul-spec-mcp

Or add to Claude Desktop config (claude_desktop_config.json):

{ "mcpServers": { "soul-spec": { "command": "npx", "args": ["-y", "soul-spec-mcp"] } } }

6 tools: search_souls, get_soul, install_soul, preview_soul, list_categories, apply_persona

GitHub: https://github.com/clawsouls/soul-spec-mcp

Important Notes

Ensure clawsouls CLI is available:

npx clawsouls --version

If not installed, install globally:

npm install -g clawsouls

Current version: v0.6.2