# Hero Shards

> Summon a single hero as a standalone shard with its own agent, model, and persona, without starting a quest. Launch from the summon-a-hero row in the shard bar creation column or from a split pane, 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, hover the shard bar's `+` and a glass column drops beneath it. Click **summon a hero**, the crossed-swords row, 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.

### From a split pane

You can also summon a hero straight into a new pane. Open a [split view](/docs/split-view/) and the picker for the empty pane lists **+ summon a hero** alongside **+ new shard** and **+ new isolated shard**. It opens the same catalog, so the hero lands in the pane beside your current work, which helps when you want a reviewer or a backend specialist visible next to what you're doing rather than a shard away. The row appears only when quest is enabled.

## 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**: what the hero launches on. Heroes ask for a [model size](/docs/model-sizes/) rather than a model id, so the same hero works on any agent. The size resolves through your own agent setup. Without one for the agent you run, the hero simply inherits your agent's own configured model.
- **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
```

Once a hero is running, follow-up work goes to it with `crystl send --gem myapp --shard <name> "<task>" --wait`. The `--wait` matters for an orchestrator handing a specialist its next job: a hero mid-turn still counts as delivered (the message lands in the agent's input queue), and the exit code separates delivered (`0`) from queued-behind-the-current-turn (`3`, **don't re-send**) from no-receipt-while-idle (`1`, safe to retry).

`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 or a split pane | Assemble and configure a party |
| Best for | A single specialist for one task | Multiple agents collaborating on one goal |

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

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