🧠 ClawSouls CLI

Give your AI a soul. Install, manage, validate, and switch AI agent personas — built for OpenClaw, works with any SOUL.md-compatible agent.

What is ClawSouls?

ClawSouls is a persona platform for AI agents. A Soul is a personality package — a set of markdown files (the Soul Spec) that define how your AI thinks, talks, and behaves. Same LLM, completely different personality — and the same persona stays consistent across models and devices.

Browse souls at clawsouls.ai.

Multi-Platform Support

ClawSouls works with any SOUL.md-compatible agent framework. The CLI auto-detects your installed platform and applies souls to the correct workspace.

| Platform | Directory | Status | |----------|-----------|--------| | OpenClaw | ~/.openclaw/workspace/ | ✅ Auto-detected | | ZeroClaw | ~/.zeroclaw/workspace/ | ✅ Auto-detected | | Clawdbot | ~/.clawdbot/workspace/ | ✅ Auto-detected | | Moltbot | ~/.moltbot/workspace/ | ✅ Auto-detected | | Moldbot | ~/.moldbot/workspace/ | ✅ Auto-detected | | Custom | Any path | ✅ Via --workspace or --platform |

1. Install downloads soul files to ~/<platform>/souls/<owner>/<name>/
2. Use copies soul files (SOUL.md, IDENTITY.md, …) to the workspace
3. Protected files (USER.md, MEMORY.md, TOOLS.md) are never overwritten
4. Automatic backup before every switch — revert with clawsouls restore

clawsouls --platform zeroclaw use surgical-coder       # explicit platform
clawsouls --workspace ~/my-agent/workspace use my-soul # custom path
CLAWSOULS_PLATFORM=clawdbot clawsouls use my-soul       # env var
clawsouls platform                                     # check detection

Coding-Agent Frameworks (--use)

Beyond the auto-detected gateway platforms above, ClawSouls installs a soul straight into popular coding-agent frameworks with install --use <framework>:

| Framework | --use value | Where the persona lands | |-----------|---------------|-------------------------| | Claude Code | claude-code | CLAUDE.md | | Cursor | cursor | .cursor/rules/*.md | | Cline | cline | .clinerules/clawsouls-*.md | | Kilo Code | kilocode | .kilocode/rules/clawsouls-*.md | | Codex (OpenAI) | codex | AGENTS.md (merged, preserves existing) | | pi | pi | AGENTS.md (merged, preserves existing) | | Hermes | hermes | ~/.hermes/SOUL.md + AGENTS.md | | Windsurf | windsurf | .windsurfrules |

npx clawsouls install clawsouls/surgical-coder --use claude-code
npx clawsouls install clawsouls/surgical-coder --use cursor
npx clawsouls install clawsouls/surgical-coder --use codex

Frameworks that share the AGENTS.md convention (Codex, pi, Hermes) are merged inside <!-- clawsouls:soul:start --> markers, so your existing AGENTS.md content is preserved — never overwritten. Then restart / reload your editor to apply the persona.

Quick Start

# Install a soul (owner/name format)
npx clawsouls install clawsouls/surgical-coder

# Activate it (backs up your current workspace)
npx clawsouls use surgical-coder

# Restart your agent session — done!

Installation

npx clawsouls <command>      # use directly, no install
npm install -g clawsouls     # or install globally

Requirements: Node.js 22+

Commands

Browse & install

clawsouls search <query>                     # search the registry
clawsouls info clawsouls/surgical-coder      # show soul details
clawsouls install clawsouls/minimalist       # install latest
clawsouls install clawsouls/[email protected] # specific version
clawsouls use minimalist                     # activate (auto-backup)
clawsouls restore                            # revert to previous soul
clawsouls list                               # list installed souls

Create, validate & publish

clawsouls init my-soul                # scaffold a new soul package
clawsouls init my-robot --spec 0.5    # robotics / embodied template
clawsouls validate ./my-soul          # validate against the Soul Spec
clawsouls validate --soulscan         # + run SoulScan analysis
clawsouls login <token>               # authenticate
clawsouls publish ./my-soul           # publish to clawsouls.ai

clawsouls init scaffolds soul.json, SOUL.md, IDENTITY.md, AGENTS.md, HEARTBEAT.md, STYLE.md and README.md. The --spec flag selects the Soul Spec template:

| Flag | Version | Use Case | |------|---------|----------| | (default) | v0.5 | Personas, incl. environment & interactionMode | | --spec 0.5 | v0.5 | Robotics / embodied agents (adds safety.laws, sensor/actuator schemas) | | --spec 0.4 | v0.4 | General-purpose personas | | --spec 0.3 | v0.3 | Minimal / legacy |

🔒 SoulScan — persona security & quality

SoulScan validates a soul package before you deploy it, producing a security trust score and grade. Run it on a directory or your active workspace:

clawsouls scan ./my-soul          # full scan with grade & score
clawsouls scan --semantic         # add deep LLM analysis (security/jailbreak/PII)
clawsouls scan --no-llm           # rule-based only (skip LLM)
clawsouls scan -q                 # quiet (SOULSCAN_OK / SOULSCAN_FAIL) — for CI/cron
clawsouls scan --json             # machine-readable output
clawsouls soulscan --init         # initialize baseline checksums (tamper watch)

What it checks:

• Structure & schema — files, manifest, allowed extensions, sizes.
• Security patterns — prompt injection, data exfiltration, jailbreaks, PII, malicious binaries (50+ patterns).
• Embodied safety — for environment: embodied souls, verifies safety.laws exist with priority-ordered critical rules, and flags persona instructions that contradict declared safety laws.
• LLM persona consistency (new in v0.15) — uses an LLM to cross-check the persona's name, tone, and role across files and flag contradictions (e.g. "be formal and professional" in one file vs "always use slang" in another). Runs automatically when an LLM provider is available (cloud API key or local Ollama), with a rule-based fallback. Disable with --no-llm.

🧬 Swarm Memory — collective memory sync

Sync a soul's memory across agents/devices using git as the backing store:

clawsouls sync init                  # set up memory sync
clawsouls sync push / pull / status  # synchronize memory
clawsouls swarm init / join          # multi-agent shared memory
clawsouls export-key / import-key    # portable encryption keys

⏮ Checkpoints

clawsouls checkpoint create          # snapshot the current persona
clawsouls checkpoint list            # list snapshots
clawsouls checkpoint restore <id>    # roll back to a snapshot

Other utilities: clawsouls platform, clawsouls diff <soul> <v1> <v2>, clawsouls doctor, clawsouls update.

Soul Spec

Souls follow the Soul Spec — an open specification for AI agent persona packages:

my-soul/
├── soul.json       # Metadata (name, version, tags, compatibility, environment)
├── SOUL.md         # Persona, principles, tone, and boundaries
├── IDENTITY.md     # Name, avatar, and vibe
├── AGENTS.md       # Operating instructions / workflow
├── HEARTBEAT.md    # Periodic check behavior
├── STYLE.md        # Voice & formatting style
└── README.md       # Human-readable description

The same persona runs consistently across any LLM (Anthropic / OpenAI / Google / local) and any device.

Links

• 📚 Full Documentation
• 🌐 clawsouls.ai — Browse souls
• 📖 Soul Spec — Open specification
• 🔒 SoulScan — Security scanner
• 📜 Manifesto
• 📄 Research Paper

License

Apache-2.0