About this skill

Problem

Codex session logs can grow large when users paste screenshots, image attachments, or long Base64 payloads. This makes threads heavier and can slow down searching, loading, or review. The skill targets these JSONL session files, replacing oversized image payloads with small placeholders while preserving the conversation, tool calls, and surrounding text.

How It Works

It starts by confirming the target thread, preferring a thread id when available. If the user only provides keywords, it searches ~/.codex/sessions and ~/.codex/session_index.jsonl. It then performs a dry run of scripts/scrub-codex-session-images.mjs to inspect the replacement scope. Once the output looks correct, --write rewrites the file. The script creates a backup, defaulting to ~/.codex/session_backups, and --backup-dir can override the location. After writing, it verifies the file size drop, confirms the JSONL still parses, and checks that image payloads are no longer present.

Boundaries

It only targets image payloads, not ordinary text that merely mentions images. Small structural markers in the conversation are preserved when practical. If multiple files match the same thread id, the process should stop and require an explicit choice to avoid editing the wrong session. This skill is for cleaning Codex session history, not for session management, permissioning, or general log analysis.

Screenshots

Use Cases

Diagnose a heavy Codex thread caused by pasted screenshots, locate the target JSONL, and dry-run image cleanup.
Before sharing a Codex thread, replace Base64 image payloads in the session JSONL while preserving tool calls and text.
Clean a specific thread under ~/.codex/sessions, create a backup first, and verify the JSONL still parses.
When multiple files match one thread id, avoid guessing and only scrub the explicitly selected image payloads.

Best For

Engineers maintaining Codex session history who need to safely remove Base64 screenshots from thread JSONL.
SREs inspecting agent run logs who need to locate and rewrite a selected session file while preserving tool calls.
Developers who paste many screenshots into Codex and need a lighter thread without breaking the conversation.
DevTools maintainers who need image payloads replaced with placeholders, backups, and parse validation.