A test runner wrapper that reduces CI makespan by scheduling the identical-machines scheduling problem: assign tests to N worker processes so that the maximum worker runtime is minimized. This is closely related to the bin packing problem. It ships MultiFit (default) and LPT (Longest Processing Time first) algorithms, with optional work-stealing between workers at runtime.

binpacker ships an agent-driven install and setup flow. Paste this to your AI coding agent (Claude Code, Cursor, etc.) and it will install binpacker and walk the setup interactively:

Install binpacker in this project by following the instructions at
https://raw.githubusercontent.com/rigortype/binpacker/master/docs/install.md

The agent installs the gem, runs binpacker describe to inspect the project, and follows the recommended skill (binpacker-setup or binpacker-improve). See docs/design/agent-workflows.md.

Install the gem:

gem install binpacker

Add a binpacker.yml at your project root:

profiles:
  default:
    test_runner: rspec
    workers: auto
    timing_file: binpacker.timings
    test_pattern: "spec/**/*_spec.rb"
    scheduler:
      algorithm: multifit
      steal_enabled: true
  ci:
    extends: default
    workers: 4

For Minitest projects, set test_runner: minitest and use your test glob:

profiles:
  default:
    test_runner: minitest
    workers: auto
    timing_file: binpacker.timings
    test_pattern: "test/**/*_test.rb"
    scheduler:
      algorithm: multifit
      steal_enabled: true

Run calibration once to seed timing data (required before the first parallel run):

binpacker calibrate
# after adding new specs, measure only the ones without timing data:
binpacker calibrate --incremental

Then run your suite in parallel:

binpacker run
# or pass arguments through to the test runner:
binpacker run -- --tag ~slow
binpacker run -- --name /UserTest#test_creates/

workers: auto uses the number of available CPU cores. Set BINPACKER_PROFILE=ci or pass --profile ci to select a profile; CI environments (GitHub Actions, GitLab CI, Jenkins) are auto-detected and fall back to the ci profile when present.

• Container/machine-level workers — extend the Worker model beyond single-job processes to distribute Tests across containers or machines.

Mozilla Public License Version 2.0. See LICENSE.