@xgent-ai/skills 0.1.0 → 0.3.0

package/skills/working-with-mbx/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: working-with-mbx
+description: Use when installing, activating, or troubleshooting mbx (Mr. Boxington), the shared compiler cache for Cargo - verifies that plain cargo actually goes through mbx, reads hit/miss/bypass summaries, diagnoses low cache reuse, and manages target/cache disk usage
+---
+
+# Working with mbx
+
+## Overview
+
+mbx (Mr. Boxington) is a shared compiler cache for Cargo, plus automatic management of
+`target/` directories. Cargo still resolves dependencies and decides what needs building;
+mbx restores matching compilations and runs the compiler for everything else.
+
+Use this skill when:
+- Installing mbx or enabling it for plain `cargo` commands
+- A build reports few cache hits and you need to know why
+- Deciding whether an mbx result (hit / miss / bypass) is expected
+- Reclaiming disk from the cache store or managed target directories
+- Adding mbx caching to CI, or migrating off sccache / rust-cache
+
+## The Iron Rules
+
+1. **Never combine mbx with sccache** - both wrap rustc through `RUSTC_WRAPPER`. If
+   `RUSTC_WRAPPER` is already set, mbx defers to it and the build is **not cached**.
+2. **Verify activation by Cargo's path, not by `mbx doctor` alone** - doctor does not
+   recognize the native mise Rust tool option, so its setup warning alone does not mean
+   wrapping is inactive.
+3. **Diagnose before deleting** - run `mbx explain` on the build. Clearing the cache
+   destroys evidence and the next build just runs cold.
+4. **Measure reuse with two fresh target directories** - rerunning the same command in
+   the same target measures Cargo's freshness check, not mbx.
+
+## Install
+
+### With mise (preferred)
+
+```bash
+mise use --global --tool-option mr_boxington=true rust mr-boxington
+```
+
+Requires mise 2026.9.2 or newer. This installs Rust and mbx and enables Cargo wrapping
+through mise - no `mbx setup` needed. `--tool-option` applies to the **following** tool,
+so it must stay before `rust`. Drop `--global` to enable it only in the current project.
+
+To share it with a project, commit both tools in `mise.toml`:
+
+```toml
+[tools]
+rust = { version = "stable", mr_boxington = true }
+mr-boxington = "latest"
+```
+
+Both entries are required. Keep the project's existing Rust version when adding
+`mr_boxington = true`. Run `mise install`, then build.
+
+### Without mise
+
+```bash
+cargo install mbx --locked
+mbx --version
+```
+
+Release archives for Linux (x86-64/ARM64, glibc and musl), macOS Apple Silicon, and
+Windows (x86-64/ARM64) are on GitHub Releases with `SHA256SUMS`. See
+[references/installation.md](references/installation.md).
+
+To make plain `cargo` use mbx from a standalone install:
+
+```bash
+mbx setup
+mbx setup --status
+```
+
+`mbx setup` also configures rust-analyzer's background check - the native mise option
+does not. Scope it with `--global` or `--local`; `--yes` accepts the recommendation.
+
+## Verify mbx Is Actually Being Used
+
+This is the single most common failure: builds succeed, but nothing is cached.
+
+```bash
+command -v cargo     # Unix
+mbx doctor
+```
+
+On Windows use `(Get-Command cargo).Path` or `where.exe cargo`.
+
+`cargo` should resolve to one of:
+- mise's command wrapper (e.g. `~/.local/share/mise/command-wrappers/bin/cargo`)
+- a mise shim
+- the stable mbx shim from `mbx setup`
+
+**Calling `~/.cargo/bin/cargo` directly bypasses mise's integration entirely.**
+
+### Non-interactive contexts (coding agents, SSH, desktop apps)
+
+These often inherit a different `PATH` than an interactive terminal. Use either:
+
+```bash
+mise exec -- cargo build      # explicit, always works
+```
+
+or put mise's shims directory on that process's `PATH`. Check with `command -v cargo`
+run *by the application itself*, and restart the app after changing its environment.
+Prefixing with `mbx` also always works: `mbx build`.
+
+## Running Builds
+
+`mbx` passes Cargo arguments through unchanged:
+
+```bash
+mbx build
+mbx test --workspace --all-features
+mbx clippy --workspace --all-targets -- -D warnings
+mbx +stable check --workspace          # rustup-style toolchain selection
+```
+
+Use the same toolchain, features, and profile across builds to reuse the same cached work.
+
+## Reading the Result
+
+A build prints a summary like:
+
+```
+mbx[cache]: 139 hits, 8 misses, 4 not looked up, 147 prefetched, 7 bypassed; 312.4 MiB downloaded, 0 B uploaded, 280.1 MiB stored locally
+```
+
+| Result | What happened |
+| --- | --- |
+| Hit | mbx restored a matching compilation |
+| Miss | No result matched the key; successful compilation fills the cache |
+| Not looked up | mbx lacked a usable input prediction and had to compile first |
+| Bypassed | The invocation ran without shared caching |
+
+Counts describe compiler actions mbx observed. They do **not** include work Cargo skipped
+because its outputs were already fresh - which is why a rerun can show zero hits.
+
+```bash
+mbx explain --last              # inspect the last recorded build, without running Cargo
+mbx explain build --workspace   # run a build with diagnostics (preserves Cargo's exit status)
+MBX_SUMMARY=full mbx build      # detailed breakdown
+mbx tui                         # watch a build live, one row per compilation
+```
+
+### Measure real cache reuse
+
+```bash
+mbx build --target-dir target/cache-demo-first
+mbx build --target-dir target/cache-demo-second
+```
+
+The second build can restore work recorded by the first. Use directory names that do not
+already contain build outputs, and remove them afterwards - explicit targets are not
+managed. Always compare wall-clock time too; "compiler time avoided" is summed across
+actions, not elapsed time saved.
+
+## Troubleshooting a Low Hit Rate
+
+Run `mbx explain build --workspace` first - it groups identical causes and prints guidance
+per category. Usual causes, roughly in the order they appear:
+
+- **The store is cold.** A first build has no dep-info to derive keys from, so
+  "could not look up" can dominate.
+- **Incremental builds are enabled.** With `MBX_INCREMENTAL=1`, workspace members compile
+  incrementally, those compilations bypass the cache, and crates above them miss too.
+- **A link could not be described.** Native executables, tests, and proc macros are cached
+  on Linux, macOS, and Windows, but links with custom or unmodeled inputs still run.
+- **The inputs differ.** A different toolchain, feature set, profile, or `RUSTFLAGS`
+  between checkouts is a different key, reported as an ordinary miss.
+- **Build-script output differs.** A build script that embeds the checkout path in its
+  output prevents reuse across checkouts.
+- **The build chose its own C compiler.** Setting `CC`, `HOST_CC`, `CXX`, or `HOST_CXX`
+  leaves host compilations outside mbx.
+- **A Rust update.** The compiler is part of every key, so a toolchain roll invalidates
+  every rustc action at once. This is expected, not a bug.
+
+For a per-compilation record: `MBX_BYPASS_LOG=bypass.log mbx build`.
+
+### Bypasses that are expected
+
+`compiler-query` and `standard-input` are routine compiler probes with no output to cache.
+The short summary leaves them out of its bypass count. Don't chase them.
+
+## Other Common Symptoms
+
+| Symptom | First check |
+| --- | --- |
+| Plain Cargo does not use mbx | `command -v cargo`; for standalone setup also `mbx setup --status` |
+| Cargo waits for a target lock | Give simultaneous builds separate target directories |
+| Cargo metadata fails before a build | `cargo metadata --no-deps --format-version 1` |
+| Build storage is on NFS | Move `cache_dir` / `target.root` to local storage (mbx refuses NFS) |
+| Remote requests fail | `mbx doctor`, then check authentication |
+| Storage larger than expected | `mbx cache stats`, then `mbx gc --dry-run` |
+
+### Bypass mbx for one command
+
+```bash
+MBX_DISABLE=1 cargo build
+```
+
+### Reporting a problem
+
+```bash
+mbx doctor --json
+MBX_LOG=debug mbx build
+MBX_BYPASS_LOG=bypass.log mbx build
+```
+
+These name absolute cache paths, any configured remote, and the crates you build.
+Credentials are never printed.
+
+## Managed Target Directories
+
+Managed targets are **on by default**. For a checkout without an existing `target/`, mbx
+places the target under its cache root and leaves a symlink:
+
+```
+target -> <cache root>/targets/v1/<checkout digest>
+```
+
+In a Git checkout, mbx adds the link path to `.git/info/exclude` when necessary, so
+`git status` stays clean without touching the project's `.gitignore`.
+
+mbx leaves the target alone when `--target-dir`, `CARGO_TARGET_DIR`, or Cargo's
+`build.target-dir` names it.
+
+Bring existing directories under management without deleting their contents:
+
+```bash
+mbx adopt                            # the current checkout
+mbx adopt --recursive --dry-run ~/src  # preview
+```
+
+Disable placement with `MBX_TARGET_VIEWS=0` or `[target] views = false`.
+
+## Disk Management
+
+```bash
+mbx cache stats     # action store, managed targets, learned incremental state
+mbx cache dir       # where the store lives
+mbx gc --dry-run    # preview collection under the configured budgets
+mbx gc              # collect
+mbx clean           # this workspace's managed target, link, and incremental state
+mbx cache remove /path/to/workspace   # the above, plus forget its cache claims
+mbx stats           # lifetime savings
+```
+
+Collection runs automatically after builds, at most once an hour. Budgets scale with the
+disk holding the data:
+
+| Budget | Default | Bounds |
+| --- | --- | --- |
+| `gc.max_size` (action store) | 5% of the disk | 5 GiB to 500 GiB |
+| `target.max_size` (managed targets) | 10% of the disk | 10 GiB to 100 GiB |
+| `gc.incremental_max_size` (learned incremental) | 5% of the disk | 10 GiB to 100 GiB |
+
+Managed targets are also collected after `target.max_age` (30 days) unused, and whenever
+their checkout is gone. The cache is disposable - it can always be rebuilt. Note that
+`cargo clean` does **not** remove mbx's private incremental state; `mbx clean` does.
+
+## Configuration
+
+Three sources, first value found wins:
+
+1. Environment variables (`MBX_*`)
+2. `.mbx.toml` at the Cargo workspace root - **build-policy and scheduler settings only**
+3. `mbx/config.toml` in the platform config directory:
+   - Linux: `~/.config/mbx/config.toml`
+   - macOS: `~/Library/Application Support/mbx/config.toml`
+   - Windows: `%APPDATA%\mbx\config.toml`
+
+Unknown TOML keys are rejected, so a misspelled setting is an error. Machine paths,
+remote-cache configuration, credentials, target placement, and garbage collection are
+**not** accepted from a repository's `.mbx.toml`.
+
+Keep a laptop responsive by capping the machine-wide compiler pool (it defaults to every
+logical CPU and 85% of physical memory):
+
+```toml
+[scheduler]
+cpus = 4
+memory = "8GiB"
+```
+
+Per-feature off switches:
+
+| Switch | Turns off |
+| --- | --- |
+| `MBX_SCHEDULER=0` | machine-wide compile scheduling |
+| `MBX_CC=0` | build-script and `mbx exec` C/C++ caching |
+| `MBX_TARGET_VIEWS=0` | managed target directories |
+| `MBX_CACHE_LINKS=0` | native link caching |
+| `MBX_LEARNED_INCREMENTAL=0` | learned incremental reuse |
+| `MBX_SAVINGS=off` | the savings line |
+
+## CI
+
+```yaml
+steps:
+  - uses: actions/checkout@v7
+  - uses: jdx/mr-boxington-action@v1
+  - run: mbx test --workspace
+```
+
+Install the toolchain **before** the action - generated keys cover the OS, architecture,
+and the identity of the `rustc` on `PATH`. Pushes to the default branch fill the archive;
+pull requests, including from forks, are restore-only. mbx automatically uses its
+explanatory CI summary when `CI` or `GITHUB_ACTIONS` is set.
+
+Migrating from sccache is **removal**: take it out of `RUSTC_WRAPPER`,
+`build.rustc-wrapper` in `~/.cargo/config.toml`, and any install steps, then run
+`mbx doctor`. Migrating from rust-cache is replacing the action - running both over the
+same paths adds duplicate restore/save work.
+
+## Available References
+
+- [references/getting-started.md](references/getting-started.md) - install to first cached build
+- [references/setup.md](references/setup.md) - Cargo wrapping, rust-analyzer, verifying Cargo's path
+- [references/troubleshooting.md](references/troubleshooting.md) - symptom table and diagnostics
+- [references/cache-results.md](references/cache-results.md) - hit/miss/bypass, measuring reuse
+- [references/limits.md](references/limits.md) - exactly what mbx will and will not cache
+- [references/managed-targets.md](references/managed-targets.md) - target placement, adoption, budgets
+- [references/configuration.md](references/configuration.md) - full setting reference
+- [references/incremental.md](references/incremental.md) - learned incremental reuse
+- [references/scheduling.md](references/scheduling.md) - parallel builds, machine-wide pool
+- [references/github-action.md](references/github-action.md) - CI setup
+- [references/cookbook/migrate.md](references/cookbook/migrate.md) - from sccache or rust-cache
+- [references/cookbook/local-development.md](references/cookbook/local-development.md) - editors, watch loops, debugging
+- [references/remote-cache.md](references/remote-cache.md) - cache server and S3 backends
+- [references/cli/](references/cli/) - per-command flags and arguments
+
+Refresh all of the above with `./update-docs.sh`.
+
+## Red Flags - You're About to Violate
+
+- Leaving sccache configured "just in case" → mbx silently stops caching
+- "`mbx doctor` warned about setup, so mbx isn't active" → check `command -v cargo` first
+- Running the same build twice in one target to prove caching works → measures Cargo freshness
+- Clearing the cache to fix a low hit rate → run `mbx explain --last` first
+- Chasing `compiler-query` / `standard-input` bypasses → routine probes, nothing to cache
+- Telling a coding agent or CI script to call `~/.cargo/bin/cargo` → bypasses mise integration
+- Putting `[remote]` credentials in a checked-in `.mbx.toml` → rejected; use env vars
+- Adding `cargo clean` to a watch loop → throws away Cargo's freshness information

package/skills/working-with-mbx/references/acknowledgements.md

@@ -0,0 +1,37 @@
+Acknowledgements
+
+Acknowledgements [​](#acknowledgements)
+
+mbx depends on Cargo and builds on ideas established by earlier compiler caches. In particular, kache directly inspired the project's design.
+
+## Cargo [​](#cargo)
+
+[Cargo](https://github.com/rust-lang/cargo) resolves dependencies, plans builds, and orchestrates rustc. Its `RUSTC_WRAPPER` integration lets mbx and other Rust compiler caches wrap compiler invocations.
+
+## sccache [​](#sccache)
+
+[sccache](https://github.com/mozilla/sccache) predates mbx and established compiler caching in the Rust ecosystem. It reuses compiler work locally and through remote storage, and supports a broader set of compilers and use cases than mbx.
+
+See the [comparison with sccache](https://mr-boxington.jdx.dev/compared#sccache) for where mbx makes different tradeoffs.
+
+## kache [​](#kache)
+
+[kache](https://github.com/kunobi-ninja/kache) predates mbx and directly inspired its design. It combines a content-addressed `RUSTC_WRAPPER` cache with C and C++ compiler shims, remote storage, and executable caching.
+
+The projects do not share code. Both aim to make compiled work reusable across checkouts; they differ in process lifecycle, storage management, and remote policy. The [comparison with kache](https://mr-boxington.jdx.dev/compared#kache) explains where mbx took a different direction and where kache may be the better fit.
+
+## cargo-pretty [​](#cargo-pretty)
+
+[cargo-pretty](https://github.com/romancitodev/cargo-pretty) by [romancitodev](https://github.com/romancitodev) provides the base for mbx's Cargo display: live and completed crate rows, per-crate timers, fading, and browsable warnings. mbx adds cache statistics and a progress bar colored by hits, misses, and bypasses while retaining Cargo's native run and test execution.
+
+The adapted source retains romancitodev's MIT license and records the upstream revision in the repository's `NOTICE` file.
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/acknowledgements.md)
+
+Last updated:
+
+Pager
+
+[Previous pageProtocol compatibility](https://mr-boxington.jdx.dev/protocol-compatibility)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)

package/skills/working-with-mbx/references/benchmarks.md

@@ -0,0 +1,140 @@
+Benchmarks
+
+Benchmarks [​](#benchmarks)
+
+mbx is measured against plain Cargo and [kache](https://github.com/kunobi-ninja/kache) on [jdx/hk](https://github.com/jdx/hk), a mid-size Rust CLI with C dependencies, pinned to one commit and built with `cargo build --locked`. The scenarios cover work a developer or CI runner may repeat. Published results come from GitHub Actions. The page labels a tool fastest only when its lead exceeds the observed variation between trials.
+
+[warm8.1s1.25× faster than kache](#warm) [commit26.2s1.66× faster than Cargo](#commit) [edit6.0slevel with Cargo](#edit) [contention1m 9s23.7s sooner than scheduler off](#contention)
+
+### warm CI rebuilds a commit it has already built
+
+The store is warm from an earlier build of the same commit and target/ is empty. Cargo is left out: with nothing to reuse it would repeat that earlier build.
+
+wall clock · lower is better
+
+| Tool | Relative wall clock | Median and range |
+| --- | --- | --- |
+| mbxfastest |  | 8.1s 7.9–8.6s |
+| kache |  | 10.1s 9.8–10.3s |
+
+mbx fastest, 2.0s ahead of kache. That lead is wider than either tool's own range across 3 runs.
+
+mbx restored 1,560 output files on 722 cache hits.
+
+### commit CI builds the next push
+
+The caches were warmed at the parent commit and build the child. Cargo has no cache to restore, so its row is the uncached build.
+
+wall clock · lower is better
+
+| Tool | Relative wall clock | Median and range |
+| --- | --- | --- |
+| mbxfastest1.66× faster than Cargo |  | 26.2s 25.7–26.5s |
+| kache1.53× faster than Cargo |  | 28.4s 28.3–28.8s |
+| Cargouncached |  | 43.5s 42.5–44.3s |
+
+mbx fastest, 2.2s ahead of kache. That lead is wider than either tool's own range across 3 runs.
+
+mbx restored 1,558 output files on 721 cache hits.
+
+### edit One line changed, rebuilt in place
+
+The local edit loop with incremental compilation on. Cargo's own incremental rebuild is the thing to beat here, not a control.
+
+wall clock · lower is better
+
+| Tool | Relative wall clock | Median and range |
+| --- | --- | --- |
+| Cargoincremental rebuild |  | 5.9s 5.8–5.9s |
+| mbxlevel with Cargo |  | 6.0s 5.9–6.1s |
+| kachelevel with Cargo |  | 6.1s 5.9–6.1s |
+
+Too close to call: Cargo and mbx finished 0.09s apart, inside the 0.2s one of them moved across its own runs.
+
+mbx restored 2 output files on 1 cache hits.
+
+First edit after a build, before the loop settles: Cargo 6.3s, mbx 22.6s, kache 24.8s.
+
+### contention Six CI jobs on one runner
+
+Overlapping check, Clippy, and test-compilation jobs. Run one after another, then all at once with and without mbx's machine-wide compiler limit.
+
+wall clock · lower is better
+
+| Tool | Relative wall clock | Median and range |
+| --- | --- | --- |
+| sequential31 compilers at peak, 63.2 GB free at the low |  | 1m 49s 107.7–109.6s |
+| parallelscheduler off170 compilers at peak, 54.1 GB free at the low |  | 1m 33s 90.7–93.7s |
+| parallelmbx schedulerfastest32 of 32 permits used, 61.7 GB free at the low |  | 1m 9s 60.4–72.3s |
+
+With the scheduler on, the parallel batch finished 23.7s sooner than unscheduled and 39.5s sooner than running the jobs in turn, peaking at 32 compilers instead of 170.
+
+Cache hits over the batch: sequential 8; parallel, scheduler off 12; parallel, mbx scheduler 3,390. The scheduler holds identical compilations until the first finishes, so the other jobs hit the store instead of repeating the work.
+
+Measured on Linux-7.1.4-x86\_64-with-glibc2.39 (nsc-runner-g7llknk0pjtlu) with Rust 1.97.1, building `hk` at `fc29ead` under mbx 1.11.1, cargo 1.97.1 (c980f4866 2026-06-30), rustc 1.97.1 (8bab26f4f 2026-07-14), kache 0.21.0. [The run that produced them](https://github.com/jdx/mr-boxington/actions/runs/34930250982) has the per-build logs.
+
+## Reading the results [​](#reading-the-cards)
+
+Each scenario has three independent trials per tool. A trial starts with a fresh clone and empty store, then performs the scenario's warm-up and measured builds. The bar shows the median; the whisker spans the fastest and slowest trial. A tool is marked fastest only when its lead exceeds both tools' trial ranges. Otherwise, the card reports no clear winner.
+
+The Cargo row means something different in each scenario, so the card tags it. In the commit scenario it is the uncached build CI does without a cache. In the edit scenario it is the incremental rebuild the caches have to keep up with. The warm scenario has no Cargo row, because with an empty `target/` Cargo would repeat the build that warmed the store.
+
+## The scenarios [​](#the-scenarios)
+
+### Warm build [​](#warm-build)
+
+A first build warms the store, then `target/` is wiped and the same commit builds again. This is a runner restoring its cache and building something it has already seen.
+
+### Next commit [​](#next-commit)
+
+The store is warmed at one commit and the build runs at the next. Most of the dependency graph is unchanged and a few crates are not. Cargo's row is a cold build, since with an empty `target/` that is all it can do.
+
+### Local edit [​](#local-edit)
+
+A full build, then one line of hk's own source changed and rebuilt in the same `target/` with incremental compilation on. This measures the edit/build loop, including cache bookkeeping and incremental compilation. Two details make the comparison useful:
+
+- `CI` is unset for every tool. mbx switches [learned incremental reuse](https://mr-boxington.jdx.dev/incremental#learned-incremental-reuse) off in CI because fresh runners have no earlier edit state to reuse.
+- The first edit establishes incremental state; the second supplies the headline timing. Cargo's own build already wrote its incremental state, while mbx builds an edited crate's [private state](https://mr-boxington.jdx.dev/incremental#learned-incremental-reuse) on the first edit and reuses it afterwards. The card shows what that first edit cost, since a developer waits for it once per fresh build.
+
+### Six parallel jobs [​](#six-parallel-jobs)
+
+Six overlapping Rust CI jobs from an empty store: default and all-targets/all-features variants of `cargo check`, Clippy, and test compilation. The sequential row runs them in turn in one `target/`. The two parallel rows give each job its own `target/`, as separate CI steps would, and differ only in whether the [machine-wide scheduler](https://mr-boxington.jdx.dev/scheduling#machine-wide-compile-scheduling) is on. Cargo bounds the compilers it starts itself and knows nothing about the Cargo process beside it; the scheduler gives every process one pool of permits and holds identical compilations until the first finishes. Peak compilers and lowest free memory show whether a faster batch shared the machine or oversubscribed it.
+
+## Keeping it fair [​](#keeping-it-fair)
+
+- The registry is fetched once, before any timed build. No cell is timed while it downloads crates.
+- Every trial starts from a fresh clone, an empty store, and a new `target/`. Nothing carries over between tools or between runs.
+- The toolchain is the runner's, the same as any user's build, and the `toolchain` field in `results.json` records which release produced the numbers. Every trial in a run uses that one compiler, so the tools are compared fairly against each other. A Rust bump between runs changes every cache key at once, which reads as a cache that stopped working, so check that field before treating a drop across runs as a regression.
+- `CARGO_INCREMENTAL=0` matches CI everywhere except the edit scenario. Any inherited `RUSTC_WRAPPER` is cleared, and the run fails if the Cargo baseline turns out to be an mbx shim.
+- Both caches run local-only. A remote would measure the network.
+- Validity checks reject runs that do not exercise the intended cache behavior. That is any run where a warm build restored nothing or was no faster than the build that seeded it, where the edit rebuild compiled nothing, or where the scheduled contention batch went past its permits or the unscheduled one never did.
+
+## Running it yourself [​](#running-it-yourself)
+
+sh
+
+```
+mise run bench
+```
+
+That builds mbx, clones hk, and runs the warm, commit, and edit scenarios once each. kache is included when it is on `PATH` and noted as skipped otherwise. `mise run bench:refresh` is what CI runs: every scenario, three trials each, written to `benchmarks/results.json`.
+
+The [bench-refresh workflow](https://github.com/jdx/mr-boxington/actions/workflows/bench-refresh.yml) checks weekly and reruns when the recorded mbx version differs from the latest release. It measures that released version and opens a pull request with the results. On `main`, a manual run with `force` also opens or updates that PR, even when the recorded version already matches. Set `dry_run` to measure without proposing an update, or `source` to measure the selected source ref instead of the latest release; `source` implies `dry_run`.
+
+## What this does not measure [​](#what-this-does-not-measure)
+
+These results describe the pinned hk workload. A project with a very different dependency shape, such as heavy proc macros, a large C component, or many small leaf crates, will see different ratios. Three trials expose some variation; their ranges are not confidence intervals, and a “fastest” label is a display heuristic, not a statistical significance test. The benchmark is Linux-only, and [limits](https://mr-boxington.jdx.dev/limits) covers what changes on macOS and Windows.
+
+Instruction-counted measurements of mbx's own startup path, and cold and warm correctness runs against this workspace, live in [`benchmarks/`](https://github.com/jdx/mr-boxington/tree/main/benchmarks).
+
+[Edit this page on GitHub](https://github.com/jdx/mr-boxington/edit/main/docs/benchmarks.md)
+
+Last updated:
+
+Pager
+
+[Previous pageHow mbx compares](https://mr-boxington.jdx.dev/compared)
+
+[Next pageFAQ](https://mr-boxington.jdx.dev/faq)
+
+MIT License·Copyright © 2026· [jjdx.dev](https://jdx.dev)