A deterministic command-line utility designed to clean oversized Codex session logs by replacing heavy base64 image payloads with small placeholders while retaining full conversation history.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install codex-session-image-scrubber
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install codex-session-image-scrubber using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Codex Session Image Scrubber?
The Codex Session Image Scrubber is a technical utility designed to restore performance to bloated AI coding sessions. When developers interact with local AI agents, paste screenshots, or work with heavy visual assets, the local session logs (stored as JSONL files) can quickly balloon in size. This leads to lagging interfaces, slow parsing times, and increased load on the coding agent. By using this utility, developers can safely purge these oversized base64 strings and image payloads.
Integrating tools like this from Openclaw Skills ensures that local developer environments remain lightweight, responsive, and easy to parse, without sacrificing the conversational context, tool call history, or text markers that local AI agents rely on to maintain state.
Codex Session Image Scrubber Use Cases
- A user reports that an active Codex chat or local development thread has become sluggish or heavy.
- Local JSONL session histories contain huge embedded screenshots or base64 image strings that need purging to save disk space.
- Prior turns containing image structures are bloating the current workspace, and the user wants to strip visual data while maintaining dialogue text.
- Pre-processing session logs for backup or sharing, where removing high-density image files is necessary for privacy or bandwidth reasons.
How Codex Session Image Scrubber Works
- Target Identification: The utility confirms the target thread or session file. It checks the provided thread ID or uses a search tool (
rg) to locate matching phrases inside~/.codex/sessionsor the session index file. - Dry-Run Analysis: The script processes the session file in a non-destructive dry-run, identifying targets for optimization without writing any changes to disk.
- Safe Backup Creation: Before writing any optimizations, the script creates a copy of the target session in a designated backup folder (defaults to
~/.codex/session_backups). - Payload Purging: The tool targets base64 strings and image markers that exceed the byte threshold, swapping them out for lightweight placeholders while retaining conversational content.
- Post-Sanitization Validation: After the write phase is complete, the utility checks that the file parses properly (verifying zero parse errors) and runs a grep verification to confirm no large image patterns remain.
Codex Session Image Scrubber Setup
To leverage this optimization process within Openclaw Skills, invoke the Node.js script directly from your terminal.
Dry-Run Verification
Run the scrubber in dry-run mode using a specific Thread ID to preview size reductions:
node ~/.codex/skills/codex-session-image-scrubber/scripts/scrub-codex-session-images.mjs --thread-id <thread-id>
Clean and Overwrite Log File
Apply the scrub process and update the active session logs using the --write flag:
node ~/.codex/skills/codex-session-image-scrubber/scripts/scrub-codex-session-images.mjs --thread-id <thread-id> --write
Scrub a Specific JSONL File Path
You can also target files directly outside the default sessions index:
node ~/.codex/skills/codex-session-image-scrubber/scripts/scrub-codex-session-images.mjs --file /path/to/rollout.jsonl --write
Codex Session Image Scrubber Data Schema & Taxonomy
Configuration and Parameter Specifications
The script operates based on the following configurations and paths:
| Option | Description | Default Path / Value |
|---|---|---|
--thread-id <id> |
The specific Codex thread to locate and scrub | N/A |
--file <path> |
Direct file path to a target JSONL session | N/A |
--write |
Executes the overwrite process | Dry-run only (Default) |
--backup-dir <path> |
Backup path for target files prior to cleanup | ~/.codex/session_backups |
--sessions-dir <path> |
Location of target active session directories | ~/.codex/sessions |
--min-bytes <n> |
Minimum size threshold for targeted image blocks | 100000 (100 KB) |
Validation Tests
To ensure target payloads have been purged successfully, run:
rg -n "data:image|iVBORw0KGgo|/9j/4AAQ|UklGR" <sanitized-file-path>
An exit code of 1 indicates no matching binary payloads remain, confirming the file is fully optimized.
Codex Session Image Scrubber Advanced Features
- Custom Byte Thresholding: Adjust
--min-bytesdynamically to focus on exceptionally large screenshots while preserving smaller inline assets. - Regex Validation Hooks: Automatic checking for popular base64 image headers (e.g., JPEG, PNG, WebP) to prevent false-positive text deletions.
- Isolated Backups: Built-in automatic backup routing ensures you never lose conversational data if a session file gets corrupted during scrubbing.
- Non-Destructive Markers: Keeps standard textual markers like
<image>and</image>intact, preserving structural readability for AI models.
SKILL.md
Loading
Related Openclaw Skills
The Psychology of Selling
An AI-powered sales coaching agent that brings Brian Tracy's iconic sales methodology directly to your development and communication workflows.
Dataset Search
An automated discovery and acquisition utility for finding datasets, public data lakes, and open-data portals across multiple global repositories.
Doctor Call
An automated diagnostic and repair tool designed to maintain high availability for the OpenClaw gateway using systemd auto-restarts.
Google Messages Browser Skill
A browser automation skill that enables AI agents to send, receive, and monitor SMS/RCS messages directly through Google Messages for Web.
Timeplus Design System
A comprehensive design system skill for AI coding agents to generate pixel-perfect, Timeplus Console-aligned web interfaces using standard design tokens, CSS, Tailwind, and React.
The Prize: Oil History, Geopolitics & Economics
An interactive knowledge skill based on Daniel Yergin's epic history of oil, detailing how petroleum shaped wars, global economies, and modern geopolitics.
Featured*
