DiffTrail

Reconstruct Git history—even if you never committed it.

Recover lost states and turn them into an evidence-backed Git timeline.

PyPI Python 3.11+ MIT license

Quick start · How it works · Commands · Safety


uvx difftrail init

Git only remembers what you commit. Useful intermediate states often survive elsewhere, such as in patches, tool calls, test outputs, uncommitted diffs, later file versions, local session history, etc.

DiffTrail retrospectively collects that evidence, replays every change it can verify, and uses a coding agent model 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, and the Codex CLI.

How it works
Collect Finds Git history, uncommitted diffs, patches, file versions, tool calls, test output, supplied artifacts, and matching Codex sessions.
Reconstruct Replays byte-exact changes first, then lets Codex resolve only the remaining gaps.
Preserve Writes reconstructed milestones to a separate branch and worktree with provenance attached as Git notes.

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

Command Purpose
difftrail init Check Python, Git, Codex, local history, and repository readiness.
difftrail reconstruct [TARGET] Scan and reconstruct the full history or one described state.
difftrail reconstruct --resume Continue the latest reconstruction without rescanning or resetting completed work.
difftrail scan [REPO] Collect and normalize evidence without starting reconstruction.
difftrail evidence RUN EVENT Inspect one normalized evidence record.
difftrail explain COMMIT Explain the evidence and classification behind a reconstructed commit.
difftrail publish RUN Push the reconstructed branch and provenance notes to the existing remote.

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 doesn't switch or modify the original worktree or branch, stores no model credentials, and never arbitrarily 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 are located under .git/difftrail/ and published commits through refs/notes/difftrail.

License

MIT

Project links

Data verified by PyPI on Aug 14, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for rishaandesai from gravatar.com rishaandesai

Credits

Author: Rishaan Desai

GitHub Statistics

Data verified by PyPI on Aug 14, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Tags

ai codex git reconstruction developer-tools

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

difftrail-0.1.1.tar.gz (34.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

difftrail-0.1.1-py3-none-any.whl (29.8 kB view details)

Uploaded Python 3

File details

Details for the file difftrail-0.1.1.tar.gz.

File metadata

  • Download URL: difftrail-0.1.1.tar.gz
  • Upload date:
  • Size: 34.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for difftrail-0.1.1.tar.gz
Algorithm Hash digest
SHA256 bb5f245ef193f207002492ce1c9d81721abeb1c978e076b30417984ea7663d0e
MD5 3cbeb9c9a32d538caf4ee7bc88363188
BLAKE2b-256 89f8984b19942fb55bd0c44bf271bada3d9ae114b6e41feae16b193dbc91a2e2

See more details on using hashes here.

Provenance

The following attestation bundles were made for difftrail-0.1.1.tar.gz:

Publisher: python-publish.yml on rishaandesai/difftrail

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file difftrail-0.1.1-py3-none-any.whl.

File metadata

  • Download URL: difftrail-0.1.1-py3-none-any.whl
  • Upload date:
  • Size: 29.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for difftrail-0.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 03cb1f6bba71133982b293e22ff24454d517bd0d301ddaa01473909d296e8b49
MD5 315dfae8d7e900086eae5f1802728b03
BLAKE2b-256 7266db73f6110c9329eadb809f1f40f0439ca94401e82cff36f8e9a7f15fbeaf

See more details on using hashes here.

Provenance

The following attestation bundles were made for difftrail-0.1.1-py3-none-any.whl:

Publisher: python-publish.yml on rishaandesai/difftrail

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page