Codex Session Image Scrubber

Purpose

Clean oversized Codex session logs by replacing embedded image/base64 payloads with small placeholders while keeping the surrounding conversation, tool calls, and text intact.

Use this when the user says a Codex chat/thread is heavy, slow, bloated, or contains pasted screenshots/images/base64 they want removed from history.

Workflow

1. Confirm the target thread/session.
• Prefer a thread id if the user provides one.
• If they provide a remembered phrase, locate the session with rg -l "" ~/.codex/sessions ~/.codex/session_index.jsonl.
• Do not edit the active file until you know which JSONL is the target.

1. Dry-run the scrubber.

```bash

node ~/.codex/skills/codex-session-image-scrubber/scripts/scrub-codex-session-images.mjs --thread-id

```

Or, with an exact file:

```bash

node ~/.codex/skills/codex-session-image-scrubber/scripts/scrub-codex-session-images.mjs --file /path/to/rollout.jsonl

```

1. If the dry-run looks right, write the cleaned file.

```bash

node ~/.codex/skills/codex-session-image-scrubber/scripts/scrub-codex-session-images.mjs --thread-id --write

```

1. Validate after writing.
• Confirm size dropped with ls -lh .
• Confirm the JSONL still parses; the script reports parseErrors: 0.
• Check obvious image payloads are gone:

```bash

rg -n "data:image|iVBORw0KGgo|/9j/4AAQ|UklGR"

```

Exit code 1 with no output is the desired result.

1. Tell the user the before/after size, backup path, and whether validation passed. Suggest reopening the thread so the app reloads the lighter file.

Safety Rules

• Only remove image payloads, not text that mentions images.
• Keep or text markers if present; they are small and can preserve conversation structure.
• Always keep a backup outside ~/.codex/sessions; the script defaults to ~/.codex/session_backups.
• If multiple session files match a thread id, stop and pick explicitly instead of guessing.
• If the user wants the backup removed later, ask for confirmation before deleting it.

Script

The deterministic scrubber is at scripts/scrub-codex-session-images.mjs.

Useful options:

• --thread-id : find a rollout JSONL under ~/.codex/sessions.
• --file : scrub a specific JSONL.
• --write: perform the rewrite; without this the script is dry-run only.
• --backup-dir : override the backup directory.
• --sessions-dir : override the Codex sessions root.
• --min-bytes : threshold for suspicious image fields; defaults to 100000.