FAQ

The questions people ask first, answered short.

A lone peregrine high over a limestone escarpment at dusk.

Can a skip hide a broken build?

Only through a blind spot: something the command depended on that isn't a file it read, like the network, the clock, or a service outside its process tree. stoop refuses to record runs that touch the network or local services unless you cover them, expires proofs after 7 days, and re-proves everything when STOOP_FULL=1 is set. Everything it can't vouch for, it runs. Blind spots lists them all.

How fast is a skip?

As fast as hashing every recorded input. The cargo build in getting started recorded 668 inputs, the Rust toolchain included; skipping it took 289 ms against 3.64 s for the build. stoop reads every byte rather than trusting timestamps, so the cost grows with the size of what the command read.

Does tracing slow the first run down?

Some. The seccomp filter only stops file and connection system calls, so compute-heavy steps pay little and steps that touch many files pay more. Measure your own steps with time under STOOP_OFF=1 and without.

How is this different from a build cache?

A build cache needs to be told what a task depends on, through declared inputs, globs, or a key you compose. stoop watches the command and finds out. Build caches also restore outputs and model task graphs, which stoop doesn't. They combine fine: wrap the cache's command in stoop and both do their job. The comparison on the home page has sources.

Why did a reverted change rebuild?

Because the build's earlier proof also requires the outputs it left in the repository to be in place, and the build in between rewrote them. Steps with no outputs in the repository, like tests, lint and type checks, do skip after a revert. Restoring outputs is on the roadmap.

Does it work with Node, Python, Go, Java?

It works with programs, not languages: anything that reads files through ordinary system calls on Linux. Node's io_uring file access is refused with ENOSYS, so Node falls back to calls the tracer sees. 32-bit programs on a 64-bit kernel use a syscall ABI the tracer doesn't follow; those runs aren't recorded.

Monorepos?

Yes, and that's where it shines: wrap each package's step, and each one only runs when something it actually read changed. The key includes the working directory, so npm test in two packages gets two keys.

Why Linux only?

The tracer is built on ptrace and seccomp. On macOS stoop still builds, and runs the command without tracing, so one workflow works on both; it just never skips there.

Is it safe on pull requests from forks?

Proofs only matter if something reads them. Pull request runs can read the default branch's proofs and should never write shared ones: keep STOOP_SYNC_WRITE unset there, save the CI cache only from the default branch, and use --no-record if you want a job to write nothing even locally.

Is tracing new?

No. Build tools have watched file access before, among them memoize.py with strace and tup. stoop applies the idea to CI steps: any command, no build file, proofs shared between runs.

Why "stoop"?

A stoop is a peregrine's hunting dive. It folds its wings, ignores everything else in the sky, and drops on the one thing that matters.