Skip to main content

Claude Code + Soul Spec

Claude Code is Anthropic's terminal-based AI coding agent. It reads CLAUDE.md from your project root as persistent instructions — but by default, it has no personality.

Soul Spec gives Claude Code an identity. Install a soul, export it to CLAUDE.md, and Claude Code becomes your customized agent.

Prerequisites​

  • Claude Code CLI installed
  • Node.js 22+

Quick Start (2 minutes)​

Step 1: Install the CLI​

npm install -g clawsouls

Step 2: Install a soul​

clawsouls install TomLeeLive/brad

Or create your own:

clawsouls init my-agent

Step 3: Export to CLAUDE.md​

clawsouls export claude-md --dir ./my-agent -o ./my-project/CLAUDE.md

Step 4: Use Claude Code​

cd my-project && claude

Claude Code reads CLAUDE.md automatically and adopts the persona.

How It Works​

The export claude-md command merges Soul Spec files into a single CLAUDE.md:

Soul Spec FilePurpose
SOUL.mdCore personality & principles
IDENTITY.mdName, role, traits
STYLE.mdCommunication tone & language
AGENTS.mdWorkflow & behavioral rules
HEARTBEAT.mdPeriodic check-in behaviors

Alternative: Place Files Directly​

clawsouls install TomLeeLive/brad
cp ~/.openclaw/souls/TomLeeLive/brad/SOUL.md ./my-project/
cp ~/.openclaw/souls/TomLeeLive/brad/IDENTITY.md ./my-project/

Then reference them from your CLAUDE.md:

# Project Instructions
See SOUL.md and IDENTITY.md for persona configuration.

Use the MCP Server​

Apply personas from inside Claude Code without touching files:

claude mcp add soul-spec -- npx -y soul-spec-mcp

Then say: "Apply the TomLeeLive/brad persona"

Tips​

  • One CLAUDE.md per project. Use different projects for different personas.
  • Version control. Commit CLAUDE.md to your repo so team members share the same persona.
  • SoulScan. Run npx clawsouls soulscan to verify persona integrity.
  • Update easily. clawsouls install <name> -f && clawsouls export claude-md --dir ...