a field guide to
the crystl filesystem
crystl keeps a private workspace inside every gem and a small set of files on your Mac. Here’s every path it touches, and what travels with your repo versus what stays on this machine. tap any node to open it.
your project
a gem is just a folder; crystl adds one hidden workspace to it.
~/code/your-app/ • CLAUDE.md your project’s agent instructions tracked
The primary instruction file Claude Code loads for this project. With the “tell agents about the crystl CLI” toggle on, crystl upserts a small primer here so any agent discovers it can drive sibling shards.
you own it · crystl appends a bracketed CLI block
• AGENTS.md instructions for Codex & other agents tracked
The cross-agent equivalent of CLAUDE.md. crystl brackets its CLI section with <!-- crystl-cli:begin --> / :end markers so re-running is idempotent and removal is one delete.
you own it · crystl manages the CLI block
• WORKBENCH.md the shared task list tracked
A plain-markdown task list rendered in crystl’s slide-out panel. You and your agents edit the same file: check items off, add what you find, claim tasks with @shard.
read & written by you and your agents
▾ .crystl/ crystl’s private workspace for this gem mixed
Everything crystl needs to run this gem: sessions, worktrees, quest state, and your committed heroes and parties. Most of it is git-ignored; the pieces meant to travel are carved back in.
• project.json the gem’s metadata ignored
Which agents and models each shard runs, the window layout, the selected shard, and per-gem settings. This is what makes a folder a “gem.”
written by crystl
▸ worktrees/ one git worktree per isolated shard ignored
Every isolated shard gets its own git worktree and branch here (a live checkout plus a .base reference), so a dozen agents can write in parallel without ever colliding. Merging a shard lands its branch; closing it preserves the commits.
written by crystl · real git worktrees
▸ quest/ live quest party state ignored
The runtime of an active crystl quest: the shared chat log, per-hero status, and rolling summaries. Delete-safe: it rebuilds when a quest starts.
messages.jsonl · status.json · v2/summaries.jsonl written by the quest engine
▸ sidequests/ 1:1 side-quest channels ignored
State for focused two-shard side quests: a direct back-and-forth line between two agents, which can even span two gems.
written by crystl
▸ heroes/ project heroes, as JSON tracked
One JSON file per local hero. These auto-join every quest party as guardrails, travel with the repo, and apply to every worktree. A single heroes.json array works too.
{ "role_name": "security", "model": "…", "charter": "…" } you author · git-tracked via a .gitignore carve-out
▸ parties/ committed party line-ups tracked
Party definitions saved with --local so the whole team inherits the same crew on clone. Launch one with crystl quest start --party <name>.
you create · git-tracked
▸ questlines/ staged quest flows tracked
Ordered stages a party clears together, advancing only once every hero checks in. Ship them with the repo so a staged flow travels with the project.
you author · git-tracked
▸ history/ per-shard transcript logs ignored
The structured record of each shard’s turns and tool calls that powers history search and crystl history. One log per shard, plus an -active.log for the live session.
written by crystl
▸ tasks/ per-shard scratch tasks ignored
Working notes a shard keeps for itself, one markdown file per shard.
written by crystl / agents
• context-load.json context-budget tracking ignored
How much context each shard has burned. A quest Healer reads this to summarize and hand off before anyone runs out.
written by crystl
• gauntlet.json release-readiness crew ignored
Config and results for a gauntlet run: the Seekers / Monk / Scribe crew that does a final pass before a merge.
written by crystl
• .gitignore auto-managed ignore rules tracked
crystl ignores the runtime bits of .crystl/ but carves out heroes and parties so they ship with the repo. Customize it and crystl leaves your rules alone.
seeded by crystl, then yours
your Mac
a handful of files outside every repo: config, and the keys that stay secret.
~/ • ~/.crystl-bridge-token the local bridge key secret
A private token the crystl CLI and the iPhone app use to talk to crystl’s local bridge. It authorizes control of your gems. Treat it like a password.
a credential · home dotfile
▸ ~/.config/crystl/ global config & starters ignored
Machine-wide crystl config: your starter-file templates (starters.json), default gems directory, and preferences. New gems inherit from here.
written by crystl
• macOS Keychain your API keys, not a file secret
Provider keys (Anthropic, OpenAI, …) live in the macOS Keychain, encrypted by the OS, and are injected into each shell session at runtime. crystl never writes them to disk in plaintext.
OS-encrypted · injected per shard
how it all connects
your files never leave your machine; the bridge token is what lets the CLI and your phone drive them.
on your Wi-Fi the phone connects directly; from anywhere else it routes through an encrypted relay; your data still only lives on your Mac. how the phone connects →