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.mdyour project’s agent instructionstracked
The primary instruction file Claude Code loads for this project. With the “tell agents about the crystl CLI” toggle on, crystl upserts a primer here (about 11 KB, roughly 130 lines) so any agent discovers it can drive sibling shards. Switching the toggle off stops new ones; blocks already written stay until you delete them or run crystl uninstall --primers.
you own it · crystl appends a bracketed CLI block
•AGENTS.mdinstructions for Codex & other agentstracked
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.mdthe shared task listtracked
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 gemmixed
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.jsonthe gem’s metadataignored
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 shardignored
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 stateignored
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.jsonlwritten by the quest engine
▸sidequests/1:1 side-quest channelsignored
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 JSONtracked
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-upstracked
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 flowstracked
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 logsignored
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 tasksignored
Working notes a shard keeps for itself, one markdown file per shard.
written by crystl / agents
•context-load.jsoncontext-budget trackingignored
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.jsonrelease-readiness crewignored
Config and results for a gauntlet run: the Seekers / Monk / Scribe crew that does a final pass before a merge.
written by crystl
•.gitignoreauto-managed ignore rulestracked
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-tokenthe local bridge keysecret
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 & startersignored
Machine-wide crystl config: your starter-file templates (starters.json), default gems directory, and preferences. New gems inherit from here.
written by crystl
•macOS Keychainyour API keys, not a filesecret
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 →