carmelyne/agent-hook-face-reactions

This project turns an old tablet into a small screen that shows a face reacting to what your AI coding assistant is doing. Instead of staring at a terminal to see if a tool is thinking, waiting, or stuck, you glance at the tablet and see an expression that tells you the current state. The setup works by running a tiny local server on your computer. Any command line AI tool, such as Codex, Claude, Gemini, or a local Ollama model, can call one shared command, facectl.sh, and pass it a state and a source name. States include happy, thinking, loading, attention, blocked, and needs-info. The source tells the display which tool triggered the change, though the current demo uses one visual style regardless of which tool called it. All the files live in a shared folder at home/.agents/tablet-face so that no single AI tool owns the setup. Multiple tools can write to the same state file, and the tablet just watches one browser page for updates. To use it, you copy over an index.html file, the facectl.sh script, and a small Python server, make the script executable, and open the page in a browser on the tablet using your computer's local network address. The project includes example hook scripts for Codex, Claude, and Gemini showing how to wire real agent events, like a finished turn or an approval request, to specific facial states. If you open the HTML file directly without the local server running, it will randomly cycle through faces as a preview instead of reflecting real activity. The README notes this is meant for repurposing an old tablet, since it only needs Wi-Fi, a browser, and to stay plugged in. It also states that hook calls should be fast and never block the agent, so a sleeping tablet or a server hiccup will not interrupt your actual workflow.