Quickstart

twin needs Node 22 or newer.

npm install -g @crypticsaiyan/twincli

This installs the twin command. To try it without installing, prefix a command with npx @crypticsaiyan/twincli.

Reporter

You have a command that fails on your machine. Nothing is uploaded and no account is needed.

1. In the project where the command fails, run it through twin:

   twin capture -- npm test

   twin runs the command as usual and shows its output.

2. twin prints a summary of what it recorded and asks:

   Write twin-capsule.json? [y]es / [n]o / [v]iew full JSON:

   Press v to read the full JSON first, y to write it, n to stop.

3. Attach twin-capsule.json to the issue. On GitHub, drag the file into the comment box.

Caution

Redaction is pattern based. Read the capsule before posting it publicly. See Privacy and redaction.

Maintainer

You have a capsule from an issue and want to see the failure.

1. Get a Solari API key from console.getsolari.com and export it, or put it in a .env file. twin reads SOLARI_API_KEY from the nearest .env above the working directory that sets it.

   export SOLARI_API_KEY=slr_live_...

2. Replay the capsule. Pass the attachment link from the issue, or a downloaded file:

   twin replay https://github.com/user-attachments/files/<id>/twin-capsule.json
   twin replay twin-capsule.json

   twin starts a clean Linux sandbox, installs the captured Node version, checks out the exact commit, applies the reporter’s uncommitted diff, installs the dependencies, sets the captured environment and runs the command three times.

3. Read the verdict. REPRODUCED means every attempt failed the way it did on the reporter’s machine. The other verdicts are explained in Replay.

4. Go further:

   twin replay twin-capsule.json --keep           # leave the machine running at the failure
   twin shell                                     # open a terminal on it (Ctrl-] detaches)
   twin bisect twin-capsule.json --good mine.json # find the difference that breaks it
   twin verify twin-capsule.json --patch fix.patch
   twin stop                                      # stop anything still running

For bisect, capture a passing run yourself at the same commit with twin capture -- npm test.

Try it on a real issue

The repository contains the capsules for apache/echarts#21538. With a key set, from a clone:

twin replay examples/echarts-21538/new-york.json
twin bisect examples/echarts-21538/new-york.json --good examples/echarts-21538/kolkata.json
twin verify examples/echarts-21538/new-york.json --patch examples/echarts-21538/fix.patch

Each takes about 70 seconds.

Working from source

git clone https://github.com/crypticsaiyan/twin
cd twin
pnpm install
pnpm dev replay examples/echarts-21538/new-york.json   # runs from source, Node 22.18 or newer
pnpm build && node dist/bin.js --help                  # or build first

Next

• Capture: what is recorded and how to share values.
• Issue template: ask for capsules when the issue is filed.
• AI agents: let a coding agent work in the reporter’s environment.