kiro-fix-session-images

Repair Kiro CLI sessions that stopped working with this error:

At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels

A screenshot larger than 2000px (usually a Retina capture) gets stored in the session history, so every later request that replays it fails. This tool scans each session's messages.jsonl, downscales every embedded image above the limit to 1900px on its longest side, and rewrites the file in place. The original is kept next to it as messages.jsonl.bak.

Warning: Close the session in Kiro before running, then resume it.

Install

With uv (recommended):

uv tool install kiro-fix-session-images

Or run it once without installing:

uvx kiro-fix-session-images --all --dry-run

Or with pip:

pip install kiro-fix-session-images

Usage

# Fix one session
kiro-fix-session-images sess_<id>

# The sess_ prefix is added automatically if you omit it
kiro-fix-session-images <id>

# Fix every session
kiro-fix-session-images --all

# Report what would change without touching any file
kiro-fix-session-images --all --dry-run

# Use a smaller target size (default 1900, must be below 2000)
kiro-fix-session-images --all --max 1600

# Scan a different sessions directory (default ~/.kiro/sessions)
kiro-fix-session-images --all --root /path/to/sessions

Each affected session is printed as sess_<id>: resized X/Y images, followed by a done: N oversized image(s) fixed summary. With --dry-run the wording changes to would resize and found.

How resizing works

Images are resized with Pillow, which is installed as a dependency, and saved back in their original format (PNG, JPEG, GIF or WEBP) with their EXIF metadata and color profile intact.

If a session contains an image Pillow cannot read, that session is skipped with a message on stderr and the rest of the sweep continues; the exit status is 1.

Platforms

macOS, Linux and Windows. Requires Python 3.9 or newer.

License

MIT