Storage

crystl writes several things to disk as you work: a searchable record of what your agents said and ran, the record of every sequence run, your saved questlines and archived quests, and two caches. None of it is deleted on a timer. It accumulates until you remove it.

storage in settings is where you see what each store costs and clear the parts you no longer want. Open Settings with Cmd+, and pick storage under GENERAL.

The page has four sections: TIMELINE, QUESTS, SEQUENCE RUNS, and CACHES. On a wide window the caches sit in a column to the right of the other three.

What is stored, in one table

Store	Where it lives	What you lose by clearing it
Timeline history	~/.config/crystl/history.db	The ability to search past conversations and commands in crystl, and their usage stats
Sequence runs	~/.config/crystl/sequence-runs/	The evidence behind finished runs: each stage’s outcome, what it produced, and why a failed run failed
Saved questlines	<gem>/.crystl/questlines/	A questline you deliberately saved and can launch again
Custom questlines	~/.config/crystl/questlines/	A questline available in every gem, not just one
Quest archives	<gem>/.crystl/quest-archive/	The chat, questlines, and state of quests that have ended
docs cache	~/.config/crystl/docs-cache.json	Nothing. It is fetched again the next time it is needed
heroes cache	~/.config/crystl/heroes-cache.json	Nothing. It is fetched again the next time it is needed

None of these are your work. Clearing any of them leaves your code, your conversation transcripts, your shards, and everything in your projects exactly where they are.

Timeline history

The timeline is crystl’s own searchable copy of what every agent said and every shell command that ran, across all gems, all sessions, isolated worktrees, quests, and SSH shards. It is what Cmd+Shift+F searches and what crystl history search and crystl history metrics read. See history search for what goes into it.

The section prints the database size, then the row counts behind it: turns, commands, and episodes. The size counts the database file and its write-ahead log (history.db and history.db-wal) as they exist at that moment.

What you lose. This is the ledger behind “what was done”. Clear it and you can no longer search that period in crystl, and its per-model token and cost rollups go with it. You keep every conversation transcript, because crystl only ever reads those. The index can be rebuilt from the transcripts that remain, but the commands and the shards whose transcripts are gone cannot come back.

RECLAIM SPACE

The compact button checkpoints recent changes and rewrites the database so cleared space returns to disk. SQLite does not shrink a file when rows are deleted, so a clear on its own frees nothing. Compacting is what frees it.

Your live history does not change, and neither do row references, so an agent holding a reference to a row can still resolve it afterwards. On a large database this takes a while. The button reports its stage as it goes.

CLEAR OLDER THAN

Pick 30, 90, or 180 days and press clear. The default is 90 days. Everything older than the cutoff goes, everything newer stays.

clear everything

Removes the whole timeline. The button is inside the TIMELINE section and reaches nothing else on the page: your sequence runs, questlines, quest archives, and caches are untouched. The confirmation sheet says what it means, “clear all search history”.

BY GEM

Under the section is a per-gem breakdown: each gem’s path, its turns, commands, and episodes, and a clear for that gem alone. The six largest are listed; show all N gems expands the rest. A gem’s clear removes that gem’s rows and nothing else, and the row shows cleared for a moment when the store confirms it is done.

While a clear or compact is running

Every control on the page is disabled for the duration, because they all touch the same database. A row at the top of the section shows what is running and how long it has been going. The figures on the page are the ones read before the operation started, and they say so with before this operation beside them, rather than quietly showing counts the clear has already changed.

You can leave the settings page and come back. The operation keeps going and the page shows it again when you return.

Sequence runs

Every sequence run leaves a directory behind: its record, the schemas and path briefs pinned when it started, every artifact its stages declared, and the manifests that explain how it was judged. The Sequences drawer lists the last twenty runs per gem, which makes a store of a thousand look handled. This section is where you see the whole thing.

The headline gives the total size, the run count, and how many runs are still going. Below it are per-gem rows with each gem’s run count, size, and still-going count, each with its own clear. clear all run records takes the lot.

What you lose. A run record is the evidence behind one run: what each stage did, what it produced, the basis for every acceptance, and the reason a failed run failed. Someone may still be reading it. Once it is cleared the Sequences drawer no longer lists that run and nothing reconstructs it. You keep everything the run wrote into your project.

Four things are worth knowing before you clear:

• A run that is still going is never cleared. crystl judges this twice, from the runs it is driving right now and from each record’s own status. A status it does not recognise counts as still going, so an unknown state is never mistaken for a finished one.
• A per-gem clear only reaches runs whose record names that gem. Runs that name no gem are listed separately and only clear all run records reaches them.
• A per-gem clear leaves your window where it is. The row names a gem, and pressing its clear clears that gem. It never selects the gem or moves you to it, which is the rule every control in crystl follows except the ones whose whole purpose is to take you somewhere.
• A gem’s clear button is off when every one of its runs is still going. There is nothing for it to do.
• The report line says what happened. After a clear, the section prints how many runs were removed, how much was freed, how many still-going runs were kept, and how many could not be removed. “cleared” on its own would leave a store that is still not empty unexplained. The line sits there for a few seconds.

The first time you open the page, this section says measuring… while it walks the store. The walk grows with the store, so it happens in the background rather than holding up the page.

Quests

Three stores, each cleared by hand and never on a schedule.

SAVED QUESTLINES are the plans you deliberately saved, in <gem>/.crystl/questlines/. Each row has a delete. These are keepers, so deleting one is always your explicit act. If the file was committed, git still has it. If it was not, the delete is permanent. crystl quest templates delete <slug> does the same thing from the terminal.

CUSTOM QUESTLINES live in ~/.config/crystl/questlines/ and are global. One row, however many gems are open, because deleting one removes it everywhere and not just from the gem you happen to be looking at.

Questlines that ship with crystl are not listed. They live inside the app and cannot be deleted.

QUEST ARCHIVES are <gem>/.crystl/quest-archive/, where quests go when they end or are cleared. Each row shows a gem, the size of its archive, and how many quests are in it. clear permanently deletes that gem’s archived quest history: past chat, questlines, and state. Saved questlines in .crystl/questlines/ are kept.

An archive is the recoverable history of a quest, and a saved questline is a deliberate keeper. Clearing archives does not touch the second.

This section only lists gems you have open. A gem that is closed has its questlines and archives on disk, unlisted and unreachable from this page. Open the gem to manage them.

Caches

Two rows, each with its size and its path: the docs cache and the heroes cache. They clear immediately, with no confirmation, because there is nothing at stake. crystl fetches each one again the next time it needs it.

What crystl never clears on its own

Nothing on this page is deleted on a timer, at a size threshold, or after any age. There is no background sweep. Every store here grows until a person asks for it to shrink.

This is deliberate for the sequence run store in particular. A run record is evidence, and deleting evidence on a clock is not crystl’s call to make. A clear happens because you asked for it, in the scope you asked for.

A practical consequence: if you run sequences often, or keep a long history, check this page now and then. A clear frees the timeline’s rows, and compact is what returns that space to the disk.

What this page does not cover

• Isolated worktrees. A gem’s parked worktrees can take gigabytes. They are managed in the gem’s worktrees panel, from the branches button in the shard bar, where each parked branch can be reattached, merged, or discarded. See isolated sessions.
• Agent transcripts. crystl reads the session transcripts your agent writes (Claude Code’s under ~/.claude) and never modifies or deletes them. Clearing the timeline does not touch them.
• Terminal scrollback. That is memory, not disk. Cmd+K or crystl scrollback clear frees a noisy shard’s screen and retained scrollback, and leaves conversation history alone.

From the command line

The timeline controls have CLI equivalents:

crystl history clear --gem myapp          # one gem
crystl history clear --shard citrine      # one shard
crystl history clear --older-than 90      # a cutoff in days
crystl history clear --all                # everything
crystl history compact                    # checkpoint and vacuum

crystl history clear refuses an unscoped clear: pass a scope, or pass --all to say you mean everything. It reports how many turns, commands, and episodes it deleted. It only ever touches the database, never your transcripts or your repository files.

Sequence run records and the quest stores are cleared from settings, storage. There is no CLI for them.