Just like GitHub stores code, SoulHub stores well-tuned Agent souls.
Every Agent Deserves a Soul 🦞
SoulHub is an open-source Agent persona template community — share, discover, and deploy well-tuned AI Agents with one click. It provides a Web platform for browsing and visual orchestration, a CLI tool for one-command installation, and Team Recipes for batch-deploying multi-Agent collaboration architectures.
Not sharing code or workflows, but sharing Agent personas, skills, and behavior patterns.
Web Platform · CLI Tool · Agent Registry · Fusion Orchestrator · Quick Start · Local Development · Docker Deploy · Contributing
While building multi-Agent architectures with OpenClaw, we discovered that well-tuned Agents (IDENTITY.md + SOUL.md) have tremendous reuse and sharing value. However —
| Pain Point | Current State |
|---|---|
| Closed Ecosystem | Agents on GPT Store, Coze Store, Character.AI, etc. cannot be exported or migrated |
| Granularity Mismatch | PromptBase sells single prompts, Dify focuses on full workflows — missing the "Agent persona" middle layer |
| No Team Perspective | Almost no platform addresses sharing templates for multi-Agent collaboration teams |
SoulHub's answer: Define Agent souls in Markdown, share them through open source.
- 🧠 Soul-First — Not code or workflows, but Agent personas, skills, and behavior patterns (IDENTITY.md + SOUL.md).
- 📝 Markdown Native — Human-readable and editable, version-control friendly, no vendor lock-in.
- 🎨 Fusion Orchestrator — Drag & drop Agents onto a canvas, auto-generate dispatchers and routing rules, undo/redo/auto-layout.
- 👥 Team Recipes — Share multi-Agent collaboration architectures (e.g., "Social Media Team", "Dev Squad").
- 🔧 CLI One-Click Install —
soulhub install writer-xiaohongshu, one command, ready to go. - 🌍 Framework Compatible — Primary support for OpenClaw, designed to adapt to Dify / CrewAI and more.
- 🌓 Theme Switching — System / Light / Dark mode.
- 🐳 Docker One-Click Deploy —
make deploy-docker, build image + start service in one step. - 📖 Docs Center — Getting started guide, Soul spec reference, community contribution guide.
┌──────────────────────────┐
│ soulhub (this repo) │
└────────────┬─────────────┘
│
┌───────────────────────┼───────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ Next.js Web │ │ Registry │ │ GitHub Actions │
│ Platform (SSR) │◄──│ 32 Agent Templs │──►│ CI Validate │
│ │ │ 3 Team Recipes │ │ + Build │
│ /souls Browse │ │ │ └──────────────────┘
│ /fusion Orch. │ │ index.json idx │
│ /docs Docs │ └──────────────────┘
└──────────────────┘
▲
│ HTTP (GitHub Raw)
│
┌──────────────────┐
│ soulhub-cli │
│ (separate repo) │
│ │
│ Search/Install │
│ Update/Rollback │
└──────────────────┘
32 curated templates across 7 categories:
| Category | Example Agents |
|---|---|
| 🎨 Self Media | Xiaohongshu Writer, WeChat Author, Zhihu Creator, Twitter Writer, Trending Researcher, Publish Scheduler |
| 💻 Development | Full-Stack Engineer, Python Expert, Code Reviewer, System Architect, K8s DevOps |
| 📈 Operations | Data Analyst, SEO Specialist, Growth Hacker, Ops Assistant |
| 🎧 Support | Frontline Support, Technical Support, Escalation Dispatcher |
| 📚 Education | Programming Tutor, English Teacher |
| 🎯 Dispatcher | Master Dispatcher (multi-Agent coordination) |
3 Team Recipes: Social Media Team, Dev Squad, Support Center.
Each Agent template consists of:
registry/agents/your-agent-name/
├── manifest.yaml # Metadata: name, category, tags, version
├── IDENTITY.md # Identity: role, responsibilities, capabilities
├── SOUL.md # Behavior: personality, style, workflow
├── HEARTBEAT.md # (Optional) Heartbeat: daily routines, status updates
└── skills/ # (Optional) Skill modules: domain-specific abilities
Runtime: Node ≥ 18
# Install CLI (recommended: curl one-line install)
curl -fsSL https://soulhub-1251783334.cos.ap-guangzhou.myqcloud.com/install.sh | bash
# Or install via npm
npm install -g soulhubcli
# Search for Agents
soulhub search writer
# Interactive install (prompts for role & claw selection)
soulhub install writer-xiaohongshu
# Install as main agent (skip role prompt)
soulhub install writer-xiaohongshu --role main
# Install as worker agent (skip role prompt)
soulhub install writer-xiaohongshu --role worker
# Specify claw type (skip claw prompt)
soulhub install coder-fullstack --claw-type LightClaw
# Install to a custom directory
soulhub install coder-fullstack --dir ./my-agents
# Install a Team Recipe (multiple Agents at once)
soulhub install --recipe self-media-team
# Rollback to a previous installation state
soulhub rollback- Visit the Web platform, go to
/soulsto browse or search for Agents - View IDENTITY.md / SOUL.md on the detail page
- Click Download ZIP or copy the install command
- Go to the
/fusionpage - Drag & drop Agents from the left panel onto the canvas
- The system auto-creates a dispatcher node and generates routing rules
- Click Export to download ZIP or generate a share link
| Feature | Description |
|---|---|
Soul Browsing (/souls) |
Filter by category, keyword search, multi-dimension sorting (popularity/stars/latest) |
Soul Detail (/souls/[name]) |
View IDENTITY.md / SOUL.md, file list, one-click copy install command, ZIP download |
Fusion Orchestrator (/fusion) |
Drag & drop Agents onto canvas, auto-generate dispatchers and routing rules, undo/redo/auto-layout |
| Team Export | Export assembled Agent teams as ZIP or share links |
Docs Center (/docs) |
Getting started, Soul spec, CLI guide, Fusion orchestration, API reference, community guide |
| Theme Switching | System / Light / Dark mode |
Landing Page (/) |
Project intro, pain points, feature showcase, quick start guide |
Fusion is SoulHub's core innovation — visually drag & drop to assemble Agents and auto-generate multi-Agent collaboration architectures:
- Drag any Agent from the left panel onto the canvas
- System auto-creates a Dispatcher node
- Auto-generates routing rules connecting all Agents
- Supports undo/redo and auto-layout
- Properties panel for editing Agent and routing details
- One-click export as ZIP or shareable link
Separate repo: soulhub-cli
npm install -g soulhubcli| Command | Description |
|---|---|
soulhub search [query] |
Search Agent templates |
soulhub search -c <category> |
Filter search by category |
soulhub search -n <number> |
Limit search results |
soulhub search --json |
Output search results in JSON format |
soulhub info <name> |
View Agent details (identity, soul, skills, etc.) |
soulhub info <name> --identity |
Show IDENTITY.md content |
soulhub info <name> --soul |
Show SOUL.md content |
soulhub info <name> --json |
Output Agent details in JSON format |
soulhub install <name> |
Install Agent (interactive: select role & target claw) |
soulhub install <name> --role main |
Install as main Agent (skip role selection) |
soulhub install <name> --role worker |
Install as worker Agent (skip role selection) |
soulhub install <name> --claw-type <type> |
Specify target claw type (skip claw selection) |
soulhub install <name> --dir <path> |
Install to a custom directory |
soulhub install <name> -y |
Skip all confirmation prompts |
soulhub install --from <source> |
Install from local directory, ZIP, or URL |
soulhub list |
List installed Agents |
soulhub list --json |
Output installed Agents in JSON format |
soulhub update [name] |
Update installed Agents (auto-backup before update) |
soulhub uninstall <name> |
Uninstall an Agent (also deletes related backups) |
soulhub uninstall <name> --keep-files |
Uninstall but keep workspace files |
soulhub uninstall <name> -y |
Skip uninstall confirmation |
soulhub rollback |
Interactive rollback to a previous installation state |
soulhub rollback --list |
List all available rollback records |
soulhub rollback --last <n> |
Rollback the n-th most recent install (1 = latest) |
soulhub rollback --id <id> |
Rollback to a specific backup record by ID |
soulhub rollback --claw-type <type> |
Specify target claw type for rollback |
soulhub rollback -y |
Skip rollback confirmation |
Runtime: Node ≥ 18
git clone https://github.com/lndyzwdxhs/soulhub.git
cd soulhub
# Install dependencies
npm install
# Start dev server (hot reload)
npm run dev
# Or use Makefile
make dev| Command | Description |
|---|---|
make dev |
Start dev server |
make dev-turbo |
Turbopack accelerated dev |
make dev-debug |
Start dev server with Node.js debug mode (port 9229) |
make build |
Production build |
make start |
Start production server (requires build first) |
make build-index |
Build registry index |
make validate |
Validate registry template format |
make lint |
ESLint check |
make typecheck |
TypeScript type check |
make check |
lint + typecheck full check |
make clean |
Clean build artifacts |
make clean-all |
Deep clean (including node_modules) |
make reinstall |
Clean and reinstall dependencies |
Multi-stage build based on Next.js standalone mode — small image size, fast startup.
# One-click deploy (build image + start in background), exposed on port 80
make deploy-docker
# Or step by step
make docker-build # Build image
make docker-run-d # Run in background
make docker-logs # View logs
make docker-stop # Stop container
make docker-shell # Enter container shell# Production deploy
make deploy-vercel
# Preview environment
make deploy-vercel-preview| Layer | Technology |
|---|---|
| Web Platform | Next.js 14 (App Router), React 18, TailwindCSS, Framer Motion |
| Fusion Orchestrator | React Flow (@xyflow/react v12) |
| Theme System | next-themes (System / Light / Dark) |
| CLI Tool | Node.js, Commander, Chalk, Ora, JSZip |
| Template Format | YAML manifest + Markdown (IDENTITY.md, SOUL.md, HEARTBEAT.md) + Skills |
| Containerization | Docker multi-stage build (Node 18 Alpine) |
| CI/CD | GitHub Actions + Vercel |
soulhub/
├── src/
│ ├── app/ # Next.js App Router pages
│ │ ├── page.tsx # Landing page
│ │ ├── souls/ # Soul browsing + detail pages
│ │ ├── fusion/ # Fusion Orchestrator (visual drag & drop)
│ │ ├── docs/ # Documentation center
│ │ ├── api/compose/ # Share API
│ │ ├── c/[id]/ # Share link redirect
│ │ └── index.json/ # Registry index API
│ ├── components/
│ │ ├── landing/ # Landing components (Hero, Features, Pain Points, etc.)
│ │ ├── agents/ # Agent list, cards, detail
│ │ ├── composer/ # Fusion canvas, nodes, panels, export
│ │ └── ui/ # Common UI (Navbar, ThemeToggle, CopyButton, etc.)
│ └── lib/ # Utilities, types, data loading
├── registry/
│ ├── agents/ # 32 Agent templates
│ ├── recipes/ # 3 Team Recipes
│ ├── categories.yaml # Category definitions (7 categories)
│ ├── index.json # Build artifact (search index)
│ ├── manifest.schema.json # Manifest validation schema
│ └── scripts/ # Build + validation scripts
├── .github/workflows/ # CI (build + validate + index)
├── Dockerfile # Docker multi-stage build
├── Makefile # Quick command entry
├── package.json
├── vercel.json
└── tailwind.config.ts
name: writer-xiaohongshu
displayName: Xiaohongshu Content Expert
description: Specializes in Xiaohongshu content creation — product reviews, lifestyle sharing, recommendation posts
category: self-media
tags: [xiaohongshu, content-creation, social-media]
version: "1.0.0"
author: soulhub
minClawVersion: "2026.3.0"Role positioning, core responsibilities, skill boundaries.
Personality traits, communication style, workflow, decision principles.
Daily routines, status updates, activity patterns.
Domain-specific skill packs containing references, templates, and specialized instructions.
- Fork this repository
- Create your Agent directory under
registry/agents/ - Write
manifest.yaml,IDENTITY.md,SOUL.md - Run validation:
npm run validate - Submit a Pull Request
Create a recipe directory under registry/recipes/, including manifest.yaml, soulhub.yaml, and README.md.
- Soul-First — Not sharing code or workflows, but Agent personas, skills, and behavior patterns
- Markdown Native — IDENTITY.md + SOUL.md as standard format, human-readable and editable
- Team Recipes — Support sharing multi-Agent collaboration architectures
- Framework Compatible — Primary support for OpenClaw, designed to adapt to Dify / CrewAI and more
- Open Source Driven — GitHub PR contribution model, community-built