| name | update-readme-screenshot |
| description | Refresh the popover screenshot embedded in README.md by running a real Claude Code session against a disposable demo project, rendering monica's popover with that session selected, and uploading the result via `gh image` (no PNG committed to the repo). Use when the popover UI has changed visually and the README screenshot is stale. |
| user_invocable | true |
update-readme-screenshot
Regenerates the README's popover screenshot end to end, without touching any of your
real tmux sessions or their transcripts, and without adding a binary to the repo:
- Creates a throwaway project at
/tmp/demo-app (a two-line main.go + README.md).
- Starts a new tmux session (
monica-demo) and launches a real claude there —
real integration, not fabricated transcript/aistatus files (their exact shapes are
finicky enough that faking them isn't worth it — see AGENTS.md's transcript-format
gotchas).
- Drives one short, clean prompt designed to produce a nicely structured reply (a
heading + a few bullet points) — good screenshot content, no real work content.
- Waits for that session to go idle (polls its
aistatus pid file).
- Builds monica's debug binary and renders the popover via the
MONICA_SHOT hook
(see the sibling screenshot-test skill and AGENTS.md's "Verifying the GUI"
section) — no Screen Recording permission needed.
- Filters the popover to the demo agent by typing
demo-app into the search field
(robust regardless of how many real agents are running — no row-counting).
- Uploads the render via
gh image (produces a github.com/user-attachments/assets/…
URL), posts it as a comment on the meain/monica#4 "Media"
tracking issue for a durable record, and rewrites README.md's
 line to point at the new URL.
- Cleans up: kills the
monica-demo tmux session, deletes /tmp/demo-app, deletes
the demo session's aistatus pid file.
Usage
.agents/skills/update-readme-screenshot/run.sh
Prints the new user-attachments URL on success. Open it (or check the README diff)
afterward to confirm it looks right before considering the refresh done — the script
already rewrites README.md in place (jj status/git status will show it modified),
it doesn't commit anything.
Why upload instead of committing a PNG
Committing screenshots directly balloons repo size over every refresh. Instead images
are uploaded to GitHub's user-attachments CDN via the gh image extension
(gh extension install drogers0/gh-image, authenticates via your browser's
user_session cookie — no PAT scopes needed) and also posted to the
Media issue so there's a durable,
browsable history of every version. Use the same pattern (gh image <file> --repo meain/monica, then gh issue comment 4 --repo meain/monica) for any other image
referenced from README.md or docs.md — never add a binary image to a commit here.
Why a disposable project, not the real running agents
The popover shows real, live tmux/aistatus data with no demo-data seam (unlike
booker's BOOKER_BM_FILE) — pointing MONICA_SHOT at your actual sessions puts
whatever you're actually working on into a file that ends up in the public README.
Early manual runs of this same technique surfaced this by accident (a captured
screenshot showed the very conversation used to drive the test). A dedicated demo
project sidesteps that entirely.
Knobs / troubleshooting
- If the script times out waiting for the demo session to go idle,
claude may be
slower than usual to respond (model load, network) — rerun, or bump the timeouts
inside run.sh.
- If Enter doesn't submit the prompt (occasionally the keystroke lands before the
textarea commits it), the script sends a follow-up Enter automatically; if the
screenshot still comes out at the "Try ..." placeholder rather than a real
agent turn, rerun.
- The script always kills any pre-existing
monica-demo tmux session before starting
and removes /tmp/demo-app first — safe unless you happen to have your own
unrelated session with that exact name.
- Uses
env -u SDKROOT -u DEVELOPER_DIR swift build per AGENTS.md's SDKROOT gotcha.
See the sibling screenshot-test skill for ad-hoc popover/menu-bar rendering that
isn't specifically about refreshing the README.
