Cairn

Cairn records experiments run by coding agents.

Agents often change code, rerun commands, and overwrite outputs. Cairn keeps a record of which code, inputs, and command produced each result.

Each run records the Git commit, command, input hashes, status, duration, and changed outputs. Failed runs and partial outputs are recorded too.

uv tool install .

Git and Git LFS must already be installed. Experiment repositories use:

data/
├── inputs/     # committed through Git LFS
└── outputs/    # ignored by Git

Configure Git LFS in .gitattributes:

data/inputs/** filter=lfs diff=lfs merge=lfs -text

Ignore outputs in .gitignore:

/data/outputs/

Commit the code and inputs before running an experiment.

cairn run -- python scripts/analyze.py

Everything after -- is the experiment command. Cairn records files under data/inputs/ and archives new or changed files under data/outputs/. The command ends with a clear success, failure, or invalid-run banner.

Run history is stored in ~/.cairn, a separate local Git repository. runs.tsv contains one row per run. data/<run-id>.zip contains the JSON manifest and changed outputs. Cairn commits locally and does not push. Set CAIRN_HOME to use another location.

• The experiment repository must be clean.
• Inputs must be committed through Git LFS and available locally.
• Outputs must be ignored and untracked.
• A successful command that changes no outputs is marked invalid.
• Only one Cairn command may run in an experiment repository at a time.

Cairn does not capture the runtime environment or external services. Record those separately when they affect reproduction.