A peregrine falcon in its stoop, wings folded, plunging head first through a cold morning sky above a limestone valley.

Run only what matters.

stoop wraps a command and watches every file it reads. The next time, if none of those files changed, it skips the command. If one did, it runs it and learns again. There are no input lists to write and none to keep current.

$ curl -fsSL https://stoop.build/install.sh | sh

Tracing needs Linux on x86-64 or arm64. On macOS stoop builds and runs the command untraced, and records nothing.

Start with the field guide

Captured, not typed: stoop's own source as a fresh clone, Linux arm64 in a throwaway container, stoop at commit c9082e1. Only cargo's progress lines are cut.

Most of a pipeline has nothing new to say.

CI reruns every step on every push. Most of those steps read the same files they read last time and reach the same answer. When agents push all day, that waste compounds.

stoop picks out the step whose inputs moved and lets the rest stay folded.

A murmuration of thousands of starlings over a frosted marsh, and one peregrine diving at a single bird at its edge.

From the transcript above

One cargo build of stoop itself, measured with the shell's time. A skip still hashes every input byte for byte, the toolchain included. That is the cost of being sure.

MeasuredWhat happened
3.64 sFirst run: cargo built the project while stoop traced it, then recorded 668 inputs.
0.29 sSecond run: all 668 inputs unchanged, so the build was skipped.
1 lineA comment appended to src/ignore.rs. stoop explain named the file and exited 1: this would run.
A peregrine on a limestone ledge, eye fixed on the valley far below.

It watches the command, not a list.

Declared inputs drift. Someone adds a config file, a script reads an environment variable, a toolchain updates, and the cache key never hears about it. stoop doesn't ask. It looks.

  1. Watch. The command runs under a tracer: ptrace plus a seccomp filter, so only file system calls stop. Every path the process tree opens, executes, looks up or lists is noted, child processes included.
  2. Record. When the command passes, stoop writes a proof: each path with a hash of every byte, files that were looked for and absent, directory listings, symlink targets, the environment, and what the run wrote inside the repository.
  3. Compare. Next time it hashes the same paths. If all of them match, the environment matches, and the outputs are still in place, the command is skipped in the time it takes to hash them.
  4. When unsure, run. No proof, an expired proof, a trace that might be incomplete, a read of .git, or use of the network: the command runs and nothing is recorded. Being wrong costs a rerun, never a missed failure.

How it works, in full

Two lines in GitHub Actions.

Put this at the top of a workflow and every run: step goes through stoop. No per-step edits.

defaults:
  run:
    shell: stoop sh {0}

Each step is keyed by its script, the workflow and the job. Steps that use an action (checkout, setup) run as usual, and the step that installs stoop sets shell: bash for itself. Share proofs between runs through your git remote with --sync git, or cache the .stoop/ directory with the CI's own cache. Pull requests read; only the default branch writes.

Recipes for GitHub Actions, GitLab CI, CircleCI and Buildkite

A peregrine on the parapet of a high-rise at dawn, the city in haze far below.

What it sees, and what it can't.

Files read, executed, looked up or listedTraced. Every byte hashed, inside the repository and out, so a changed compiler or lockfile counts.
A file that was absent and appearsRecorded as absent inside the repository, so a new config file that would be picked up triggers a run.
The environmentEvery variable, minus the runner's per-run bookkeeping. --ignore-env NAME exempts one that changes without mattering.
What the run wrote in the repositoryMust still be there, unchanged, for a skip. Throwaway output goes in .stoopignore.
External state you can check--probe CMD: the command's output is hashed into the proof and must match again before a skip.
A peregrine on a dead branch, half lost in valley fog.
The network
A run that connects out is not recorded, and stoop names where it connected. Cover it with a probe, or pass --allow-network.
The clock and randomness
Invisible to a file trace. Proofs expire after 7 days, and STOOP_FULL=1 re-proves everything. Run that nightly.
Anything outside Linux
Tracing is Linux only. Elsewhere the command just runs.

Blind spots and how to cover them

Declared inputs, observed inputs.

Build caches have to know what a task depends on. Most are told. stoop finds out. The other tools do things stoop doesn't, like task graphs, restoring cached outputs and, in Bazel's case, remote execution. stoop is one binary around one command, and it sits happily inside any of them.

ToolHow it learns what a task depends onWhat you keep current
BazelEach target declares its sources and dependencies in BUILD files. bazel.buildBUILD files
NxHashes a target's inputs: file sets, runtime values and environment variables named in nx.json or project config. nx.devinputs and namedInputs
TurborepoBy default hashes every git-tracked file in the package; the inputs key narrows it. turborepo.devinputs globs
actions/cacheYou compose the key, usually from hashFiles() over globs you choose. docs.github.comThe key expression
stoopTraces the files the command actually opened, executed, looked up or listed, and hashes those.Nothing. A .stoopignore for noise, if you want one.
A leather falconry hood, glove, jesses and a brass bell on a wooden perch atop a limestone wall.

The field guide.

Everything you need to wrap a step, share proofs between runs, and know where the edges are.

  1. iGetting started

    Install, the first run, reading explain.

  2. iiHow it works

    The tracer, proofs, keys, and every reason it refuses to record.

  3. iiiCI recipes

    GitHub Actions, GitLab CI, CircleCI, Buildkite, the cache directory and git sync.

  4. ivCLI reference

    Every command, flag, variable and exit code.

  5. v.stoopignore

    Paths whose reads don't count.

  6. viBlind spots

    The network, the clock, randomness, and the knobs that cover them.

  7. viiFAQ

    Short answers to the questions people ask first.

  8. viiiRoadmap

    Where it is going. Not shipped.

Still learning to fly.

Today a skip needs byte-equal inputs. The roadmap loosens that one careful step at a time. None of this is built yet.

  1. Equal build artifacts. Skip downstream steps when a rebuild produced the same bytes, and hash executables without build ids and timestamps.
  2. Normalized source. Ignore comment and whitespace edits, per language, keeping directives that change behavior.
  3. Finer grain. Use coverage to tie a test to the code it actually ran.
  4. A determinism check. Run twice at record time and refuse to record a step that disagrees with itself.
  5. Static vetoes. Refuse to skip a step whose code calls the clock or a random source. This can only make stoop run more, never less.
  6. Restored outputs. Let a skip also put back what the command produced.

The roadmap, with the reasoning

A young peregrine with brown streaked plumage at the edge of its cliff nest, wings half open.