turbo-hot-cache

Warm your local Turborepo cache across a list of branches — in the background, without touching your working checkout.

Paste a list of branches and a turbo command; for each branch the tool:

1. Creates a detached git worktree in a temp directory (your main checkout is never touched)
2. Merges the latest default branch (origin/main) into the branch, so the warmed cache matches what you'd build after updating; branches with merge conflicts are skipped and listed at the end
3. Mirrors loose gitignored files (.env*, *.generated.ts, etc.) from your main checkout into the worktree — these are often turbo hash inputs (globalDependencies, task inputs), and without them every task hash would differ from your real checkout, making the warmed cache useless
4. Installs dependencies (auto-detects pnpm / yarn / npm / bun from the lockfile)
5. Runs your turbo command (e.g. npx turbo run build)
6. Ensures the cache lands in your primary repo: turbo 2.x shares its cache across worktrees automatically (via the git common dir); any cache left in the worktree itself (turbo 1.x) is merged back by copying entries you don't already have
7. Removes the worktree

Turbo's local cache is content-addressed (entries are keyed by task hash), so merging is safe — only entries you don't already have get copied. Afterwards, checking out any of those branches gives you FULL TURBO cache hits.

Supports both cache locations: .turbo/cache (turbo ≥ 2) and node_modules/.cache/turbo (turbo 1.x).

Install

npm install -g .        # from this directory
# or run directly:
node index.js

Usage

Interactive (paste branches, then the command):

cd ~/work/my-monorepo
turbo-hot-cache

Non-interactive:

turbo-hot-cache --command "npx turbo run build" main feat/login feat/billing
turbo-hot-cache --repo ~/work/my-monorepo --command "npx turbo run build lint" --branches "main, develop"

Run it in a spare terminal (or with &) and it warms each branch sequentially while you keep working.

Options

Flag	Description
--repo <path>	Path to the git repo (default: current directory)
--command "<cmd>"	Turbo command to run in each worktree
--branches "<list>"	Comma/space separated branches (also accepted as positional args)
--skip-install	Skip dependency installation in each worktree
--skip-merge	Don't merge the default branch into each branch first
--skip-sync	Don't mirror gitignored files into each worktree
--keep-worktrees	Leave worktrees on disk for debugging

Notes

• Always warms the latest version of each branch: the tool runs git fetch --all first and prefers origin/<branch> over any (possibly stale) local branch. Local-only branches still work.
• Branches are checked out detached, so a branch currently checked out in your main repo can still be warmed.
• If the turbo command fails partway, whatever cache entries were produced are still copied.
• Requires Node ≥ 18 and git ≥ 2.30.