Rust build toolsRustmacOSLinux

Cargo Steward

Cargo Steward keeps Rust build output bounded and helps people and AI agents work across many git worktrees. I built it after repeatedly running out of disk space during Rust development, then added warm starts, build limits and cache tools to reduce the work those builds repeat.

It is a Cargo subcommand and rustc wrapper for macOS and Linux, with an optional Cargo proxy. Source and releases are MIT licensed.

Install and check the setup

Install from crates.io with Rust 1.89 or newer. Setup makes Cargo Steward your rustc wrapper and turns on automatic cleanup. An existing wrapper, such as sccache, is kept as the inner wrapper. The agent skill is optional.

cargo install --locked cargo-steward
cargo steward setup
cargo steward skill install
cargo steward doctor

Prebuilt binaries

The GitHub release has binaries for aarch64-apple-darwin, x86_64-apple-darwin, aarch64-unknown-linux-gnu and x86_64-unknown-linux-gnu, with a SHA-256 checksum for each archive. The installation guide covers the release installer, upgrades and uninstalling.

Cargo Steward 0.1.0 release downloads on GitHub.

Everyday commands

Start by checking which build directories are managed and previewing a cleanup. The preview changes nothing; add --apply when you want to perform it.

cargo steward doctor
cargo steward status --sizes
cargo steward gc
# Perform the cleanup after reviewing the preview:
cargo steward gc --apply

What cleanup removes

The wrapper removes replaced debug objects after successful incremental compiles. Background cleanup also handles superseded incremental sessions, idle caches, unused build units, old Cargo layouts and build directories from deleted or long-idle worktrees. Rust 1.88 through 1.100 are affected by the debug-object leak; Cargo 1.101 addresses it for its own builds.

When space is low, cleanup prioritizes directories by idle time, unshared size and recorded compile cost. It holds Cargo's locks, skips builds in use, protects running programs, and removes incremental sessions whole. The README lists the default ages and thresholds.

Warm starts for new worktrees

Seeding clones a build the repository already has into an empty worktree target directory. It prefers an available main-checkout build, then a recent alternative. Dependencies can remain fresh while workspace crates rebuild once for their new source timestamps.

Run seed in the new worktree, install the git hook for automatic seeding on worktree creation, or let the Cargo proxy seed on the first build. Cloning requires APFS, btrfs, reflink-enabled XFS or bcachefs, and source and destination on the same volume. Unsupported filesystems continue with a normal cold build.

cargo steward seed
# In the repository, to seed future worktrees when git creates them:
cargo steward hooks install
# Preview sharing identical files across existing build directories:
cargo steward dedup

Route output and limit concurrency

The optional Cargo proxy routes target directories and temporary files, seeds new worktrees and limits whole Cargo builds. max-compiles limits rustc processes machine-wide through the wrapper; max-builds limits whole builds through the proxy.

This example is for a Mac with an existing Scratch volume. Put it in ~/.cargo/steward/config.toml, choosing limits for your machine. On Linux, use the mount paths for your build filesystem.

target-root = "/Volumes/Scratch/{label}/cargo"
tmp-root = "/Volumes/Scratch/{label}/tmp"
max-compiles = 8
max-builds = 4

cargo steward shim install
cargo steward shim explain

Real proxy output from the Cargo Steward checkout, typeset for readability. The output shows which routes and limits actually apply.

Retire a worktree or protect a build

Pin a build directory that must survive between runs. Before removing a worktree, preview removal of its build output, apply it, and then let git remove the worktree. Running builds and programs remain protected.

cargo steward pin /path/to/build-dir
cargo steward unpin /path/to/build-dir

cargo steward remove --worktree ../app-fix
cargo steward remove --worktree ../app-fix --apply
git worktree remove ../app-fix

Use the GitHub Marketplace Action

The Cargo Steward Action works on Linux and macOS runners. This example uses Swatinem/rust-cache to restore and save the cache, and Cargo Steward to trim the build output before the save.

Save this as .github/workflows/rust-ci.yml. The start step goes after cache restore and before the first build. It installs the requested CLI release if the matching version is not already on PATH. The trim step is the last ordinary step, ahead of rust-cache's cache-saving post step.

name: Rust CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: Swatinem/rust-cache@v2
      - uses: 0xdoublesharp/[email protected]
        with:
          mode: start
          version: 0.1.0
      - run: cargo test --locked
      - uses: 0xdoublesharp/[email protected]
        with:
          mode: trim
          budget: 6GiB

Choose budget for the build units you want to retain. The example uses 6GiB; final outputs, target/doc and profiles held by another build are not counted in that limit. Without budget, trim still removes unused units, workspace crates and incremental caches, but does not impose a size limit.

For a workspace in a subdirectory, set working-directory on both Action steps and run the Cargo commands there too. Set target-dir on both steps when you need to select a custom build directory. If rust-cache uses cache-workspace-crates: true, also set keep-workspace: true on trim. keep-incremental: true retains incremental caches during trimming, although rust-cache removes incremental data before saving its own cache.

Leave trim without if: always(). Its normal success condition avoids trimming a cache after a failed or cancelled build has used only part of it. If you use actions/cache instead, split restore and save into separate steps, with trim immediately before the save.

For more options and persistent self-hosted runners, see the CI guide.

For AI coding agents

The bundled skill teaches Claude Code and Codex to work with the wrapper, preview cleanup and retire worktree outputs. doctor, status, gc, remove, dedup and shim explain support JSON output for scripts and agents. See the JSON reference.

From my development machine

On November 8, 2026, a cleanup pass reported a 25.4 GiB free-space increase on my Scratch volume. That is a real log measurement from one machine, rather than an estimate based on directory sizes or a promised saving for another project. The journal post has the chart and the story behind the tool.

Source, documentation and issues

The repository has the full command reference, configuration defaults and implementation notes.

Open Cargo Steward on GitHub