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:

CODEBLOCK0

If not installed, install globally:

CODEBLOCK1

Current version: v0.6.2

Commands

Install a Soul

CODEBLOCK2

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

Official souls (owner: clawsouls):

• - Development: code-reviewer, coding-tutor, debug-detective, api-architect, ml-engineer, sysadmin-sage, devops-veteran, gamedev-mentor, prompt-engineer, frontend-dev, backend-dev, mobile-dev, cloud-architect, database-admin, qa-engineer
• Writing & Content: tech-writer, storyteller, scifi-writer, copywriter, content-creator, journalist, poet, screenwriter, academic-writer
• Professional: data-analyst, project-manager, legal-advisor, startup-founder, hr-manager, marketing-strategist, sales-coach, product-manager
• Education: math-tutor, philosophy-prof, mentor-coach, science-tutor, history-prof, language-teacher, economics-tutor
• Creative: music-producer, ux-designer, chef-master, graphic-designer, video-editor, podcast-host, dungeon-master, game-designer
• Lifestyle: personal-assistant, fitness-coach, travel-guide, life-coach, meditation-guide, nutrition-advisor, productivity-guru, financial-planner
• Science: research-scientist, data-scientist
• Security: security-auditor
• MBTI: mbti-intj, mbti-intp, mbti-entj, mbti-entp, mbti-infj, mbti-infp, mbti-enfj, mbti-enfp, mbti-istj, mbti-isfj, mbti-estj, mbti-esfj, mbti-istp, mbti-isfp, mbti-estp, mbti-esfp
• Special: surgical-coder, korean-translator
• General: brad, minimalist

Activate a Soul

CODEBLOCK3

• - Automatically backs up current workspace files (SOUL.md, IDENTITY.md, AGENTS.md, HEARTBEAT.md, STYLE.md, examples/)
• Never overwrites USER.md, MEMORY.md, or TOOLS.md
• Requires gateway restart to take effect

Restore Previous Soul

CODEBLOCK4

Reverts to the most recent backup created by use.

List Installed Souls

CODEBLOCK5

Shows installed souls in owner/name format.

Create a New Soul

CODEBLOCK6

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

Export a Soul

CODEBLOCK7

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

CODEBLOCK8

Soul Testing (Phase 9)

CODEBLOCK9

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

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

CODEBLOCK10

Validate a Soul

CODEBLOCK11

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

CODEBLOCK12

SoulScan checks active soul files for:

• - Integrity: SHA-256 checksum comparison — detects tampering since last scan
• Security: 53 pattern checks (prompt injection, code execution, XSS, data exfiltration, privilege escalation, social engineering, harmful content, secret detection)
• Quality: File structure, content length, schema validation
• Persona Consistency: Cross-validates name/tone across SOUL.md, IDENTITY.md, soul.json

Cron usage — periodic tamper detection:

CODEBLOCK13

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

CODEBLOCK14

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

Login / Get Token

CODEBLOCK15

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

Workflow

Installing & Switching Personas

1. 1. Browse — Check available souls at https://clawsouls.ai or suggest from the categorized list above
2. Install — INLINECODE12
3. Activate — INLINECODE13
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, INLINECODE16

Publishing a Soul

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

Memory Sync (Swarm)

CODEBLOCK16

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

Soul Checkpoints (Rollback)

CODEBLOCK17

Checkpoint-based rollback for persona contamination detection and recovery.

Platform Detection

CODEBLOCK18

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:

CODEBLOCK19

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

CODEBLOCK20

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

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

Important Notes

• - After use, always remind the user to run soulclaw gateway restart and then /new to start a fresh session (old conversation history retains the previous persona's identity)
• The use command creates automatic backups — data loss is unlikely
• Souls may include STYLE.md and examples/ for enhanced persona customization
• Published souls appear at INLINECODE33
• Users can leave reviews (1-5 stars) on any soul they don't own
• For custom registry (local testing), set env: INLINECODE34
• Website available in 5 languages: English, Korean, Japanese, Chinese, Spanish (e.g., clawsouls.ai/ko/souls/...)
• Share any soul to your OpenClaw bot: the install command is included in the share text
• The Soul Thesis — Read the manifesto: https://clawsouls.ai/en/manifesto
• Research paper — "Soul-Driven Interaction Design": https://doi.org/10.5281/zenodo.18772585
• Legal: Privacy Policy · Terms of Service