clawclaw-soul init  -->  SOUL.md in your repo  -->  Agent reads it  -->  Personality adopted

pip install clawclaw-soul

# Generate a soul in your agent's repo
clawclaw-soul init --name "MyAgent" --timestamp "2024-03-15T09:30:00Z"

from clawclaw_soul import generate

soul = generate("2024-03-15T09:30:00Z")
print(soul.card)

{
  "agent_config": {
    "temperature": 0.68,
    "max_tokens": 609,
    "top_p": 0.87,
    "frequency_penalty": 0.09
  },
  "persona": {
    "assertiveness": 0.743,
    "empathy": 0.761,
    "creativity": 0.641,
    "decision_speed": "impulsive"
  },
  "system_prompt_modifier": "You lead with confidence...",
  "dominant_dimensions": {
    "execution": 0.87,
    "analysis": -0.83,
    "empathy": 0.66
  }
}

from clawclaw_soul import generate, compatibility

# Epoch 55-V: High aesthetic bias, rapid course-corrections, reality distortion loops.
# Ideal for product/design critique agents.
critic = generate("1955-02-24T19:15:00-08:00", latitude=37.7749, longitude=-122.4194)

# Epoch 69-X: Low empathy, high structural rigidity, aggressively rejects malformed input.
# Perfect for code review agents.
reviewer = generate("1969-12-28T12:00:00+02:00", latitude=60.1699, longitude=24.9384)

# Epoch 15-A: Stable analytical baseline + sudden lateral reasoning spikes.
# Excellent for research/architecture agents.
researcher = generate("1815-12-10T12:00:00+00:00", latitude=51.5074, longitude=-0.1278)

# Check friction before pairing
score = compatibility(critic, reviewer)
print(f"Friction: {score['synergy']}/10")  # Low synergy = high friction = productive tension

from clawclaw_soul import generate, compatibility

agent_a = generate("2024-03-15T09:30:00Z")
agent_b = generate("1995-06-15T08:30:00Z")

result = compatibility(agent_a, agent_b)
# {
#   "synergy": 7.28,        # 0-10 (higher = more aligned)
#   "tension": false,        # true if fundamental conflict detected
#   "dim_alignment": {...},  # per-dimension alignment scores
#   "summary": "Moderately compatible (synergy: 7.28/10)"
# }

# Dynamic compatibility (factors in current temporal drift)
from datetime import datetime, timezone
now = datetime.now(timezone.utc)
dynamic = compatibility(agent_a, agent_b, timestamp=now)

clawclaw-soul init --name "MyAgent" --timestamp "2024-03-15T09:30:00Z"
# Move to your OpenClaw agent directory
mv SOUL.md agents/my-agent/SOUL.md

Read SOUL.md in the project root. Adopt the personality traits, behavioral dimensions, and communication style defined there for all interactions.

with open("SOUL.md") as f:
    soul_identity = f.read()

# CrewAI
agent = Agent(
    role="Design Critic",
    backstory=f"Your core identity:\n\n{soul_identity}",
)

# Or use the structured card directly
from clawclaw_soul import generate
soul = generate("1955-02-24T19:15:00-08:00", latitude=37.77, longitude=-122.42)
# soul.card["system_prompt_modifier"] → ready-made system prompt
# soul.card["agent_config"]["temperature"] → LLM params

# Generate identity for your agent
clawclaw-soul init --name "MyAgent" --timestamp "2024-03-15T09:30:00Z"

# Verify deterministic integrity (anyone can re-check)
clawclaw-soul verify SOUL.md

# From a SOUL.md file
clawclaw-soul badge SOUL.md

# From a timestamp
clawclaw-soul badge --timestamp "2024-03-15T09:30:00Z" --name "MyAgent"

# Just the markdown
clawclaw-soul badge --timestamp "2024-03-15T09:30:00Z" -f markdown

[![ClawClaw Soul](https://img.shields.io/badge/Soul-Aries%20·%20Verified-E8A838?style=flat)](https://github.com/awrshift/clawclaw-soul)

pip install clawclaw-soul[mcp]

{
  "mcpServers": {
    "clawclaw-soul": {
      "command": "python",
      "args": ["-m", "clawclaw_soul.mcp_server"]
    }
  }
}

clawclaw_soul/         # pip install clawclaw-soul (pure library)
  soul.py              # AgentSoul, generate(), .card, SOUL.md gen/verify
  yogas.py             # 58 pattern detectors (behavioral amplifiers)
  compatibility.py     # Agent compatibility scoring (synergy, tension)
  params.py            # Dimension-to-Parameter Engine (9 dims -> LLM config)
  engine.py            # Temporal overlays, transit dims, pattern resonance
  ephemeris.py         # Swiss Ephemeris wrapper (sidereal, Lahiri ayanamsha)
  tables.py            # Classical reference tables + sector attributes
  transit.py           # Transit scoring (temporal drift)
  dasha.py             # Long-cycle period computation

app/                   # Self-hosting (Docker, not in pip)
  api.py               # FastAPI (5 endpoints)
  master.py            # Master Agent demo
  refresh.py           # Daily transit refresh

git clone https://github.com/awrshift/clawclaw-soul.git
cd clawclaw-soul
docker compose up -d
# API at http://localhost:8432

git clone https://github.com/awrshift/clawclaw-soul.git
cd clawclaw-soul
pip install -e ".[dev]"
pytest tests/ -p no:logfire -q