Skip to content
twin

Introduction

twin reproduces a bug in the environment where it was reported. The reporter records the environment a command failed in. A maintainer, or a coding agent, rebuilds it on a clean Solari sandbox, finds the difference that breaks it, and checks a fix there.

The problem

Section titled “The problem”

Most “works on my machine” bugs are not in the code. The commit is the same. What differs is a runtime version, a dependency that resolved differently, an environment variable, or the time zone. The maintainer gets, at best, a pasted list of versions that nobody can run, and the issue stays at “cannot reproduce”.

What twin does

Section titled “What twin does”
  1. The reporter runs twin capture -- <command>. twin records the environment with secrets removed into a small JSON file, the capsule.
  2. The maintainer runs twin replay on the capsule. twin starts a clean Linux sandbox, rebuilds the environment and runs the command three times.
  3. twin bisect compares the failing capsule with one from a passing environment and reports the smallest set of differences that turns pass into fail.
  4. twin verify applies a candidate fix in the reporter’s environment, so it is checked before anything is pushed.

The reporter needs no account and uploads nothing. Only the side that replays needs a Solari key.

Who runs what

Section titled “Who runs what”
Step Who Command Solari key
Record the failing environment reporter twin capture -- npm test no
Summarize or compare capsules anyone twin inspect a.json, twin diff a.json b.json no
Rebuild it and rerun maintainer twin replay twin-capsule.json yes
Find the difference that breaks it maintainer twin bisect bad.json --good good.json yes
Check a fix maintainer twin verify bad.json --patch fix.patch yes
Open a shell on the failure, or share one maintainer twin replay … --keep, then twin shell --web yes
Let a coding agent work on it agent twin mcp yes
Check a fix pull request CI crypticsaiyan/twin@main yes

Real runs

Section titled “Real runs”

The case studies are recorded on Solari with the capsules and transcripts in the repository:

  • apache/echarts#21538: a test that fails only in time zones with daylight saving time. Replay, bisect and verify each take about 70 seconds.
  • node-lru-cache#397: a fresh install that resolved a broken package release buried under jsdom. Bisect finds it among 32 differences.

What it is for

Section titled “What it is for”

twin is for environmental causes: a version, a variable, a time zone, a resolved dependency, uncommitted changes. It does not find logic bugs or reproduce network and data problems. Replay runs on Linux.

Where to go next

Section titled “Where to go next”

How it works explains the capsule, the replay plan and the verdicts.