tak

A tachometer for code.

Wall-clock time on a shared CI runner has roughly the same noise floor as the regressions people want to catch. tak asks whether retired instruction counts can provide a deterministic signal instead.

Measured on a 32-core Linux host:

That produces one narrow rule: gate on instruction counts; report wall time without gating on it. Syscall counts and peak RSS move with thread scheduling and are not deterministic enough for a tight threshold.

Measurements stay in the repository as JSON lines under refs/notes/tak, merged with git's cat_sort_uniq strategy. There is no database, account, or hosted service.

Read the methodology for the measurements, limitations, and reasoning.

• tak run measures wall time and, where Valgrind is available, instruction counts
• allocations = true or tak run --allocations also counts heap allocations under Valgrind's DHAT. They are recorded and shown in tak compare, and never gate
• tak.toml declares repeatable benchmarks for local and CI runs
• a benchmark can also record custom metrics, such as a file's size in bytes or a number a command prints. They are stored and reported beside the timings, and never gated
• tak run --record, tak push, and tak history store results in git notes
• tak artifact export and tak artifact publish hand measurements from a read-only CI job to a separately trusted publisher
• tak compare reports changes and gates only on instruction counts. It fails when nothing was measured on both sides, unless the allow_empty setting is on ([gate] allow_empty, TAK_ALLOW_EMPTY or --allow-empty), which passes that case with a warning, or --no-gate is given. Under allow_empty a regression still fails; --no-gate never fails on the comparison, though errors such as an invalid tak.toml still do
• tak compare --accept BENCH accepts an intentional regression in one named benchmark while every other benchmark still gates; Tak-Accept: commit trailers do the same once a project opts in
• tak run --save-baseline NAME and tak run --baseline NAME compare a local, uncommitted change against a saved measurement, without touching git notes
• tak run --profile-dir and tak explain show which functions an instruction-count change came from
• tak detect reports instruction-count steps that already landed on a branch, and fails when the newest recorded commit introduced one or when nothing could be compared
• tak log shows each benchmark's measurements over first-parent history, as Markdown or as a self-contained HTML report
• tak backfill measures published release binaries, or builds and measures past commits with --commits, to bootstrap history

tak itself does not post to pull requests. jdx/tak-action, which is also pre-v1, runs tak compare on a pull request and reports the result as a sticky comment and a check run. See Adopt tak in a project.

Change-point detection does not exist. tak detect compares consecutive recorded points against the gate; it is not statistical change-point detection.

• Getting started
• Adopt tak in a project
• Benchmark configuration
• CI and git notes
• CLI reference

The crate is tak-cli; the binary is tak. Releases are automated as described in RELEASING.md.

Use mise so local and CI commands stay aligned:

mise run build
mise run test
mise run lint
mise run ci

Instruction-count tests require Valgrind. Run tak doctor to see what is available on the current host.

MIT