CodeInstances.com

CodeInstances Adds a Self-Hosted Store, Push and Pull by ID, and Bug Reports That Reproduce

Sun, 18 Oct 2026 00:00:00 +0000

CodeInstances v0.5.0 is about getting a run from where it failed to where someone can fix it. A test fails in CI at 3 a.m. The run is kept, but it’s sitting on a build machine that’s gone in an hour. This release adds a small store of your own to keep runs in, push and pull to move them by id, and report, which writes the bug report you paste into the issue.

CodeInstances Groups Failing Runs by Fingerprint So Repeats of One Bug Show as One

Sun, 18 Oct 2026 00:00:00 +0000

CodeInstances v0.4.0 adds the sixth verb, group. Point codeinstances group at a folder of instances and it tells you how many different ways your program failed, how often each one happened, and when it was first and last seen.

The problem is a familiar one. A nightly job fails 40 times in a week. A flaky suite leaves a pile of red runs. Each failure gets its own instance now, which is good, but 40 files isn’t an answer. Usually it’s two or three bugs, repeating. Somebody has to open the files, squint at the errors and sort them into piles, and the piles drift, because the messages carry request ids, timestamps and ports that change every time.

CodeInstances Launches as an Open Source Tool That Keeps Program Runs and Replays Them

Sun, 18 Oct 2026 00:00:00 +0000

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 Now Compares Two Runs and Shows Where the Failing One Went Wrong

Sun, 18 Oct 2026 00:00:00 +0000

CodeInstances v0.2.0 is out, and it adds the third verb. The first release could keep a run and replay it. This one compares two of them: codeinstances diff passing.instance failing.instance.

The usual case goes like this. A job works on Monday and fails on Tuesday, or passes on your laptop and fails in CI. You have both runs as instance files, because you put codeinstances record in front of the command. Now you want to know what was different, and you’d rather not read two logs side by side and guess.

CodeInstances Shrinks a Failing Run to the Answer That Breaks It and Keeps It as a Test

Sun, 18 Oct 2026 00:00:00 +0000

CodeInstances v0.3.0 adds two verbs at once. codeinstances shrink takes a failing run and a passing one and finds which of the failing run’s answers actually cause the failure. codeinstances test replays a folder of instances as regression tests. They belong together: the first finds the bug’s smallest form, the second makes sure it stays fixed.

Here’s the problem shrink goes after. You’ve got a run that fails and one that doesn’t, and diff from the last release shows you how they differ. Often that’s dozens of answers: timestamps, ids, counters, prices that moved. One of them broke the program, and the rest is noise. Reading them one by one is slow, and it’s guesswork.

How a Bug Report Can Arrive as a Runnable CodeInstances File

Sun, 18 Oct 2026 00:00:00 +0000

You maintain a command-line tool that talks to an online service. An issue comes in: “sync breaks against our account”. You don’t have their account. You can’t see their data. You ask for logs, then a bigger log, then a screen share, and after a week of back and forth you still haven’t seen the failure happen.

The reporter could send the failure itself. If they run your tool under CodeInstances, the run is kept as a file with every request your tool made and every answer their account gave back:

How CodeInstances Keeps the Failing Run of a Flaky CI Test

Sun, 18 Oct 2026 00:00:00 +0000

Here’s a situation most teams know. An integration test fails about one run in twenty. It calls an API that usually answers one way and occasionally answers another (a field missing, a list in a different order, a slow page that times out). Somebody hits rerun, it goes green, and the failure is gone. A week later it happens again, and the ticket still says “can’t reproduce”.

The trouble is that the one run worth looking at is the one nobody kept. Logs say the test failed. They don’t hold the answer that made it fail.

How CodeInstances Was Tested Before Its First Release

Sun, 18 Oct 2026 00:00:00 +0000

A tool that claims to replay runs exactly has to be tested on exactly that. So most of the testing for v0.1.0 does the same thing over and over in different ways: record a program against real servers, shut the servers down, replay it, and check the replay came out the same. Then change something and check the replay notices.

Every number in this post comes from the result files in the code repository, in test/results. They were recorded on October 18, 2026, at commit c2a5975, on a Linux machine with an Intel Xeon processor at 2.10GHz and 2 CPUs, with Go 1.24.7. One script, scripts/record-tests.sh, runs everything and writes the files, so anyone can run it again.

How to Develop Against a Metered or Rate Limited API With CodeInstances

Sun, 18 Oct 2026 00:00:00 +0000

Some APIs you can’t call as often as you’d like. A payments sandbox that throttles you after a burst. A maps or weather API billed per request. A partner’s staging server that falls over every afternoon. You’re working on the part of your program that handles the answers (the formatting, the error messages, the retry logic), and each try means another call you’d rather not make.

Record the program once against the real API, and work against the recording for the rest of the day:

How to Replay the AI Agent Run That Did Something Odd Last Night

Sun, 18 Oct 2026 00:00:00 +0000

An agent ran overnight on a batch of tasks. In the morning one result is wrong. It filed a ticket under the wrong customer, or summarised a document it never fetched, or called a tool twice. You run the agent on the same task to see what happened, and it does the job perfectly.

That’s normal for agents. The model’s answers vary from run to run, so the agent picks different tools in a different order and ends up somewhere else. Running it again doesn’t show you last night’s run. It shows you a new one. With an ordinary program, rerunning is how you debug. With an agent, the only copy of the run that went wrong is whatever you kept at the time.

How to Upgrade a Dependency With CodeInstances Replaying Real Runs

Sun, 18 Oct 2026 00:00:00 +0000

You need to bump something underneath your program. A new major version of the HTTP client library, a vendor’s SDK, or the Go toolchain itself. The changelog is long. Your unit tests pass, but they use mocks written two years ago against the old behaviour, so passing doesn’t tell you much. What you’d like to know is simple: does the program still do the same thing on real work?

Real runs answer that. Before the upgrade, record a handful of runs of the current build doing real work, against the real services:

The CodeInstances File Format Is Open JSON With a SHA-256 ID

Sun, 18 Oct 2026 00:00:00 +0000

The file is the product. A tool can be replaced, but a run you kept in a format only one tool reads is a run you’ll lose eventually. So the instance format is open JSON, written down in full in FORMAT.md for anyone who wants to read or write instances with their own tools.

Its name is codeinstances/0, and that string is the first member of every file. A reader that sees a format version it doesn’t know has to refuse the file, and readers ignore members they don’t recognise. A file that holds the same member twice, or a known member spelled in another case, is refused. That’s how the format can grow without breaking files that already exist.

What a Code Instance Is and Why Program Runs Should Be Kept Like Code

Sun, 18 Oct 2026 00:00:00 +0000

If you’ve written object-oriented code, you already know the idea. A class is a blueprint. Each object you make from it is an instance of that class, with its own state. One Order class, thousands of orders.

Your program works the same way. The code is the blueprint, and every time it runs, that run is an instance of it. Same code, different day, different answers from the servers it talks to, different clock, different random numbers. Each run is its own thing.

Why Replay Matters for AI Agents That Take a Different Path Every Run

Sun, 18 Oct 2026 00:00:00 +0000

Most programs are boring in a good way. Give them the same input and they do the same thing. If one fails, you can usually run it again and watch it fail again.

An AI agent isn’t like that. The model’s answer varies from run to run, so the agent picks different tools, calls them in a different order, reads different pages and ends somewhere else. Ask it the same thing three times and you may get three different runs, and only one of them may go wrong. Run it again to see what happened, and you’re watching a different run.

Why the Project Is Called CodeInstances

Sun, 18 Oct 2026 00:00:00 +0000

The name is the idea, in two words. Code is the program you write. An instance is one run of it.

Programmers already use “instance” this way. An object is an instance of its class. A server is an instance of an image. A running process is an instance of a program. In each case there’s one blueprint and many concrete things made from it, each with a life of its own. A run of your code fits right in. It’s made from the code, but it also has things the code doesn’t: the answers it got from the network that day, the time on the clock, the random numbers it drew.

About

Mon, 01 Jan 0001 00:00:00 +0000

CodeInstances keeps runs of programs as instances and replays them. It’s an open source project under the Apache License 2.0, made by SoftDevStudio.com. The code is on GitHub.

The current release is v0.5.0, the fifth one. It’s early. What it does, it does well and it’s tested, and the reference lists plainly what it can’t do yet.

Why the Project Exists

Code gets a lot of care. It sits in version control, it’s reviewed, tagged, released and kept for years. Runs get none. A program runs, talks to a few servers, prints something and exits, and the run is gone. If it failed, you have a log line and a guess.

Contact

Mon, 01 Jan 0001 00:00:00 +0000

The project would like to hear from:

Developers who tried CodeInstances and hit something it didn’t capture or replay the way they expected.
Teams with flaky tests, hard-to-reproduce failures or AI agents whose runs they’d like to keep.
Anyone with a question about the tool, the instance format or the numbers on this site.

Write to info@codeinstances.com.

For a bug, it helps to mention your system, the CodeInstances version (codeinstances version prints it), the language and HTTP client of the program you recorded, and what the replay report said. An instance file that shows the problem is the best bug report of all, once you’ve checked it holds nothing private.

Download

Mon, 01 Jan 0001 00:00:00 +0000

CodeInstances is a single static binary with no dependencies. Pick the archive for your system. These links always fetch the latest release, which is v0.5.0 right now.

System	Archive
Linux, x86-64	codeinstances_linux_amd64.tar.gz
Linux, ARM64	codeinstances_linux_arm64.tar.gz
macOS, Apple silicon	codeinstances_darwin_arm64.tar.gz
macOS, Intel	codeinstances_darwin_amd64.tar.gz
Windows, x86-64	codeinstances_windows_amd64.zip

Each archive holds two programs: codeinstances itself, and codeinstances-demo, the self-checking demo described in how it was tested. The license files come with them.

Check the Download

The release page has a SHA256SUMS file with a checksum for every archive. On Linux or macOS:

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

This takes a couple of minutes. You need the codeinstances binary from the download page and any program that talks to the network. The examples use a Python script, but the language doesn’t matter.

1. Record a Run

Put codeinstances record and -- in front of the command you’d normally type:

codeinstances record -o weather.instance -- python3 fetch_weather.py

The program runs as usual and its output passes through. When it exits, the run is kept in weather.instance: the command, what it printed, how it ended, and every HTTP and HTTPS request it made with the answer it got. record exits with the program’s own exit code, so it drops into scripts and CI without changing anything around it.

Reference

Mon, 01 Jan 0001 00:00:00 +0000

Every command, flag and limit in CodeInstances v0.5.0. For a first run, the quick start is shorter.

Commands

Command	What it does
`codeinstances record [flags] -- command [args...]`	Run the command and keep the run as an instance file
`codeinstances replay [flags] file [-- command [args...]]`	Run the recorded command again, or the one given, with the network replaced by the recording, and compare
`codeinstances diff [flags] a b`	Compare two instances: how they ended, their output, their calls and values, and their speed
`codeinstances shrink [flags] -pass passing failing [-- command]`	Find the fewest of the failing run’s answers that keep the failure, and keep that instance
`codeinstances test [flags] file-or-dir... [-- command]`	Replay instances as regression tests
`codeinstances group [flags] file-or-dir...`	Fingerprint failing runs and group the ones that fail the same way
`codeinstances serve [flags]`	Run a store that keeps instances under their ids
`codeinstances push [-to url] file-or-dir...`	Upload instances to a store
`codeinstances pull [-from url] [-o file] id`	Download an instance by id or unique prefix
`codeinstances report [-url store] file`	Write a Markdown bug report for an instance
`codeinstances show [-json] file`	Describe an instance, or print it whole as JSON
`codeinstances verify file`	Check the file hasn’t been changed since it was recorded
`codeinstances version [-json]`	The version, the format version and the commit it was built from

Exit codes: record exits as the program did. replay exits 0 when the run matched and 1 when it diverged. diff exits 0 when the runs are the same and 1 when they differ. shrink exits 0 when it kept an instance and 1 when the failure couldn’t be narrowed down. test exits 0 when every test passed and 1 when any failed. group, report, push and pull exit 0 when they worked. verify exits 1 for an edited file. Anything else is 2 on a usage or file error.