Guide · elf-import

Your agent sessions are files. Take them with you.

Claude Code and Codex keep your conversation history as plain files on your own Mac — and Claude Code deletes transcripts older than 30 days by default. elf-import finds those files, reads them without touching them, and exports everything into one unified, redacted format any tool can read. One Python file, standard library only: no install, no network, no account.

5 min read · Updated 2026-10-19

TL;DR. Download the zip, run three commands, and you get a unified export of every Claude Code and Codex session on your Mac, plus a one-page HTML report organized by project. The export has two tiers: a full local tier that stays on your machine, and a redacted share tier that is the only one meant to travel.

What it does

elf-import scans the two session stores that already exist on your Mac:

  • Claude Code (terminal and the Claude Mac app’s Code tab share one store): ~/.claude/projects/**/*.jsonl, including subagent transcripts.
  • Codex (terminal, Mac app, and editor extension share one store): ~/.codex/sessions/**/rollout-*.jsonl, ~/.codex/archived_sessions/, and ~/.codex-openai/ when present.

The export is one .jsonl file per session in the unified elf.session.v1 format, plus an index.json describing the whole corpus — per session: project, times, message and tool counts, first prompt, a state guess (open / done / errored), project cluster, redaction count, and the file’s SHA-256. A missing store is reported as NOT FOUND, never as “0 sessions, success”.

Download

Download elf-import (zip, 28 KB)

The zip contains the tool (elf-import.py), the report renderer (elf-import-report.py), a README, a paste-prompt for handing the whole run to your own agent, and the clean-room proof notes. SHA-256 of the zip: ad1407a8a90a950ce76937e6a122e09694f88c782a380b1f89b45c776c5d83b1

Quickstart

Terminal
unzip elf-import-package.zip -d elf-import
cd elf-import
python3 elf-import.py scan     # see what you have (read-only, writes nothing)
python3 elf-import.py export   # write the unified export to ~/Desktop/elf-export
python3 elf-import.py verify ~/Desktop/elf-export
python3 elf-import-report.py ~/Desktop/elf-export   # writes REPORT.html

export writes ~/Desktop/elf-export/ with two folders: local/ (full transcripts — stays on your machine) and share/ (redacted, tool results truncated, reasoning dropped, home paths replaced with ~). By default it covers the last 30 days plus any session that looks unfinished; add --since all for everything. Exports are safe to repeat.

Or hand it to your agent

Don’t want to run commands yourself? Download the zip, then paste this into your own agent — Claude Code, Codex, terminal or app. The zip also contains a longer version of this prompt (PASTE-PROMPT.md) with a debug protocol and a receipts checklist.

Paste to your agent
Run elf-import for me, end to end:
1. Unzip the package I downloaded from this page and save elf-import.py and
   elf-import-report.py exactly as received, byte for byte.
2. Run: python3 elf-import.py scan — and show me the summary (sessions per
   app, per project, date span).
3. Run: python3 elf-import.py export — then:
   python3 elf-import.py verify ~/Desktop/elf-export (it must end "verify OK").
4. Run: python3 elf-import-report.py ~/Desktop/elf-export — and walk me
   through REPORT.html: totals, projects, open vs done sessions, date span.
Rules: never modify or delete anything under ~/.claude or ~/.codex, never
open auth or config files, and send nothing anywhere — I decide what leaves
this Mac, after I have seen the report.

Privacy, honestly

  • Local-only. The tool makes no network calls and reads only the session stores above. It never touches auth files, config files, or app databases.
  • Read-only. Your original sessions are never modified.
  • Redaction, both tiers. Before anything is written, a pattern pass replaces secret-shaped strings — API keys, JWTs, bearer tokens, PEM private keys, KEY= assignments — with markers like «redacted:sk-shape», and counts them per session. verify re-scans the finished export and fails if any secret-shaped string remains.
  • Reasoning stays home. Thinking is kept in the local tier and dropped from the share tier — it is the most private text in the corpus and the least needed to continue work.

The honest limit: pattern redaction cannot catch a secret pasted mid-sentence in ordinary prose, or in a novel shape. Read the share tier before sending it anywhere — treat it as best-effort, not a guarantee.

What v1 does not do

  • Consumer chat apps. Plain claude.ai / ChatGPT conversations have no local transcript store — they live in the cloud. Nothing to import, and we won’t pretend otherwise.
  • Resuming work is a separate, later step that consumes an export. Export itself is inert data — nothing here starts, resumes, or sends anything.
  • Windows/Linux path layouts are the same shape but untested in v1.

Proven, not promised: the package was exercised end to end in a clean room (fresh home directory, scrubbed environment) and in a full first-user simulation that followed the paste-prompt literally; the fixture suite covers synthetic Claude Code and Codex stores, including crashed-run shells and auto-generated review rollouts. The proof notes ship inside the zip (PROOF.md, PACKAGE-PROOF.md). Download: https://elf.dance/guides/elf-import/elf-import-package.zip

Your history, in a format that outlives the app.

One file, no dependencies, nothing leaves your Mac unless you send it.

Download elf-import