# Hero Shards

> Summon a single hero as a standalone shard — its own agent, model, and persona — without starting a Quest. Launch from the summon-a-hero button next to the shard +, optionally isolated in its own git worktree.

A **Hero Shard** is a single [hero](/docs/quest-heroes) launched as a standalone [shard](/docs/gems-and-shards) — with its own agent, model, and persona — without assembling a [Quest](/docs/crystl-quest) party. When you need one specialist for the task in front of you (a backend agent, a reviewer, a planner), you summon it directly instead of spinning up a whole party and its shared chat.

## Summoning a hero

In any gem, the shard bar has a **summon-a-hero** button right next to the shard `+`. Click it to open the **summon a hero** panel:

1. Optionally flip the **isolated (own git worktree)** toggle.
2. Pick a hero from the grid — each card shows its role (UI/UX, Backend, Reviewer, QA, …) and the agent it runs.
3. The hero opens as a new shard, already set up as that specialist.

That's it — no party, no Quest chat panel. The shard behaves like any other shard in the gem; it just starts with the hero's configuration applied.

## What the hero brings

A Hero Shard inherits everything the hero is configured with:

- **Agent** — the CLI agent the hero runs (Claude Code, Codex, etc.).
- **Model** — the model the hero is set to use.
- **Persona** — the role, personality, stat modifiers, and system prompt that define how the hero works.

So a "Rogue (Backend)" shard and a "Bard (Reviewer)" shard start with different instructions and behavior, even in the same project.

## Isolation

Toggle **isolated (own git worktree)** when you summon, and the hero gets its own git worktree and branch — the same mechanism as any [isolated session](/docs/isolated-sessions). This lets the hero work in parallel with your other shards without touching their files. Leave it off and the hero shares the gem's working directory.

## Where heroes come from

Hero Shards draw from the same roster as Quest:

- Your global hero roster in **Settings**.
- [Local project heroes](/docs/local-heroes) defined in a project's `.crystl/heroes/` folder.

Browse the full catalog — Wizard, Warrior, Ranger, Rogue, Paladin, Bard, Druid, Warlock, Monk, and more — in the [hero library](/library/heroes).

## Spawning heroes from the CLI

You don't have to use the panel. With the [crystl CLI](/docs/cli) enabled (a Guild feature), an agent can spawn hero shards for you:

```bash
crystl hero list                                 # discover summonable heroes
crystl hero summon wizard --gem myapp --isolated              # summon one
crystl hero summon seeker --gem myapp --prompt "audit auth"   # summon and brief it
crystl shard create --gem myapp --hero monk --prompt "run QA" # same route
```

`crystl hero list` is read-only/free and shows the names you can pass (built-in catalog, your global custom heroes, plus the gem's [project-local heroes](/docs/local-heroes)); `crystl hero summon <name>` is a focused alias for `crystl shard create --hero <name>`. Add `--prompt` / `--task` to give the hero its opening assignment immediately, and `--model` to override the configured model for that summon only. Because crystl injects the CLI command reference into each gem's `CLAUDE.md` / `AGENTS.md`, your agent already knows how — just ask it to summon the heroes you want, brief them, and pick the models they should run on.

### Built-ins are immutable; editing one creates a named copy

The built-in heroes (15 core presets ship with the app; **sync from crystl.dev** pulls the full roster, currently 30) are read-only defaults. Editing a built-in in the Heroes settings page **duplicates** it into a **named custom hero** rather than changing the original in place — so you can keep both the stock wizard and your tuned one. Custom heroes are global (they appear in the solo picker, `crystl hero list`, and Quest parties everywhere) and inherit the source hero's avatar. On a name clash, precedence is **project-local > global custom > built-in**, so a committed `.crystl/heroes/` hero always wins over a global custom of the same name.

This is the same agent-neutral, scriptable surface the rest of the CLI uses, so a Claude orchestrator can summon a Codex hero (or vice versa). See the [crystl CLI reference](/docs/cli) for the exact flags.

## Hero Shards vs. crystl Quest

Both use the same heroes; they differ in scope:

| | Hero Shard | [crystl Quest](/docs/crystl-quest) |
|---|---|---|
| How many heroes | One | A party |
| Coordination | None — it's a normal shard | Shared chat: @mentions, handoffs, DMs |
| Setup | One click from the shard bar | Assemble and configure a party |
| Best for | A single specialist for one task | Multiple agents collaborating on one goal |

Reach for a **Hero Shard** when you want one specialist now. Reach for a **Quest** when you want a team working together.

---
Source: https://crystl.dev/docs/hero-shards/