Metadata-Version: 2.4
Name: kiro-fix-session-images
Version: 0.4.0
Summary: Repair Kiro CLI sessions broken by oversized (>=2000px) embedded images by resizing them in place.
Keywords: kiro,session,image,resize,repair
Author: sawitmee
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Utilities
Requires-Dist: pillow>=10
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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):

```sh
uv tool install kiro-fix-session-images
```

Or run it once without installing:

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

Or with pip:

```sh
pip install kiro-fix-session-images
```

## Quick start: fix a broken session

Works for Kiro CLI and Kiro IDE sessions, in both on-disk layouts:
`~/.kiro/sessions/<hash>/<id>/messages.jsonl` and the flat
`~/.kiro/sessions/cli/<id>.jsonl`. A session's sub-agent transcripts
(`sub-executions/`) are repaired along with it.

**1. Exit the broken session.** In Kiro CLI type `/exit`; in Kiro IDE close the
chat tab. Kiro must not be writing to the session file while it is repaired.

**2. Pick the session and fix it.** `cd` into the project directory and run:

```sh
cd /path/to/your/project
uvx kiro-fix-session-images
```

A list of this directory's sessions opens (every directory's, if this one has
none), newest first, each marked `ok` or
`N oversized`. Type to filter (title, id or workspace), use the arrow keys to move, and press
**Enter** to fix the highlighted session. **Tab** switches to sessions from every
directory; **Esc** quits without changing anything.

Prefer to fix everything at once? `uvx kiro-fix-session-images --all`.

**3. Resume the session.**

```sh
kiro-cli chat --resume                  # Kiro CLI: most recent session here
kiro-cli chat --resume-id sess_<id>     # Kiro CLI: a specific session
```

In Kiro IDE, reopen it from the session history list.

If the session still fails, put the original back with
`cp messages.jsonl.bak messages.jsonl` in that session's folder under
`~/.kiro/sessions/`.

## Usage

```sh
# Pick a session from a list (run inside the project directory)
kiro-fix-session-images

# List sessions for this directory with their IDs and status, then exit
kiro-fix-session-images --list
kiro-fix-session-images --list --title deploy   # match title, id or workspace
kiro-fix-session-images --list --all            # every directory

# Fix one session by ID (CLI sess_<id> or the bare IDE id both work)
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](https://python-pillow.org/), 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 an image can't be read, that image is skipped and reported as
`N unreadable`. The other images in the session are still fixed, the rest of
the run continues, and the exit status is 1.

## Platforms

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

## License

MIT
