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.
archiveleaves 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.reclaimremoves that original JSONL after verification. This recovers disk space, but the chat may disappear from Codex and may not be resumable there.restorerecreates 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/sessionsis 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:
scaninventories histories;--deephashes inline images and estimates duplicate bytes without decoding or displaying them.archivewrites non-image transcript bytes to a compressed thin stream and stores images in a global SHA-256 content-addressed store.verifyreconstructs and hashes the full logical transcript without writing a source-size temporary file.reclaimverifies the archive and original again, then removes only the exact source named in the manifest after explicit confirmation.restorerecreates 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
--storewhen 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.