Posts on 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 Forks a Run at Any Step, to Run On Live or Try a What-If Answer

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

CodeInstances v0.6.0 adds fork. Replay runs a program against the whole recording. Fork runs it against the recording up to a step you pick, then lets it carry on from there. You get the past exactly as it happened, and a new future.

Two uses pull this in. The first is picking up where a run went wrong. An agent ran for twenty minutes, called a dozen APIs, and on call nine it got an answer that sent it the wrong way. You don’t want to spend another twenty minutes and another dozen calls getting back to call nine. codeinstances fork -at 9 run.instance answers calls one to eight from the recording in a moment, then sends call nine for real, against today’s servers.

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.

CodeInstances Signs Runs, So You Can Check Who Kept One and That Nothing Changed

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

CodeInstances v0.7.0 adds signing. Every instance already carried an id, the SHA-256 of its contents, so verify could tell you a file had been edited. What it couldn’t tell you is who made the file in the first place. Anyone can change a run and write a fresh id. Now a run can carry a signature, and verify -trust checks it against keys you’ve decided to trust.

That matters when a run is evidence. A CI job says the tests passed, an AI agent says what it did and what came back, a bug report says this is what happened. With a signed instance the person reading it doesn’t have to take the file’s word for it. They check the key.

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.