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.
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.
| Measured | What happened |
|---|---|
| 3.64 s | First run: cargo built the project while stoop traced it, then recorded 668 inputs. |
| 0.29 s | Second run: all 668 inputs unchanged, so the build was skipped. |
| 1 line | A comment appended to src/ignore.rs. stoop explain named the file and exited 1: this would run. |
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.
- 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.
- 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.
- 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.
- 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.
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
What it sees, and what it can't.
| Files read, executed, looked up or listed | Traced. Every byte hashed, inside the repository and out, so a changed compiler or lockfile counts. |
|---|---|
| A file that was absent and appears | Recorded as absent inside the repository, so a new config file that would be picked up triggers a run. |
| The environment | Every variable, minus the runner's per-run bookkeeping. --ignore-env NAME exempts one that changes without mattering. |
| What the run wrote in the repository | Must 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. |
- 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=1re-proves everything. Run that nightly. - Anything outside Linux
- Tracing is Linux only. Elsewhere the command just runs.
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.
| Tool | How it learns what a task depends on | What you keep current |
|---|---|---|
| Bazel | Each target declares its sources and dependencies in BUILD files. bazel.build | BUILD files |
| Nx | Hashes a target's inputs: file sets, runtime values and environment variables named in nx.json or project config. nx.dev | inputs and namedInputs |
| Turborepo | By default hashes every git-tracked file in the package; the inputs key narrows it. turborepo.dev | inputs globs |
| actions/cache | You compose the key, usually from hashFiles() over globs you choose. docs.github.com | The key expression |
| stoop | Traces the files the command actually opened, executed, looked up or listed, and hashes those. | Nothing. A .stoopignore for noise, if you want one. |
The field guide.
Everything you need to wrap a step, share proofs between runs, and know where the edges are.
- iGetting started
Install, the first run, reading
explain. - iiHow it works
The tracer, proofs, keys, and every reason it refuses to record.
- iiiCI recipes
GitHub Actions, GitLab CI, CircleCI, Buildkite, the cache directory and git sync.
- ivCLI reference
Every command, flag, variable and exit code.
- v.stoopignore
Paths whose reads don't count.
- viBlind spots
The network, the clock, randomness, and the knobs that cover them.
- viiFAQ
Short answers to the questions people ask first.
- 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.
- Equal build artifacts. Skip downstream steps when a rebuild produced the same bytes, and hash executables without build ids and timestamps.
- Normalized source. Ignore comment and whitespace edits, per language, keeping directives that change behavior.
- Finer grain. Use coverage to tie a test to the code it actually ran.
- A determinism check. Run twice at record time and refuse to record a step that disagrees with itself.
- 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.
- Restored outputs. Let a skip also put back what the command produced.