soul-radar is a CLI tool that searches, browses, and installs SOUL.md personality templates for AI agents. Think of it as a package manager for AI personalities — one command to discover templates across 4 community sources, another to install them into your project.

Built for OpenClaw agent developers who don't want to write personality prompts from scratch.

Demo

$ souls search "code review"

  Source            Name                 Description
  ─────────────────────────────────────────────────────────────────
  souls.directory   code-reviewer        Meticulous code reviewer with security focus
  clawplay          translated/reviewer  严格的代码审查专家
  awesome           development/cr-bot   PR review agent with auto-suggestions

  Found 3 results across all sources.

$ souls install code-reviewer
  ✔ Saved to ./SOUL.md

Key Features

• 🔍 Unified Search — query 3 community sources with one command
• 🌏 Multilingual — English (souls.directory) + Chinese (ClawPlay 虾魂) templates
• 📦 One-Command Install — souls install <name> writes SOUL.md to your project
• 🏷️ Category Browsing — explore by coding, creative, devops, and 20+ categories
• ⚡ Zero Config — works instantly with npx, no setup needed
• 🔗 GitHub Token Support — auto-detects gh CLI or GITHUB_TOKEN for higher rate limits

Installation

# Run instantly (no install)
npx soul-radar search "funny"

# Or install globally
npm install -g soul-radar

Quick Start

# Search all sources at once
souls search "assistant" --source all

# Browse a category
souls browse coding

# Preview a template
souls view thedaviddias/comedian

# Install to your project
souls install thedaviddias/comedian
# → writes ./SOUL.md

Data Sources

| Source | Flag | What's Inside | |--------|------|--------------| | souls.directory | (default) | English-first SOUL.md marketplace | | ClawPlay (虾魂) | --source clawplay | Chinese-first community templates | | awesome-openclaw-agents | --source awesome | 20+ curated categories | | soul-index | --source soulindex | Aggregated index with language filter (--language zh) | | All sources | --source all | Search everything at once |

Tip: GitHub-based sources auto-detect your gh CLI token or GITHUB_TOKEN env var to avoid rate limits.

Commands

souls search <query>

souls search "猫娘" --source clawplay     # Search Chinese templates
souls search "devops" --source awesome     # Search curated agents
souls search "code review" --source all    # Search everywhere
souls search "assistant" --limit 20        # Limit results
souls search "code" --source soulindex     # Search aggregated index
souls search "助手" --source soulindex --language zh  # Filter by language

souls browse [category]

souls browse coding                        # souls.directory category
souls browse creative --source clawplay    # ClawPlay category
souls browse devops --source awesome       # awesome-openclaw category
souls browse --source clawplay             # List all without filter

souls categories

souls categories                           # List available categories
souls categories --source all              # Merged from all sources

souls view <name>

souls view thedaviddias/comedian                          # souls.directory
souls view clawplay:community/creative/catgirl-nova       # ClawPlay
souls view awesome:agents/devops/incident-responder       # awesome-openclaw
souls view soulindex:rio-awsm/analytical-engine           # soul-index

souls install <name>

souls install thedaviddias/comedian                       # → ./SOUL.md
souls install clawplay:translated/pirate-captain --path ./agents/pirate/SOUL.md

What is SOUL.md?

SOUL.md files are personality templates that define how AI agents behave — their tone, principles, communication style, and domain knowledge. Instead of writing complex system prompts from scratch, pick a community-tested template and customize it.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT © shazhou-ww