Git only remembers what you commit. AI coding agents often leave useful intermediate states scattered across patches, tool calls, test output, uncommitted diffs, later file versions, and local session history.

DiffTrail retrospectively collects that evidence, replays every change it can verify, and uses Codex to reconstruct the missing pieces in a separate branch with clearly marked commits that you can revert or refer to.

Quick start

Run without installing

From the Git repository you want to reconstruct:

uvx difftrail init
uvx difftrail reconstruct

Recover one particular state instead:

uvx difftrail reconstruct "before the auth refactor"

If reconstruction is interrupted:

uvx difftrail reconstruct --resume

Install the difftrail command

uv tool install difftrail
difftrail init
difftrail reconstruct

Upgrade later with uv tool upgrade difftrail. DiffTrail requires Python 3.11+, Git, the Codex CLI, and existing Codex authentication.

Until the first PyPI release is published, run the GitHub version directly:

uvx --from git+https://github.com/rishaandesai/difftrail.git difftrail init

How it works

Running difftrail reconstruct with no target reconstructs the complete recoverable history. DiffTrail shows a persistent task progress bar whose total grows when Codex discovers more work. Commands appear as [codex] $ ...; detailed model events and command output stay in the run log.

Commands

The lower-level start, replay, commit, and verify commands support the reconstruction workflow and advanced manual use. Run difftrail COMMAND --help for every option.

Safety

DiffTrail is local-first. It never switches or modifies the original worktree, never publishes automatically, stores no model credentials, and never executes a historical command merely because it appeared in agent history.

Every reconstructed file is classified as:

• exact — original bytes were preserved;
• reconstructed — the bytes follow from verified evidence;
• inferred — model judgment affected the result.

Full manifests remain under .git/difftrail/ and travel with published commits through refs/notes/difftrail.

License

MIT