Your first run

You set up ralph_loop in a scratch repository, start it on a small bug, watch it work, and stop it once the bug is fixed. At the end, that directory remembers the setup, so the next run there is one line.

At a glance

• You will choose a flow, give its role an agent and the run a budget, start it with a task, watch it, and stop it.
• Use it when you have just installed humanize, or want to see how any flow is set up at the prompt.
• You need humanize and one signed-in coding agent CLI (Installation), git, and about ten minutes. The run itself costs a few cents.

Use a scratch repository

A flow's agents run with approvals bypassed: they edit files and run commands without asking you. Start somewhere you can throw away, and read Security before you point a flow at work you care about.

hmz

The flow menu: a project flow is chosen, its one agent is set to another model and effort, a budget of 20 minutes is set, and the menu is saved. The task is then typed at the prompt.

The same steps, recorded with stand-in CLIs on a project's own flow, @local/twice.

Try it

In a git repository you can throw away:

hmz
/flow                        choose ralph_loop, set its agent and budget, then save
❯ Fix the bug in calc.py.    the task; the flow starts
ctrl+c ctrl+c                stop it once the bug is fixed

The steps below take each of those in turn.

How it works

Three words cover what you set up:

• A flow is the loop: which agent is asked what, in what order, and when to stop. ralph_loop, used here, gives one agent the same task again and again, in a fresh conversation each round, until its budget runs out or you stop it.
• A role is a slot the flow declares, such as agent, builder or reviewer. You fill each role with an agent: a CLI, the account it runs as, a model, and an effort.
• A budget is what a run may spend: time, dollars or output tokens. Every flow except chat needs one, because most flows are loops that never end on their own.

You set all three in the /flow menu, save, and then type the task. Nothing runs until you send that first line.

1. Make something to fix

calc.py subtracts where it should add:

mkdir -p ~/tmp/humanize-demo && cd ~/tmp/humanize-demo && git init -q
printf 'def add(a, b):\n    return a - b\n' > calc.py
git add -A && git commit -qm "a calculator with a bug in it"
git tag start

The tag marks where you started, so you can see everything the agent changed later, whether it commits its work or not.

2. Open the interface

hmz

The first time, humanize asks whether to report what goes wrong to its developers. The question says what a report carries; answer either way, and /settings changes it later (Reporting).

The interface opens on chat: one agent that answers you, a turn at a time. For work that runs on its own you choose a flow.

3. Choose a flow

Type /flow and press enter. It opens on Installed: every flow ready to run here, the ones built into humanize first. Press /, type ralph, press enter to go back to the list, and enter on ralph_loop:

hmz · /flowdrawn, not recorded

  hmz › /flow › Installed
  Flows ready to run here: pick one to set it up and run it, or install more
  from a flowverse.

  ╭────────────────────────────────────────────────────────────────────────╮
  │  ralph                                                                 │ 1
  ╰────────────────────────────────────────────────────────────────────────╯
  ╭────────────────────────────────────────────────────────────────────────╮
   built in 2
   ralph_loop                                                     built in 
     The task again and again, a fresh session every round.

   stateful_ralph                                                 built in
     The task again and again, in one session that remembers.
  ╰────────────────────────────────────────────────────────────────────────╯

    Install more…   Update   Uninstall   Copy here 3   Search…       Save

  enter set up   / search   tab actions   esc clear search

1. The search box. It keeps the flows whose names hold the letters you typed, in that order. esc clears it, then steps out of the menu.
2. built in is where these flows come from: they ship with humanize. A flow you install from a flowverse is listed under that flowverse's name, and this project's own under local.
3. Copy here copies the flow under the cursor into this project, to read or change. You do not need it now; Security says when you would.

More flows than these

Install more… goes to the flowverses: indexes of flows humanize can install, official first. hmz fetches them in the background every time it opens. Open one, then a flow, and install it; from then on it is listed here, with its version at the end of its row. See Flowverses.

4. Give the role an agent

The flow opens on its roles: a row for each agent it drives, then budget and profiling, and buttons under them, Save last. ralph_loop has one role, agent. humanize fills it with the first CLI it found, so the row already names one.

hmz · /flow › ralph_loopdrawn, not recorded

  hmz › /flow › Installed › ralph_loop                    ● unsaved changes
  Configure each role: an agent (CLI, account, model and effort) or an
  environment; then what the flow takes and what a run may spend.

  ╭────────────────────────────────────────────────────────────────────────╮
   agent                                     claude/claude-opus-5-5:high ▸  1
     agent
   ────────────────────────────────────────────────────────────────────────
   budget                                                           none ▸ 2
     what a run may spend: none set; a run needs one
   ────────────────────────────────────────────────────────────────────────
   profiling                                                       ○ off ▾ 3
     traced only
  ╰────────────────────────────────────────────────────────────────────────╯

      Update    Uninstall    Copy here                               Save  4

  enter open   tab actions   esc back

1. agent, the flow's one role, and the agent filling it as cli/model:effort.
2. budget: none yet. You set it in step 5.
3. profiling stays off here: it is for when you want the programs a run starts in its trace.
4. Save: nothing you change is kept until you press it. ● unsaved changes says something is waiting.

Press enter on agent. An agent is four rows:

hmz · /flow › ralph_loop › agentdrawn, not recorded

  hmz › /flow › Installed › ralph_loop › Set up agent
  Configure this agent: select its CLI, account, model, and reasoning
  effort.

  ╭────────────────────────────────────────────────────────────────────────╮
   cli                                                            claude ▸ 1
     coding agent CLI to use
   ────────────────────────────────────────────────────────────────────────
   account                                                      as local ▸ 2
     account to run as
   ────────────────────────────────────────────────────────────────────────
   model                                       claude-haiku-4-5-20251001 ▸ 3
     model to use
   ────────────────────────────────────────────────────────────────────────
   effort                                                            low ▾  4
     reasoning effort                              ╭─ effort ─────────────╮
                                                   │ ultracode            │
                                                   │ max                  │
                                                   │ xhigh                │
                                                   │ high                 │
                                                   │ medium               │
                                                   │ low ✔                │
                                                   ╰──────────────────────╯
  ╰────────────────────────────────────────────────────────────────────────╯

                                                                      Save  5

  enter choose   esc close

1. cli: the coding agent CLI that takes its turns. Only CLIs that can fill this role are listed. Choosing another clears the account and the model, since both belong to a CLI.
2. account: as local is the CLI as you signed it in. Add an account under its list makes another; see Accounts.
3. model: one of the models that CLI said it runs. The list shows each model's efforts beside it, and Check again under it asks the CLI again.
4. effort: how hard it thinks, from the model's own list. ▾ means enter or a click drops every effort the model takes under the row, hardest first, with ✔ on the one in force; ↑ ↓ and enter, or a click, pick one, and esc picks none. See Efforts.
5. Save keeps the agent. It cannot be pressed until a row has changed.

A row marked ▸ opens a list: enter or →, then pick; each list opens on the choice in force. For a first run, pick a small model and a low effort, as here. Then tab to Save and press enter to save the agent. The line across the top is the way you came, hmz › /flow › Installed › ralph_loop › Set up agent: esc or a click on ralph_loop goes back there.

A flow that has settings of its own asks for them before its roles. ralph_loop has none.

5. Set a budget

Press enter on budget:

hmz · /flow › ralph_loop › budgetdrawn, not recorded

  hmz › /flow › Installed › ralph_loop › Set budget for ralph_loop ● unsaved changes
  A run stops at whichever limit it reaches first; at least one limit is
  required. Leave empty or 0 for no limit.

  ╭────────────────────────────────────────────────────────────────────────╮
   duration                                                            20m 1
     maximum run duration: 1h30m, 90s, PT2H; empty for no limit
   ────────────────────────────────────────────────────────────────────────
   cost                                                                0.5  2
     maximum cost in US dollars, 0 for no limit                            
   ────────────────────────────────────────────────────────────────────────
   output_tokens                                                         0
     maximum output tokens, 0 for no limit
   ────────────────────────────────────────────────────────────────────────
   graceful                                                         ● on ▾ 3
     finish the current turn when a limit is reached
  ╰────────────────────────────────────────────────────────────────────────╯

                                                                       Set  4

  enter change   tab actions   esc back

1. duration: how long the run may take. enter, type 20m, enter. 1h30m, 90s and PT2H are all understood.
2. cost: how many US dollars it may spend. enter, type 0.5, enter: the first key you type replaces the 0.0 that was there. output_tokens works the same way.
3. graceful: on lets the turn that is running finish when a limit is reached; off cuts it off. enter or a click drops the two under it, opening on the one it is not.
4. Set keeps all four: tab to it and press enter. The budget row then reads set, and under it what a run may spend: stops at 20m, $0.50.

The run stops at whichever limit it reaches first. If your account is billed by the token, set a cost as well as a duration. See Every run has a budget.

6. Save

Press tab to reach Save under the roles, and enter. The status line now reads ◉ ralph_loop, and humanize says enter a task to start the flow.

Nothing is applied before you save. esc steps back, and leaving /flow with changes in it asks Save? in a box, with Save and Discard. A flow with no budget refuses to save, saying this flow requires a budget: set the budget first.

7. Say what to do

❯ Fix the bug in calc.py.

Press enter and the flow starts. What the agent says streams into the transcript as it says it:

hmz · ralph_loopdrawn, not recorded

0000000000

❯ Fix the bug in calc.py.

── agent1

● agent is working

● I'll read the file to identify the bug.

● Found the bug: the `add` function is subtracting instead of adding. Let me fix it.

● Done. The `add` function was returning `a - b` instead of `a + b`—now it correctly adds the two numbers.

✻ Worked for 7s · agent2

● agent is working · conversation 2 of 23

agent · claude/claude-haiku-4-5-20251001:low · ● 24

input 70 · output 1.1k · cache_read 146.5k · cache_write 22.2k5

$0.05 · 73 out/s

❯

·|· agent… (3s · ctrl+c twice to stop)6/ commands · shift+enter newline · ← monitor · ctrl+c stop

A real run, with Claude Haiku at effort low. The first round fixed the bug in seven seconds; the second has just started, in a fresh conversation.

What to look at, by number:

1. ── agent marks whose words follow. With several agents, a new one appears wherever the speaker changes.
2. ✻ Worked for 7s · agent closes a turn: the first round is done, and calc.py is already fixed.
3. conversation 2 of 2: a Ralph loop starts a fresh conversation every round, so the agent comes to the task new each time. It keeps going until the budget is spent.
4. The agent line: its role, what it runs, and ● while a turn is open (○ between turns). The number is how many conversations it holds.
5. What the run has spent: tokens by kind, dollars, and how fast the model is writing. See Cost and rate.
6. The status line: who is working, for how long, and how to stop. Its right-hand end is the keys that work right now; ctrl+c stop means ctrl+c would start a stop.
7. Stopped: back to ◉ ralph_loop, and ctrl+c exit, because nothing is running.

While it runs:

To	Do	More
tell the agent something	type a line and press enter; it goes into the turn that is running	Talking to a running turn
see who is working, and who handed to whom	← with nothing typed	Watching a run
stop the flow	ctrl+c twice, or /stop	Stopping
walk away and keep it going	close the terminal, or /exit	Leaving it running

A Ralph loop keeps going round until its budget is spent. Once calc.py is fixed, press ctrl+c twice to stop it.

Check it worked

Look at what it did, from the tag you made in step 1:

git diff start

 def add(a, b):
-    return a - b
+    return a + b

/epics in hmz lists the run you just made, marked stopped.

Next time: one line

humanize remembers the setup for this directory, so the next hmz here opens on ralph_loop with the same agent and budget. Type the task and press enter.

What this directory remembers:

• the flow you last saved, which hmz opens on;
• for every flow you have set up here: each role's agent (CLI, account, model and effort), the flow's own settings, and its budget.

To run another flow without opening the menu, put its name after a $ at the start of the line:

❯ $ralph_loop Fix the bug in calc.py.

The flow is	Name it
built in, or installed from official	$ralph_loop
in this project's .hmz/flows/	$@local/twice
in your ~/.hmz/flows/	$@user/twice
installed from a flowverse you added	$@<flowverse>/<flow>

A flow that is set up here starts at once. One that is not opens the menu on its roles, and saving starts it. $ralph_loop with nothing after it only chooses the flow.

The Workspace page of /settings shows what this directory remembers, and forgets it.

Troubleshooting

this flow requires a budget: set the budget first

Saving refused, because the budget row still reads none set; a run needs one. Set at least one limit in step 5.

The cost row reads 0.00.5

What you type is added to what the row holds. enter on the row, delete what is there, and type the amount again.

hmz: cannot choose a flow while one is running

A $name line, or /flow <name>, was typed while a flow runs. Stop it first (Stopping). /flow on its own opens the running flow's agents instead, and what you save there is what the next run starts with.

The agent row names a CLI you did not want

humanize fills a role with the first CLI it found. enter on the role, then on cli, and pick another; then pick its model again.

A flow from the Flows pages is not listed

Only the flows built into humanize are there from the start. Install the others from a flowverse: see the note under step 3.

Next steps

• Security: what to check before you point a flow at real work.
• The tutorials take a real piece of work start to finish: Beat a benchmark, Port a project and Build a coding agent.
• Flows lists every flow humanize and its official flowverse offer.
• Run it unattended: the same run as one hmz exec line.