Hero Shards

A Hero Shard is a single hero launched as a standalone shard — with its own agent, model, and persona — without assembling a 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. 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 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.

Spawning heroes from the CLI

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

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); 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 for the exact flags.

Hero Shards vs. crystl Quest

Both use the same heroes; they differ in scope:

	Hero Shard	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.