cargo-warmPrivate warm Cargo state for every worktree
Rust worktree acceleration

Keep the warm build. Lose the shared state.

cargo-warm forks useful Cargo and rustc state from a warm checkout into each new worktree's own writable cache. Agents start closer to warm without fighting over one mutable target directory.

Start in 3 commands →See how it works
Private per worktreeCopy-on-writeCargo validated
cargo-warm / worktree init ready
01
warm checkoutCargo build state already paid for
source
APFS clone / reflink
02
private worktree cacheindependently writable from here
isolated
$cargo warm seed

profile balanced · source exact revision

cache forked · freshness verified

$cargo warm check
01diagnosecargo warm doctor
→
02provisioncargo warm seed
→
03iteratecargo warm check

Profiles

Choose where to pay the warm-up cost.

Small crates should not pay for heavyweight priming. Giant crates should not make the first agent edit discover every relocation cost. Profiles let each repository choose.

01

quick

Fastest setup

Fork warm state and repair only proven freshness metadata.

cargo warm seed --profile quick
02good starting point

balanced

Warm compiler

Add a relocatable rustc prime before the first real edit.

cargo warm seed --profile balanced
03

deep

Warm package boundary

Also re-establish the selected package's own build-script boundary.

cargo warm seed --profile deep

Doctor

Do not guess which profile your repo needs.

Doctor works before you create a second worktree. It looks at the selected packages, Rust source size, build scripts, toolchain support, and cache shape. With two worktrees, it also explains freshness and path blockers.

  • Recommends a profile and alternatives worth benchmarking.
  • Prints a starter .agents/.cargo-warm.toml.
  • --probe classifies Cargo's actual fingerprint misses.
Read the diagnostic guide →
cargo warm doctorread-only
project shape
  rustc:       1.98.0 (Stable)
  local Rust:  86,420 lines / 214 files
  build scripts: 1 direct / 2 path deps

recommendation
  profile:     balanced
  why:         large local crate; relocatable rustc available
  compare:     quick, deep

Suggested .agents/.cargo-warm.toml
  default-profile = "balanced"
  clone-pressure = "auto"
  manifests = ["Cargo.toml"]

Safety boundary

Copied state is a hint. Cargo is still the judge.

cargo-warm optimizes the starting point without inventing a second build system. Unknown state stays stale; unsafe mappings fall back to ordinary Cargo revalidation.

1

Rank

Find a nearby compatible, quiescent worktree with real warm state.

2

Fork

Clone Cargo intermediates into a different writable destination path.

3

Prove

Synchronize freshness only across clean, equivalent inputs.

4

Validate

Let Cargo and rustc reopen, invalidate, and compile normally.

Open the architecture map ↗

Guides

Enough internals to use it well.

The docs focus on setup, profiles, diagnosis, and integration. The implementation is there when you need the deeper mechanics.

01Start

Quickstart

Go from install to a worktree hook in a few commands.

Open guide →02Start

Profiles and configuration

Built-in quick, balanced, and deep profiles plus project-local overrides.

Open guide →03Start

Doctor and benchmarking

Project diagnosis, worktree comparison, Cargo fingerprint probes, and a repeatable benchmark method.

Open guide →04Concepts

Architecture

Source selection, cache forking, freshness proof, native state, and relocatable compiler priming.

Open guide →

One hook

Let every new worktree inherit the compile work you already paid for.

cargo install cargo-warm --lockedQuickstart →