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. By default, scans and archive listings show the human-readable task names from Codex's local index. Use --no-titles if you do not want those names printed.

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 archive /path/to/completed.jsonl --title "Storage archive"
sessionfold list
sessionfold list --search "game-based"
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

Sessionfold records the Codex task name in new archives when it is available. It can also enrich older archive listings from Codex's local index. After sessionfold list, verify, reclaim, and restore accept either a manifest path, an archive ID, or an exact unique title:

sessionfold verify "Plan storage cleanup"
sessionfold restore ARCHIVE_ID --output ./restored.jsonl
sessionfold label ARCHIVE_ID --title "Storage archive updated"

Title lookup is best-effort and read-only. Codex does not document its local index as a public interface, so Sessionfold falls back to archive IDs and paths if that schema changes. You can supply archive --title or label an existing archive yourself. Sessionfold never derives a title by reading conversation bodies.

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
  • Codex task names: read-only, best-effort lookup in the local Codex state index
  • 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.0a5

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.0a5
File Size Uploaded Provenance Actions
sessionfold-0.1.0a5.tar.gz 31.1 kB With provenance Details for sessionfold-0.1.0a5.tar.gz

Built distribution (wheel)

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

Total release size: 48.1 kB

Release files / sessionfold-0.1.0a5.tar.gz

Download URL sessionfold-0.1.0a5.tar.gz
Size 31.1 kB
Tags Source
SHA-256 checksum
How to use checksums
e8eb1ffae3f0aa4b823e3d5e376582e9baf96c2205f601288f8056e34e76cdae
BLAKE2b-256 checksum
How to use checksums
0f48c7608798389631f798c9b9cd647c2c7823d0c860debb97f10396f364833c
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.0a5-py3-none-any.whl

Download URL sessionfold-0.1.0a5-py3-none-any.whl
Size 17.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
82b2fc7190a3325c2576c2cccdba087fb22f64d5edac0f4c9b3f87105de55505
BLAKE2b-256 checksum
How to use checksums
397f5f1123d152b5c0cf5f100158c6a8008df163b5ccbc517805f57a21099e36
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.0a5

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.0a5.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