| name | hn-local-image |
| description | Use the hn-local-image PyPI package to generate AI artwork from Hacker News headlines on local Apple Silicon. Use when the user asks to run hn-local-image, create HN/front-page/news headline artwork, generate web or e-ink images from Hacker News, compare supported local image models, configure headless uploads, or automate this package from an agent. |
HN Local Image
Overview
Use hn-local-image as a CLI-first package for turning current Hacker News stories into generated images. Prefer the released PyPI package for normal usage; only clone or edit the source repo when the user asks for development work.
The package runs local MLX-based inference and is intended for Apple Silicon Macs with Python 3.12+. Expect first runs to download model weights and take substantially longer than later runs.
Quick Start
Prefer uvx when the user wants to run the package without installing it:
uvx hn-local-image
Use a persistent tool install when the user wants repeated use:
uv tool install hn-local-image
hn-local-image
If already working in the package source checkout, use:
uv run main.py
Common Tasks
Generate the default color web image:
uvx hn-local-image
Generate an e-ink optimized monochrome image:
uvx hn-local-image --target eink
Select a style:
uvx hn-local-image --style story_blueprint
Select an image model:
uvx hn-local-image --image-model flux2-klein-9b
Compare image models with one shared prompt and seed:
uvx hn-local-image compare --style editorial --watermark
Compare all styles for e-ink output:
uvx hn-local-image compare --all-styles --target eink
Run headless and upload the PNG bytes to a webhook:
WEBHOOK_URL=https://example.com/upload uvx hn-local-image --target eink --headless-upload
Options To Prefer
- Use
--target web for full-color 1280x768 PNG output; this is the default.
- Use
--target eink for 800x480 1-bit dithered output intended for e-ink displays.
- Use
--style editorial for the default style.
- Other styles are
story_scene, story_blueprint, story_desk, story_frontpage, and original.
- Image models are
z-image-turbo, flux2-klein-4b, flux2-klein-9b, ernie-image-turbo, and ideogram-4-fp8.
- Use
--output-dir <dir> when the user needs files in a specific location; otherwise outputs go under generated/.
- Use
--model-name <hf-repo-id> only when the user asks to change the local text model used for prompt generation.
- Use
--watermark for model comparisons or visual reports where the chosen image model should be visible in the output.
Agent Workflow
- Confirm the user is on an Apple Silicon Mac before running full generation when hardware is unclear.
- Prefer a help or dry command first if package availability is uncertain:
uvx hn-local-image --help
- Warn before full generation if it may download large model files or take a long time.
- After generation, report the produced PNG path and JSON sidecar path. Do not paste the generated JSON unless the user asks.
- For automation, recommend environment variables only for stable defaults:
WEBHOOK_URL=https://example.com/upload
PROMPT_MODE=editorial
TARGET_MODE=eink
OUTPUT_DIR=generated
HN_URL=https://news.ycombinator.com/
Failure Handling
- If
uvx cannot find the package, check that the package name is hn-local-image.
- If model loading fails, verify Apple Silicon, Python 3.12+, available disk space, and network access for initial model downloads.
- If webhook upload fails, verify
WEBHOOK_URL, network access, and that the endpoint accepts raw image/png request bodies.
- If the user asks to change package behavior or CLI flags, switch to source-repo development rather than treating it as package usage.
