CodeInstances Launches as an Open Source Tool That Keeps Program Runs and Replays Them
CodeInstances v0.1.0 is out. It’s a small command-line tool that keeps a run of any program as a file and replays it later, with the network replaced by what was recorded. It’s open source under the Apache License 2.0 and comes as a single static binary for Linux, macOS and Windows.
The problem it goes after is an old one. Code is kept with great care, in version control, reviewed and tagged. Runs are thrown away. A test fails in CI, someone hits rerun, it passes, and whatever went wrong is gone along with the evidence. An API answers something strange once and never again. A job breaks on Tuesday, and by Wednesday the data it read has moved on.
CodeInstances keeps the run. You put codeinstances record -- in front of a command, and the program runs as usual behind a local proxy. When it exits you have an instance file holding the command, what it printed, how it ended and every HTTP and HTTPS exchange it made, request and answer both. Later, codeinstances replay runs the program again and answers every request from the file. It never opens a connection.
What You Can Do With It Today
Replay works with the network off, the API down or the data on the server changed. At the end it says “replay matched”, or it lists exactly what was different: a request the recording doesn’t have, a recorded request that was never made, a different line of output, a different exit code. It exits 0 or 1, so CI can act on it.
The most useful trick is replaying a different build against the same file. You record the failing run, fix the bug, and run codeinstances replay failing.instance -- ./fixed-build. The fixed program sees exactly the answers the broken one saw. If it now behaves, the fix works on the case that actually broke, and you didn’t have to rebuild the conditions by hand.
Go programs get one more thing. The clock and random numbers can’t be seen from outside a program, so a small hook package records them and hands the same values back on replay. Outside CodeInstances it’s just the real clock and crypto/rand.
The file itself is plain JSON in an open format, documented in FORMAT.md. Each one carries a SHA-256 id over its contents, and codeinstances verify catches any edit.
How Much Was Tested
59 Go tests pass, and the race detector finds nothing. A self-checking demo records a program making 23 calls over HTTPS and HTTP to two servers whose answers change every time, stops the servers, and replays the run 10 times. All 10 matched. The recording took 46 ms, and each replay took between 26 and 45 ms, on a 2-CPU Linux machine. The release binaries are smoke-tested on Linux, macOS and Windows before anything is published. How it was tested has the details.
What It Doesn’t Do Yet
It’s v0.1.0, and it’s honest about it. Only HTTP is recorded, so WebSocket and raw TCP aren’t. Bodies are buffered whole, so a streamed response arrives all at once on replay. Clock and random capture is Go only for now. The full list is on the reference page.
Where It Goes
Keep and replay are the first two verbs. The plan adds one at a time: compare two runs, shrink a failing run to the smallest one that still fails, turn real runs into regression tests, group repeated failures, share an instance like a link, fork a run at a step, and sign instances as proof of what ran. The explainer says why those belong together.
Download it, try the quick start, and tell us what it missed.