Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

Sessionfold

Sessionfold is a local-first disk safety tool for Codex histories. It finds oversized JSONL sessions and creates lossless, content-addressed archives in which identical inline images are stored once across every archived session.

The current alpha supports Codex only. It does not support Claude Code. Claude Code normally stores image blocks in a different JSON representation, which Sessionfold does not currently deduplicate.

It does not upload telemetry or session data, display conversation content, or modify an active transcript. Scanning is read-only. Source removal is optional and occurs only after a full byte-exact reconstruction has been verified.

Important: this is cold storage

Sessionfold is not transparent compression inside Codex.

  • archive leaves the original JSONL untouched, so the chat remains available in Codex. This creates the verified cold-storage copy but does not reclaim the original file's bytes.
  • reclaim removes that original JSONL after verification. This recovers disk space, but the chat may disappear from Codex and may not be resumable there.
  • restore recreates the original JSONL byte for byte. Sessionfold verifies the restored file, but automatic reintegration into the Codex sidebar has not yet been validated.

If every chat must remain immediately usable in Codex, use scan, archive, and verify, then stop before reclaim.

Why I built it

I bought a 1 TB Mac, and about 20 days later it had 80 MB of free space left. I assumed the healthcare datasets I had been working with were responsible. After some debugging, my agent reported:

The main culprit is not the healthcare data: ~/.codex/sessions is about 566 GiB, mostly individual rollout JSONL files of roughly 5 to 6 GiB each from September 3 to 5.

My reaction was basically, "what the shit?"

Those histories contained screenshots copied into JSONL as base64. Compaction and related sessions had repeated many of the same images thousands of times. I wanted the disk space back without blindly deleting my work or trusting a lossy cleanup script. That became Sessionfold.

At 80 MB free, the machine was already too full to build a safe archive on the same disk. I first freed some breathing room. If your internal drive is that close to full, use --store to put the archive on an external volume.

Why it exists

Screenshot-heavy agent sessions can embed base64 images directly in JSONL. Compaction and forks may repeat the same image thousands of times. Ordinary gzip cannot efficiently deduplicate copies that are far apart or in different files.

Sessionfold provides five operations:

  • scan inventories histories; --deep hashes inline images and estimates duplicate bytes without decoding or displaying them.
  • archive writes non-image transcript bytes to a compressed thin stream and stores images in a global SHA-256 content-addressed store.
  • verify reconstructs and hashes the full logical transcript without writing a source-size temporary file.
  • reclaim verifies the archive and original again, then removes only the exact source named in the manifest after explicit confirmation.
  • restore recreates the original JSONL byte-for-byte at a new path.

Install the alpha

Requires Python 3.10 or newer and has no runtime Python dependencies.

python3 -m pip install --pre sessionfold
sessionfold scan

The --pre flag is required while Sessionfold is published as an alpha.

To install from a checkout:

python3 -m pip install .
./bin/sessionfold scan

Usage

sessionfold scan
sessionfold scan --deep --top 20
sessionfold archive /path/to/completed.jsonl
sessionfold list
sessionfold verify ~/.sessionfold/archives/ARCHIVE/manifest.json
sessionfold reclaim ~/.sessionfold/archives/ARCHIVE/manifest.json --yes
sessionfold restore ~/.sessionfold/archives/ARCHIVE/manifest.json --output ./restored.jsonl

The recommended workflow separates review from removal:

sessionfold archive /path/to/completed.jsonl
sessionfold verify ~/.sessionfold/archives/ARCHIVE/manifest.json
sessionfold reclaim ~/.sessionfold/archives/ARCHIVE/manifest.json --yes

For a one-command archive and removal, after reviewing the risks below:

sessionfold archive /path/to/completed.jsonl --remove-source

Both removal paths perform the same second archive reconstruction and source hash check. They refuse recent files, files open by another process, changed sources, and platforms where open-file detection is unavailable. Removing a vendor transcript may hide that session from the product UI until it is restored.

Defaults and scope

  • Codex discovery: ${CODEX_HOME:-~/.codex}/sessions
  • Archive store: ~/.sessionfold
  • Inline image candidates: 4 KiB to 64 MiB each

Creating an archive requires additional disk space before any source can be removed. When the source disk is critically full, choose an external store:

sessionfold archive /path/to/completed.jsonl --store /Volumes/External/sessionfold

The initial archive format targets JSONL transcripts containing quoted data:image/*;base64,... values. Unknown or small data URIs remain inline. Transcript formats are vendor-owned and unstable, so compatibility must be tested as they evolve. Sessionfold is archival storage and Codex does not read its archive format directly. Codex is the only supported target in this alpha. Do not use Sessionfold to reclaim Claude Code histories.

If an archive store is relocated, pass its new root with --store to verify or restore.

Limits worth knowing

  • Sessionfold cold-archives completed histories. It does not rewrite or shrink the live history that Codex is currently using.
  • The first archive needs enough temporary headroom for its thin stream and any image blobs not already in the store. Use an external --store when the internal disk is critically full.
  • Archive data is not encrypted. Protect it like the original transcript.
  • Source removal depends on reliable open-file detection. It fails closed when that check is unavailable. In this alpha, removal is not supported by default on Windows, although scan, archive, verify, and restore run in Windows CI.
  • The safety checks assume an ordinary single-user machine, not a malicious local process deliberately racing filesystem operations.
  • Codex owns its transcript format and can change it. Verify compatibility on synthetic data after major Codex updates before reclaiming original files.

Safety and privacy

  • no network access or telemetry;
  • no prompt, image, or tool-output display;
  • no implicit deletion or whole-root mutation;
  • no edits to vendor databases or active transcripts;
  • atomic archive directories and immutable, content-addressed blobs;
  • source-size and SHA-256 validation of every logical reconstruction;
  • blob size and SHA-256 checks before a restore is accepted;
  • existing restore targets are never overwritten.

See SECURITY.md and PRIVACY.md.

Optional Codex plugin

The repository includes a Codex plugin manifest and a safety-focused skill.

Development

python3 -m unittest discover -s tests -v
python3 -m py_compile sessionfold/cli.py
python3 -m build

The feasibility measurements in experiments/ are single-machine benchmarks, not promises about every corpus.

See the archive format, validation record, and competitive boundary for the current contract.

Metadata

Release files for sessionfold 0.1.0a4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sessionfold 0.1.0a4
File Size Uploaded Provenance Actions
sessionfold-0.1.0a4.tar.gz 27.1 kB With provenance Details for sessionfold-0.1.0a4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sessionfold 0.1.0a4
File Interpreter ABI Platform Actions
sessionfold-0.1.0a4-py3-none-any.whl Python 3 none any Details for sessionfold-0.1.0a4-py3-none-any.whl

Total release size: 41.9 kB

Release files / sessionfold-0.1.0a4.tar.gz

Download URL sessionfold-0.1.0a4.tar.gz
Size 27.1 kB
Tags Source
SHA-256 checksum
How to use checksums
70c6985a743e6bca0352ef4167d2b16ab855c1d693b0d4a75bf8e1500febc8a0
BLAKE2b-256 checksum
How to use checksums
ee7792f9f5192fc1850caeee22c8c29e43acd3e9929a96586e5901e6351e27d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.

Transparency log

Release files / sessionfold-0.1.0a4-py3-none-any.whl

Download URL sessionfold-0.1.0a4-py3-none-any.whl
Size 14.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4af0bf705e4330910135bf2fe4da54ad6619b6e12bf4dc05b3781467ee90ca57
BLAKE2b-256 checksum
How to use checksums
be999c90b92c91eb35798d786d7a8fd00c662190e7dd804aea0c80c7b2093fe9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.

Transparency log

Security for sessionfold 0.1.0a4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sessionfold-0.1.0a4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page