agent_cleanup:ralph_loop

Keep a long run's workspace tidy. ralph_loop, with a cleaner that steps in every few turns: it keeps the work, deletes what strayed, writes down what is next, and the repository's history becomes one commit of what survived. The same cleaner between two agents taking turns is agent_cleanup:flame_chase.

flowverse v0.1.1

In hmz, open /flow → Flowverses → official and install agent_cleanup, which brings agent_cleanup:flame_chase with it. Or run the release without installing anything:

hmz exec -f 'git+https://github.com/humanfia/agent-cleanup-flow@v0.1.1#agent_cleanup:ralph_loop' …

repository: humanfia/agent-cleanup-flow
release: v0.1.1 · commit dc83fcd
earlier: v0.1.0
licence: Apache-2.0

Read from humanfia/flowverse when this site was built.

every role: claude · codex · kimi · pi

at the prompthmz exec

text

❯ $agent_cleanup:ralph_loop make every test in tests/ pass

hmz exec -f agent_cleanup:ralph_loop \
    -a agent=claude/claude-opus-5:high -a cleaner=claude/claude-opus-5:high \
    -p work_paths=src -p budget.duration=12h,budget.cost=100 "$(cat TASK.md)"

agent_cleanup:ralph_loopsimulated

The whole run, at rest. Step through it with the buttons, or drag the bar.

Every few turns the cleaner keeps the work under work_paths, deletes what strayed and writes NEXT.md; humanize checks the result and the history becomes one commit. An empty or failed turn is taken again.

The run, turn by turn

agent — a turn; a session opened for this turn; hands agent in the tree: the tree
agent — a turn; a session opened for this turn; hands agent in the tree: the tree
agent — a turn; a session opened for this turn; hands cleaner in the tree: three turns of work
cleaner — distills it, writes NEXT.md; a session opened for this turn; hands the epoch in the tree: the distilled tree
the epoch — measures, checks, one commit; no turn of a model; hands agent in the tree: work_paths and NEXT.md
agent — a turn; a session opened for this turn

Then round again: an epoch every cleanup_turns turns.

It ends when the budget runs out, or 3 turns in a row come to nothing.

Each cleaning rewrites your git history

Every cleaning replaces the repository's history with a single commit, epoch N: distilled tree. The history it replaces is archived outside the repository, never deleted; the flow's README says how to read it back. Run this on a clone you are willing to have rewritten.

When to use it

On a run long enough that the tree fills up with scratch files, dead ends and notes nobody reads again. Each fresh session then starts from a tree that holds only the work under work_paths and a short NEXT.md saying what to do next.

Roles and params

Role	What it is	How it is filled
`agent`	agent, required	`-a agent=…`	The coding turns, each in a fresh session.
`cleaner`	agent, required	`-a cleaner=…`	One cleaning at a time, in a fresh session that it keeps through its repairs.
`human`	you	filled by humanize; no `-a`	Asked only whether to start on a very large workspace.
`workspace`	environment, local	the directory you start in; no `-e`	The repository every turn works in and every cleaning distills. Its git history is rewritten each epoch.

Each agent role takes one -a role=CLI[@PROVIDER]/MODEL[:EFFORT]; several roles may share one -a, comma-separated. There is no -e to give: workspace is a local environment, the directory you start the run in, and an -e naming it is refused. See Command-line specs.

Every role must be a backend the flow can speak to mid-turn, because a turn that runs too long is told to wrap up: claude, codex, kimi or pi. Any other is refused before the first turn.

work_paths is required: the paths, relative to the repository, where agents may create or change the work, as -p work_paths=src,include or a JSON list. The rest have defaults:

Param	Default
`cleanup_turns`	`3`	Coding turns between cleanings. `0` never cleans.
`next_lines`	`10`	The most lines `NEXT.md` may hold.
`comment_lines`	`30`	Comment lines allowed across `work_paths`. Going over is reported, never cut.
`repairs`	`2`	Times a cleaning that left too much is handed back to the cleaner, before the flow cuts it down itself.
`check_command`	blank	A check to run after each cleaning, such as your test command. If it fails, the cleaning is undone. Blank skips it.
`session_timeout_minutes`	`240`	Minutes before a coding turn is told to wrap up. `0` for never.
`stop_grace_minutes`	`10`	Minutes after that before the turn is cut off.
`idle_timeout_minutes`	`20`	Minutes of a turn spending nothing before it gets a reminder. `0` for never.
`max_tracked_file_mb`	`10`	Files larger than this are never committed.
`confirm_large_workspace_copies`	`true`	Ask before starting on a workspace over 5,000 files or 1 GiB. Under `hmz exec` nobody answers, so the run does not start; set it to `false` to only warn.

What ends it

The budget. A cleaning it interrupts puts the tree back first.
Three turns in a row that come to nothing. A turn that answered nothing, or whose backend failed, is taken again; the third in a row stops the run.

Picking it up

--resume carries on the turn count and the cleanings done so far, so the next cleaning comes when it would have. See Picking a run up.

agent_cleanup:ralph_loop ​

When to use it ​

Roles and params ​

What ends it ​

Picking it up ​

See also ​

agent_cleanup:ralph_loop

When to use it

Roles and params

What ends it

Picking it up

See also