Storage
Squeezy writes everything it creates automatically below a single directory, named by the SQUEEZY_HOME environment variable. Nothing lands inside your repository unless you ask for it. Each checkout you open gets its own space in there for sessions, memory, and caches, and one command prints every path in use.
contents
contents
One home, and one command that shows it
SQUEEZY_HOME defaults to ~/.squeezy on macOS and Linux, and to %LOCALAPPDATA%\Squeezy on Windows. Set it to any other absolute path and the whole tree moves with it, which is how you keep Squeezy's data on an encrypted volume or hold two installs apart. A second home starts empty: no settings, no credentials, no sessions, no caches. Your own settings file lives at $SQUEEZY_HOME/config/user-settings.toml, and every project gets a private one of its own inside its space.
squeezy storage paths prints the home in effect, the project you are standing in, and then one row per family of files. Each row carries a class, and the class is what tells you how Squeezy treats it: project files checked into your repository, settings and skills you wrote, credentials, data nothing can regenerate, rebuildable cache, runtime files that live only as long as the process, telemetry, and files you asked for by name.
squeezy storage pathsOne space per checkout
The first time you run Squeezy inside a directory, it registers that checkout and gives it a random 32-character ID, recorded in projects/registry.toml. The ID is not derived from the path, so nothing about your directory layout can be read back out of it. Everything stored for that project lives in one folder named after the checkout, with the ID on the end, so sibling worktrees of the same repository sort together in a listing.
Rename or move a checkout on the same disk and its identity survives with no command from you. Squeezy recognizes the directory itself rather than the path it sits at, and the folder name catches up on the next run. A copy is a different project. A move to another disk is the one case that needs your confirmation, because continuity across disks cannot be proven.
- squeezy projects list shows every project on this machine: its name, whether it was identified as a Git repository or a plain directory, the paths it has been seen at, and its ID.
- squeezy projects relink points an existing identity at a moved checkout. Add --allow-cross-volume when the move crossed disks.
- squeezy projects forget drops one stale path and squeezy projects clean drops every path that no longer exists. Neither deletes the data behind them.
- Wherever a command asks for a project ID, the full folder name works too, so a name pasted out of a directory listing works as written.
squeezy projects list
squeezy projects relink <project-id> /new/path --dry-runWhat you would miss, and what rebuilds itself
Every project space splits along one line. The state directory holds what nothing can regenerate: your sessions, the notes you asked Squeezy to remember, plans, and checkpoints. The cache directory holds what a later run can rebuild: the code knowledge database, search indexes, saved tool output, and the working caches behind them.
That split is enforced rather than assumed. A cache file whose format changed is deleted and rebuilt; a precious one is migrated forward and never dropped. The savings ledger sits in the cache directory but is versioned on its own, so an ordinary cache rebuild does not take your accumulated savings and spend history with it.
If the precious database is ever damaged, opening it stops rather than repairing it quietly. squeezy storage repair-state --dry-run reports what a repair would recover. With --yes it copies the damaged file aside first, rebuilds from every readable row, and prints how many rows each table gave back.
squeezy storage repair-state --dry-runBack up, or reclaim space
The backup rule is short: keep everything under the home except the directories named cache and runtime, both at the top level and inside each project. That covers your settings, your skills and prompts, your credentials, projects/registry.toml, and every project's sessions, memory, and recovery data. The credentials directory holds provider keys and tokens, so treat that copy as carefully as you treat the keys themselves.
squeezy storage clean is how you get space back, and it can only ever take rebuildable files. Pass --class derived to remove the global cache and the current project's cache, or --class runtime to remove only process-lifetime files. Exactly one of --dry-run and --yes is required, and the preview prints exactly what it would remove, so you can size it before committing. Add --project to confine a derived cleanup to one project, or --all-projects to reclaim the knowledge database of every project nothing has touched for a week.
Neither class touches sessions, exports, reports, registry records, or crash reports. And if another Squeezy is running in the same storage, cleanup stops and names that process instead of deleting files underneath it.
squeezy storage clean --class derived --dry-run
squeezy storage clean --class derived --yes
squeezy storage clean --class runtime --dry-runMoving the home, and reading it from a script
Moving the home is deliberate. squeezy storage move --to /absolute/path checks the destination, then prints the four steps: stop every running Squeezy, move the directory in one operation, set SQUEEZY_HOME to the new path everywhere Squeezy is launched, and run squeezy storage paths before restarting. It moves nothing itself, because a half-finished move would break the single-home rule the rest of the tree depends on. The destination has to be absolute, empty or absent, and not nested with the current home in either direction.
Add --json to any of these commands and the answer arrives in the envelope every Squeezy command uses: a top-level schema key holding the version, the command name, and the payload under data. One version number covers the whole CLI, currently 1, so a script pins a single number instead of tracking a per-command schema_version.
squeezy storage paths --json
squeezy storage move --to /absolute/pathWhat stays in your repository
Some things deliberately do not live under the home. A checked-in squeezy-settings.toml, an AGENTS.md, and a .squeezy folder holding project skills, prompt templates, subagents, and shell shapers are inputs: they belong to the repository, travel with a clone, and are read rather than written. Worktrees Squeezy creates for you are the same, made beside the checkout under .worktrees by default.
Anything you name explicitly stays where you named it. An export path, a report path, a session directory, a browser data directory you point at, a file handed to your editor: Squeezy writes there and does not adopt the location as storage of its own.