🌱 Welcome to Factnetize — honest, well-researched articles on tech, health and AI. Get the weekly →
Agentic AI

File-based agent flow in Hermes: one sentence in, one checked image out

A file-based agent flow for Hermes that asks you for one sentence and one yes or no. A script does the bookkeeping; Hermes writes only the prompt.

Five blank manila folders in a wooden tray on a dark desk lit from the left, illustrating a file-based agent flow

⚡ Key takeaways

  • A file-based agent flow keeps every step in files, so each step starts in a fresh session and you can see afterward what happened.
  • The flow in this guide asks you for one sentence and one yes or no. A small script does the bookkeeping.
  • Hermes writes only the image prompt, in a fresh session. The script makes and checks the image.
  • The check is mechanical: size, format, file size. Whether the picture is any good stays your call.

Asking Hermes for an image in a chat works fine once. It gets messy when you want the same job next week, want it to stop after three tries, or want to say no before it goes anywhere. This guide gives you a file-based agent flow you set up once: you type one sentence, Hermes and a script do the work, and you answer yes or no.

Chat or files: a 30-second test

Stay in the chat unless one of these is true:

  • The job repeats. The same steps again next week.
  • A step can loop. Generate, check, try again: that needs a ceiling.
  • You must approve the result before it goes anywhere.
  • You want a record of what each step did.

Images tick all four, which makes them a good first flow.

What you need

  • Hermes Agent, working in Hermes Desktop or a chat app.
  • Python 3. If setup complains that Python is missing, install it from python.org. The flow needs no extra packages.
  • A Pollinations key for the image service: sign in on the Pollinations keys page and create one.
  • The flow itself: download img-flow.zip (about 9 KB).

Step 1: set it up once

Unzip the folder somewhere it can stay, such as your Documents folder. Then double-click setup.cmd and paste your Pollinations key when it asks. The key stays hidden while you paste. On macOS or Linux, run python3 flow.py setup in the folder instead.

Setup saves the key in pollinations.key inside the folder and installs a Hermes skill called img-flow. You should see “Hermes skill installed” with the skill’s path, then “Ready.”

Step 2: ask for an image

Every Hermes skill doubles as a slash command. In Hermes Desktop or your chat app, type:

/img-flow a rocket climbing away from a small Earth, big bright flame

Hermes starts the flow and waits for it. The flow turns your sentence into a brief, has Hermes write the prompt in a separate fresh session, makes the image and checks the file. If the check fails, it tries again by itself.

You should see Hermes reply with the path to the image and ask whether to keep it.

Step 3: say yes or no

Open the image. If it is right, answer yes, and the flow copies it to the job’s out folder.

If it is not, say what is wrong in your own words, for example “the flame is cut off by the top edge.” Your words go into the job’s feedback.md, and the next prompt is written against them. Then you get a new image and the same question.

Each job gets at most three attempts. After that the flow stops and says why; start a new job with a clearer sentence.

Prefer the terminal? In the img-flow folder, python flow.py run "a rocket climbing away from a small Earth" does the same and asks the question right there.

What the file-based agent flow does behind the scenes

Every image gets its own folder under jobs, named after your sentence:

jobs/
  rocket-climbing-away-small-01/
    brief.md       your sentence, what to avoid, the size
    prompt.md      written by Hermes
    attempt-1.jpg  one file per attempt
    feedback.md    failed checks and your "no" answers
    log.md         one line per step
    state.md       what comes next, attempts, gate
    out/           the image you kept
Listing 1 · One job folder

Only one step is model work: writing prompt.md. For that, the script starts a separate Hermes session that reads the brief and any feedback, writes the prompt and exits. Its rules sit in AGENTS.md in the folder, which Hermes loads from the folder it starts in.

Everything else is plain code. generate.py makes the image. The check looks only at the file: it must exist, be a real image of a reasonable size, and match the 1200Ă—640 in the brief. The script is the only code that writes state.md, and every step adds a line to log.md, so you can always see where a job stands.

To use another image service, replace generate.py with a script that takes the same arguments and saves one image.

Troubleshooting

Hermes does not know /img-flow

Check that SKILL.md exists in the skill folder: %LOCALAPPDATA%\hermes\skills\img-flow on native Windows, ~/.hermes/skills/img-flow on macOS and Linux. Then type /new to start a fresh chat and try again.

“Pollinations answered 401”

The key is missing or wrong. Delete pollinations.key in the img-flow folder and run setup again.

“The ‘hermes’ command was not found”

The flow could not start Hermes for the prompt step. Open a new terminal and type hermes --version. If that fails too, Hermes is not on your PATH yet.

“3 attempts used”

Three images in a row failed the check or got a no. Start a new job with a more concrete sentence: what must be in the picture, and from which angle.

What’s next

The prompt step is a small job, so it rarely needs your most capable model; the post on model routing and cost control shows how to pick a cheaper one. To write a skill like /img-flow for your own jobs, see the guide to Hermes skills.

This article is part of the Agentic AI series.

John Lock
Written by

John Lock

The Tested Weekly

One email a week with the guides we tested, sources linked. No spam.

Leave a comment

Your email address will not be published. Required fields are marked *

Weekly · No spam

The Tested Weekly

One email a week with the guides we tested, sources linked.