Concepts
The global store
One content-addressable store of checkouts, artifacts and prebuilts, cloned into every worktree.
The store lives at ~/.spmx/store. Override the location with SPMX_STORE_DIR. It must be on the same APFS volume as your worktrees for zero-copy clones; see APFS clonefile for what happens otherwise.
Layout
| Kind | Path | Keyed by |
|---|---|---|
| Source checkouts | checkouts/<identity>-<revision>/ | package identity and Git revision |
| Binary artifacts | artifacts/<identity>/<target>-<checksum>/ | package, target and checksum |
| Macro prebuilts | prebuilts/<toolchain-hash>/<package>-<version-or-checksum>/ | Swift and Xcode version, then package |
| Index | index.json | linked projects, toolchain fingerprint, last access |
Prebuilts are partitioned by a hash of swift --version and xcodebuild -version. After an Xcode update the old prebuilts are simply not selected, so a stale module ABI is never served.
Hydrate and harvest
spmx hydratereadsPackage.resolved, and for every pin already in the store clones it into the worktree'sSourcePackages(or.build). It rewritesworkspace-state.jsonso paths point at the current worktree.spmx harvestgoes the other way: after a build it copies any new, complete package into the store and records the project inindex.json.
The shims run both for you. A modified checkout is never overwritten unless you pass --force.
Concurrency
Every write to the store takes a per-package flock and goes through atomic staging, so several worktrees, or several AI agents, can hydrate and harvest at the same time.
Inspecting and cleaning
spmx store path # print the store location
spmx store status # packages, sizes, registered projects, estimated copy-on-write savings
spmx store prune # drop entries no registered worktree references