Which Session Is Waiting for Me? Claude Code Hooks on a Stream Deck

Claude Code users often run multiple sessions simultaneously, such as documents, fixes, and research. However, on busy days, a single session asking for permission can get lost among other windows. A script tracks each session's state, such as working, waiting for permission, done, or idle, and writes it to a JSON file. A Stream Deck plugin reads these files every second and colors the keys accordingly.

The issue surfaced when a completed session's key remained blue, indicating it was still waiting for permission. The problem occurred because the plugin read the temp file at the moment it was being renamed, causing a permission error. To fix this, the script retries renaming the file several times with a short wait between attempts.

Additionally, the setup faced another challenge when a session with a cleared command continued under a new ID, resulting in two keys with the same name. The hook now removes the old record when a session starts from a clear and maintains an old-ID to new-ID mapping for the plugin.

To make the setup more engaging, the author added a pixel-art chick named Aqui to the keys. Aqui displays different actions based on the session's state, such as passing a ball when the session is working, holding up a question mark when waiting for permission, showing a bang when the session is done, and closing her eyes with a zig-zag when idle.

The solution, which could be implemented with any colored corner of the screen or sound, significantly reduced the time wasted waiting for permission. This personal project by a Claude Code fan has garnered over 20 YouTube Shorts and a YouTube playlist featuring the chick riding a pixel-art WRX S4 through various seasons.