RateBait

Tiny local web app for rating AI-generated images and music fast: numpad keys or a pie menu at the pointer to rate (Reject → MVP) and flag (Redo, Broken, Trash), a comment per file, pins and drawings over the picture, the mouse wheel to step through files, a scrollable grid view with folder tiles, multi-select, and a REVIEW.md summary per folder that an LLM can read to learn your taste. Python standard library only: no install, no build.

Made for a 4K screen at 50 inches. ¯\_(ツ)_/¯ Screenshots: docs/screenshot.png (bottom layout, the ` pie menu with a slice lit), full-size 4K docs/screenshot-4k.jpg (right-sidebar layout, three files selected, docked Marks).

More demos: navigation, annotation, multi-select, layout and settings, 4K vs low-res at the same zoomed spot

Navigation: folder tiles (↑ Up and the subfolders; arrows reach them, Enter opens), W/S and arrows, Home/End, the wheel to the previous or next file, file list (☰ list or ▦ thumbnails, ⇅ sort by time/name/size, L hides it), grid with + − size, double-click for fullscreen, Ctrl+wheel zoom, wheel up/down and Shift+wheel sideways, Shift+arrow pan, Ctrl+Space reset, path field with Tab completion.

Annotation: pin a note (A), draw (D: free, Shift line, Ctrl box, Ctrl+Shift circle, Alt arrow, Alt+Shift cross), pen and pin colour (R: hold, point at a slice, let go), undo (Z), hide marks (H), comment (C, Enter saves), Redo (4) and Broken (5) with the rating pop and its 💬 📍 ✏️ badges, the ` pie menu, Del clears.

Mode chip: while Pin, Draw, the comment box or a multi-selection is on, a coloured pill at the top left of the picture (also in fullscreen) names the mode and the key that turns it off, and the picture area and the picture itself are outlined in that colour (Pin red, Draw yellow, Comment blue, Multi-select green).

Multi-select: Ctrl+click files in the list or grid (Shift+click picks a range), then one key rates or flags all of them; C + Enter gives them one comment; Redo asks for the comment first.

Layout and settings: ◫ or X switches to the right sidebar (numpad keys, docked Marks, comment box pops in over the picture); ⚙ Sizes: file list pictures, right sidebar, bottom bar; Rating buttons: colour, icon and title, name 7–9 for your own; Keyboard: every key on a UK keyboard picture; Folder search: folder tiles in the grid; V shows this folder's REVIEW.md.

Compare resolutions: fullscreen keeps the zoom and spot when you switch files, so a 4K upscale and its 960×540 source can be checked side by side, one key apart.

Why "RateBait"?

No database, no memory service, no index to keep in sync. Every review leaves a trail of bait that the next person, script or LLM agent can pick up:

• REVIEW.md in each folder: plain Markdown, grouped by rating, with comments and marks. Easy to read, grep and diff, and to paste into a prompt.
• Embedded data (opt-in): with ⚙ Save the review inside the PNG too on, PNGs carry their own review in an iTXt chunk, next to the generation prompt and seed. Copy or move a file and its rating goes with it; RateBait reads it back in any folder. Off by default, because anyone you share the PNG with can read the comment and marks. The first start asks once, in the same popup as the home folder search.
• File names: the name links a picture to its review entry, its run log and its notes, so plain search finds every place it is mentioned.

Plain files and stable names link everything that matters, cheaply and reliably. Any tool that reads text can follow the trail.

Setup

Setting it up with an AI agent, or letting one act on your reviews? Point it at AGENTS.md.

• Required: Python 3.11+ and a modern browser. Nothing to install: clone and run.
• Optional, for Browse…: on Linux, PyGObject (python3-gobject on Fedora, python3-gi on Debian/Ubuntu) plus a running xdg-desktop-portal, which most desktops ship. Without it, Browse… falls back to Tk (python3-tkinter / python3-tk). Without either, type the folder path instead.
• Folders: pass --root per media folder, or set MEDIA_RATER_ROOTS once (e.g. in ~/.config/environment.d/).

git clone https://github.com/philipplinux/ratebait
cd ratebait
python3 ratebait.py                        # scans the current directory → http://127.0.0.1:8765/
python3 ratebait.py --root ~/Pictures --root ~/Music --port 8765

Try it first: I included some 4K wallpapers in sample-wallpapers/, 13 of them. They're already rated, with comments, pins, drawings and made-up generation metadata (prompt, model, sampler). Start with python3 ratebait.py --root sample-wallpapers to see a finished review, including its REVIEW.md.

Use

• Pick a discovered folder (F opens the list in the header; scans the roots up to 6 levels deep) or Browse… (also B/O) to any local folder. The top of the sidebar has a fuzzy folder search (a bare name searches every folder below the start folder, or all of home with Search all of home in ⚙; a path with / completes level by level; Tab/→ take, ↑↓ pick, Enter opens; folders already shown below are left out), then the open folder with Browse…, then ↑ Up and its subfolders with item counts. Hidden, node_modules-style and network-mounted folders are skipped and the list refreshes every 5 minutes. Roots: --root (repeatable), else MEDIA_RATER_ROOTS (colon-separated), else the current directory.

• Numpad layout: 0 Reject, . Neutral, 1–3 Pass · Love · MVP: rate and advance; ** opens a ring of every rating and flag button at the pointer for rating with the mouse (a pie menu: click a button, or keep ** held, point out of the middle at a slice, which lights up, and let go to pick it; letting go in the middle keeps it open) (old Good/Great/Bad ratings load as Pass/Pass/Reject); ← → (or W / S) and ↑ ↓ navigate (in the grid ↑ ↓ move a row and the arrows also reach the ↑ Up and folder tiles, Enter opens one; at either end they jump to the other end); PgUp/PgDn skip 10 files (in the grid one page); Home/End first/last file; Enter or the fullscreen button beside ⚙: fullscreen (Enter or Esc closes); C comment in a floating bar (Enter saves it and, if the file already has a rating or flag, moves on; Shift+Enter saves it and moves on, closing the bar; Alt+Enter starts a new line; Esc closes it; a saved comment stays in that bar, one line tall unless the text needs more; with ⚙ Show a saved comment off it shows in a box beside the file details instead, click it to edit); Space play/pause audio. + − or Ctrl+wheel zoom the picture, also below 100%; when zoomed, Shift+arrows, drag or the wheel (Shift+wheel sideways) move it, Ctrl+Space resets; not zoomed, the wheel goes to the previous or next file. While zoomed a hint bar at the bottom of the picture shows the zoom level, these keys and Reset (⚙ Hint bars off: a small box bottom right instead). The next two pictures and the previous one are preloaded.

• After a rating or flag is saved its icon pops in the middle of the picture and fades; small 💬 (top), 📍 (bottom left) and ✏️ (bottom right) badges show when the file has a comment, pins or strokes. Rating keys pressed while a save is still running are queued, not dropped. Shift+Enter moves to the next file (also in the grid).

• Extra mouse clicks during a save are ignored. After clicking a rating, Space switches the grid and Enter opens fullscreen instead of repeating that rating; Tab-focused rating buttons retain native keyboard activation.

• Ctrl+click files in the file list (while it is visible) or in the grid to select several (the open file joins the selection); Shift+click selects every file from the last clicked one to this one, Ctrl+Shift+click adds that range. From 2 files on, an overlay shows the keys: a rating or flag key applies to all of them; C, type, Enter gives all of them the same comment, and a rating pressed afterwards sends both. Redo (or any button with 💬 on) first opens the comment box; Enter then sets it with that comment on all of them, replacing their old comments. Esc clears the selection; a plain click selects one file again.

• Before entering multi-select, an edited single-file comment is saved to that file. The shared comment starts empty; if saving fails, the draft and single-file selection stay intact.

• 4 Redo: request changes. Without a comment it stays (press again to remove it); with one it moves on (Redo → C, write → Shift+Enter or Redo again → next). A rating replaces any flag; red Clear (Delete) removes rating, flag, comment, pins and drawing. 5 Broken: defective output, advance. 6 Trash: mark for deletion, advance. Press again to remove the flag. Each gets its own section in REVIEW.md; nothing is deleted automatically.

• 💬 checkbox (next to the keycap in each rating/flag control's bottom row): comment mode. On, the button works like Redo: it sets the value but stays until there is a comment, then pressing it again moves on (or press again without a comment to undo). Off, ratings and flags move on straight away. On for Redo by default; remembered per browser. Tab to the checkbox and press Space to toggle it without rating the file.

• Score mode (F2, or ⚙ Layout): the digit keys score 0–9 and . or * score 10, next to the rating and flag: set and advance, the same score again removes it. A 🔢 Score pill and an orange frame show it is on; rating keys rest until F2 turns it off. The score shows as a coloured number (red 0 to green 10) in the file list and in each grid tile, beside its other icons in the bottom-right corner, and in REVIEW.md as "score N/10".

• ⚙ Settings (top right, or F1): a large window with sections side by side. Layout: file list on/off (also L, or the ◧ button beside the logo), rating buttons in a right sidebar (also X or the ◫ button right of ⚙; buttons arranged like a numpad, the comment box pops in over the bottom centre of the picture and, the Marks panel docks under the mark tools, its list scrolling when space runs short), file details and generation info. Fullscreen and hints: previous/next thumbnails, a saved comment shown over the picture (single view and fullscreen), key hints while drawing, pinning or zoomed. Sizes: file list width 50–100% (scales everything in it), file list thumbnails 50–200% (in the sidebar grid, fewer or more columns), right sidebar 50–100%, bottom bar 50–150% (rating buttons, details and docked Marks in the bottom layout), grid columns × rows. Folder search: whether the path field searches all of home; viewport gridview navigation (the ↑ Up and folder tiles in the grid and in folders without media). Rating buttons (collapsed, click to open): colour, icon and title for every button, plus names for up to three custom buttons on 7 8 9; Reset restores the defaults. A named button appears next to Trash and works like a flag (press again to remove it); empty names hide it, and the × next to a name removes the button and the name saved in the open folder. Names are remembered per browser and saved into each folder, so REVIEW.md lists those files under their custom name. Keyboard: a UK keyboard with numpad where every bound key is coloured by what it does (hover for details), and the modifier and mouse combinations below it. Esc, F1 or × closes the window.

• Single / grid switch (top right; Space/G): the lit half shows the current view. Grid shows all files as a scrollable grid, 3 columns × 3 rows visible by default (set any size up to 10 × 10 in ⚙ Settings, or pick a preset: 2×1, 3×3, 10×10); + − or Ctrl+wheel step the size (2×1, 2×2, 3×3 … 10×10; + gives fewer, bigger tiles, − more), Reset in the bottom-right box returns to 3×3; click a tile to select it, double-click for fullscreen, ↑↓ move by row; tiles show the filename (date-run prefix dropped), the rating icon and, top right, 💬 for a comment and 📍 for pins or drawings; A/D switch to single view of the outlined tile to pin or draw; ratings apply to the outlined tile. On an audio file, Space still plays/pauses; G opens the grid there.

• Folder head and report: 🧭 Explore at the top of the sidebar folds the folder browser away (remembered per browser). 📄 Report (or V) shows the folder's REVIEW.md over the picture area; file names in it jump to that file, Esc, V or × closes it. 🧹 next to it removes every rating, flag, comment, pin and stroke in the folder, also from its PNGs, after a confirmation. Scrolled down, the row rides along at the top of the sidebar; click 🧭 Explore there to scroll back up with the browser open.

• Sidebar: each file shows type, resolution, size and a short date (time for today, day and month this year; hover for the full timestamp). Under the folder controls, ☰ List / ▦ Grid buttons switch between the list and thumbnails only (3 per row by default, rating as a coloured underline); remembered per browser. Under them the ⤢ list scale slider (same as ⚙ File list pictures) sets how many thumbnails fit per row in the grid and how dense the list is (below 100% rows tighten to one line, at 60% the grey line goes too); Below that ⇅ sorts by Time (default, oldest first), Name (A–Z, numbers in order) or Size; press the active one again to reverse it. Click ⤢ or ⇅ to fold its row into a small button beside List/Grid, and that button to open it again. The open file's thumbnail carries a white lens. In the list each file shows type · resolution · size in grey. Drag rows (or thumbnails) to put files in your own order for A/B comparing (dragging a selected file moves all selected files; Esc cancels); arrows, grid and progress bar follow it. The order is saved per folder in this browser; new files appear at the bottom in the chosen sort order, and Reset restores that sort. While there is more to scroll, ▲ under the sort row and ▼ at the bottom show it; click one to jump to the first or last file.

• Progress bar (top): one tile per file in the rating's colour with its icon; the current file is outlined, a click jumps there. When a tile would get narrower than 8 px (many files, narrow window or zoomed in), the bar rolls up into one chip per rating with its count (e.g. ★ 2 MVP · ♥ 156 Love · — 7 Unrated); a chip jumps to the next file with that rating. Still too narrow, the chips drop their names and show icon and count only. ⚙ Settings → Progress bar always rolled up keeps the chips at any width.

• Live: new folders, new or replaced media, and externally saved reviews show up within 10 s, no reload needed. The selected sort and unsaved comment/mark-note drafts are preserved; unchanged audio keeps playing.

• Double-click an image (single view or grid) or press Enter for fullscreen: + − or Ctrl+wheel zoom (at the cursor), also below fit; Shift+arrows, drag or the wheel move (Shift+wheel sideways; not zoomed, the wheel goes to the previous or next file), Ctrl+Space resets; the bottom bar lists the keys and, while zoomed, a zoom bar above it shows the level, the zoom/move keys and Reset (the mode pill sits at the picture's top left, the pen and pin bars float centred over its top; ⚙ Hint bars hides all three); a file with a saved comment shows its comment box in fullscreen (one line tall unless the text needs more; ⚙ Show a saved comment off: only on C); click, Enter or Esc closes (while a pin or draw tool is active, clicks place marks; right-click turns the tool off). Small previous/next thumbnails with their rating icon sit at the left and right edges; click one to jump there (← → work too). The current picture's rating icon sits at the top centre. Turn the thumbnails off in ⚙ Settings.

• 📍 Pin (A) / ✏️ Draw (D): marks drawn over the picture as an overlay; the file's pixels never change. Pin: click the image to drop a numbered pin and type its note in the field that opens beside it (Enter saves, Esc closes; click a pin to edit its note). The Marks panel lists pins and strokes (docked as a row under the rating buttons in the bottom layout or under the mark tools in the right sidebar when there is room, otherwise top right over the picture), each with an editable note or name; ✕ removes one; hidden when there are none. Draw: drag to draw in the chosen colour (R opens a ring of quick colours at the pointer, or hold R, point at a slice and let go, like the rating ring; its middle 🎨 or a click on the colour swatch opens the full picker; new pins take the same colour); hold Shift for a straight line, Ctrl for a box, Ctrl+Shift for a circle around the start point, Alt for an arrow, Alt+Shift for a cross (the keys held on release decide); Z, Ctrl+Z or ↶ Undo removes the newest pin or stroke. A, D, C, Z, R and H also work in fullscreen, where the bottom bar lists the keys. The active tool lights up blue and the cursor turns into a pin or a pencil in the chosen colour; click it again, press its key again, right-click (on the picture or the Marks panel) or press Esc to turn it off (in fullscreen Esc closes the viewer). While a tool is on, an options row with its keys sits centred above the picture when the letterbox leaves room, otherwise over its top (single view and fullscreen); for the pen it also picks Free / Line / Box / Circle / Arrow / Cross for every stroke and the colour. H (the 👁 button left of the tools) hides or shows all marks and turns the active tool off. Marks are saved with the review (also embedded in PNGs), show in fullscreen too, and pins with their notes are listed in REVIEW.md.

• Keyboard access: Tab reaches pin markers and saved-comment previews; Enter or Space opens their note/comment editor. Mark undo history is scoped to the folder and file, and failed saves do not consume it.

• File details (box under the buttons): name, type, resolution, size, date and AI generation metadata. It is never taller than the buttons; when it's cut off, use the details toggle to show everything and activate it again to shrink it back. The toggle works with Enter or Space; clicking the box still works. Hide it altogether in ⚙.

• Ratings are stored per folder in .review.json, and REVIEW.md is rebuilt on every change: a Markdown summary an LLM can read to learn your taste. Sample: sample-wallpapers/REVIEW.md.

  Excerpt of the sample report

  # Media review
  
  - Folder: `ratebait/sample-wallpapers`
  - Updated: 2026-10-06T15:42:43+01:00
  - Progress: 13/13 rated · redo 1 · mvp 2 · love 6 · pass 3 · neutral 1 · reject 0 · broken 0 · trash 0 · unrated 0
  
  ## Redo / changes requested
  - `red-crowned-cranes.png` (image, neutral): Nice pairing and the red crowns pop, but the bodies dissolve into mush and the legs are cut off at the bottom. Redo with a cleaner render.
    - Pin 1 (57%, 23%): Red crown: great accent
    - Pin 2 (30%, 66%): Body turns into mush here
    - Pin 3 (72%, 95%): Legs cut off by the frame
    - Stroke 1 (#ff4d6d): Messy texture
  
  ## MVP / best
  - `peacock.png` (image): Best of the set. Symmetric fan, rich colour, lots of black around it so it crops well to any screen. Use as the hero image.
    - Pin 1 (51%, 56%): Head is small but sharp
    - Pin 2 (52%, 11%): Fan top has room to breathe
    - Pin 3 (51%, 89%): Legs fade nicely into black
    - Stroke 1 (#ffd166): Clean fan silhouette
  - `phoenix.png` (image): Huge energy, warm palette and drips that run into black. Works on any screen size; strong candidate for the hero image.
    - Pin 1 (43%, 37%): Head is small but readable
    - Pin 2 (66%, 20%): Wing tips burst out nicely
    - Pin 3 (55%, 85%): Drips fade into black: keep
    - Stroke 1 (#ffd166): Strong diagonal
  …

• With the ⚙ PNG setting on, PNG files also carry their review in an embedded iTXt chunk (pixels and other metadata untouched, mtime kept); with it off, saving a PNG removes a review embedded earlier. Copy a rated PNG into another folder and the rater picks up its rating there, so favourites can be promoted and demoted in a collection folder.

• Saves are atomic per file: .review.json, REVIEW.md and PNGs are written to a temporary file and then swapped in. A failed report save restores the previous JSON state. PNG embedding is a separate best-effort step: if a PNG cannot be rewritten, the folder review is saved, but a copy of that PNG may still carry its old embedded review. Atomic replacement does not guarantee durability across power loss.

Images: PNG, JPG, WebP, GIF. Audio: MP3, FLAC, WAV, OGG, M4A, Opus. Listens on IPv4 loopback only; requests must use the listening loopback address or localhost and the actual server port. Foreign Host headers, cross-origin POSTs and cross-site browser requests (Sec-Fetch-Site) are rejected; command-line clients without Origin remain supported. Browse… (B or O) opens the system folder dialog via the XDG desktop portal (needs PyGObject), falling back to Tk.

Support

If RateBait saves you time:

License

Copyright © 2026 philipplinux. Licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later), see LICENSE. You may use, change and share it, including commercially, but you must keep the copyright notice and credit, and if you distribute a changed version or run one as a service for others, you must publish its source under the same license.