English | 繁體中文 | 简体中文 | 日本語

Soul Forge

Summon AI agents with personality. RPG-style character creation for Claude Code, Gemini CLI, Copilot & more.

Get Started in 3 Steps

uvx agentsoulforge init    # Pick your platform
/sf-summon             # Summon your first character
/sf-party              # View your party

Why Soul Forge?

• Multi-agent orchestration — One prompt triggers multiple expert agents, each responding in their own style and personality
• RPG character system — Manage AI agents like an RPG party: summon, bind, fuse, banish
• 5 platforms, one config — Claude Code, Gemini CLI, Codex, GitHub Copilot, OpenCode — no vendor lock-in
• Pure prompt-based — No API keys, no external services, no runtime dependencies

See It in Action

Ask: "幫我寫一個 REST API for user authentication" — and your party responds:

Each sub-agent activates automatically based on trigger conditions — language detection, code presence, task type, or custom rules.

Installation

# Via uvx (recommended, no install needed)
uvx agentsoulforge init

# Or install globally
pip install soul-forge
soul-forge init

Slash Commands

How It Works

Character Creation

/sf-summon walks you through a wizard:

1. Personality Source — Preset style, URL + character extraction, or custom
2. Expertise — Backend, Frontend, DevOps, Code Reviewer, QA, Architect, English/Japanese Teacher, or custom
3. Naming — Auto-suggested or custom
4. Role — Main Agent or Sub-agent
5. Relationship — Mentor, Friend, Enemy, Rival, Servant, Senior, Junior, Partner, or Custom
6. Response Language — Auto, Chinese, English, or Japanese
7. Trigger Mode — Auto or Manual (sub-agents only)
8. Fine-tuning — Optional attitude override
9. Storage — Project-level or global

Agent File Format

Agents are markdown files with YAML frontmatter:

---
name: jiraiya-architect
personality:
  source: url
  reference: "Jiraiya — Naruto"
expertise: system-architect
role: sub
relationship: mentor
behavior:
  trigger_mode: auto
trigger:
  conditions:
    - task_type: architecture
  execution_mode: after_main
  output_section: "Architecture Review"
---

You are Jiraiya, the legendary Sannin from Naruto.
# ... personality, expertise, and behavior prompts

Automatic Orchestration

Sub-agents with auto triggers activate based on declarative conditions:

• Language detection: contains_english, contains_japanese, contains_chinese
• Content type: contains_code, task_type: backend|frontend|devops|architecture
• Unconditional: always
• Custom: Regex patterns or AI-judged conditions

Execution modes: after_main, before_main, parallel

Supported Platforms

Examples

See the examples/ directory for ready-to-use party configurations:

• fullstack-team — Frontend + Backend + Code Reviewer party
• language-tutors — Anime-powered English + Japanese teachers

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

The easiest way to contribute is adding new expertise templates — it's just a markdown file!

Development

git clone https://github.com/anrylu/soul-forge.git
cd soul-forge
uv venv && uv pip install -e .
uv run pytest -v

License

MIT