Features
What humanize does, described in one page. Every entry links to a guide that shows you how to use it, and to the reference that spells it out completely.
If you have not run it yet, start with the Quickstart instead.
The idea
humanize runs flows: directories of Python that drive one or more coding agents in a loop and write down everything they did.
It does not talk to a model provider. It drives the coding agent CLI you already have — nine of them, plus anything that speaks the Agent Client Protocol — logged in the way you already log in. There is no API key for it to hold. The one exception is DeepSeek Harness, which ships inside humanize and does take a key, because it has no subscription login to use instead.
Two ways in, and they run the same flows and leave the same records behind. hmz opens a terminal interface. hmz exec runs a flow with nobody watching, which is what a script, a cron entry or a CI job wants.
At the prompt
The interface is a transcript, an editor under it and a status line under that. The status line's right-hand end lists the keys that do something right now, which is the whole of what you have to remember.
A line typed mid-turn goes into the turn. Not after it. "Actually, use pathlib" arriving four minutes into a refactor reaches the agent that is doing the refactoring. Guide
One transcript, several conversations. A flow driving four agents is four conversations, and tab steps between the ones that are working. Guide
Showing the working. /details toggles between every tool call and thought, or only what the agent says. It changes the screen and nothing about the run. Guide
The shape of a run. /status says who is working, who handed to whom, and what it has cost so far. Guide
Being away. /afk decides what happens when an agent stops to ask you something: wait, or tell it nobody is there and let it carry on. Guide
Everything you typed here before, on ↑ and ↓, kept per project. Guide · What a half-typed line could become, under the editor. Guide · /export writes the transcript out as it was written. Guide
Reopening finds it as you left it. The flow, the agents, the efforts and the accounts are remembered per project. Guide
esc stops the flow — the whole flow, not just the turn. ctrl+c takes back something smaller. Guide
What an agent is
An agent is a CLI, a model, an effort and an account, written cli/model:effort.
Efforts. How hard to think: off, low, medium, high, max, mapped onto whatever each backend calls the same idea. A flow can move an agent's effort between turns. Guide
Permissions. Four rungs from read-only to bypass. The default is bypass, and there is no setting that turns permission prompts back on. Guide
Skills. Two kinds: the ones that CLI has installed, which humanize reads and never changes, and the ones a flow carries in its own skills/ and mounts onto every session it opens. Guide
Goals. The backend's own goal feature — the agent decides for itself when the objective is met, and until it does, a turn that would have ended starts another. Guide
Questions. An agent stopping mid-turn to ask its user something, answered by whoever is at the prompt or by the flow. Guide
Answers in a shape. A turn given a pydantic model answers with that model instead of prose, so a flow reads a field rather than searching a paragraph for a phrase. Guide
Hooks. Python callables hung on the moments of a turn — before a tool runs, when one asks permission, when the agent tries to stop. Guide
Cost and rate. What has been spent, how fast the tokens are arriving, and how hard the model is currently thinking. Guide
The person as an agent. You, driven by a flow like any other agent, so a flow can ask a human the same way it asks a model. Guide
Reporting. humanize asks once whether to send crash reports to its developers, and says what one carries before you answer. Guide
Where the work lands
Providers. An agent may name the account it runs as, so one flow can drive one CLI as your subscription and as somebody else's endpoint at the same time. Guide
Containers. Give an agent a container of its own, brought up on its first turn and taken down with it. Guide
Remote execution. Moor an agent to an ssh host so its commands land there while the process stays here. Guide
Worktrees. One agent working in several directories at once, one session per directory. Guide
Flows
A flow is a directory whose __init__.py holds a function marked @flow, taking the agents and the task. Everything else is ordinary Python — a loop, a subprocess.run, a file read between turns.
Writing one. The shortest useful flow is about a dozen lines. Guide · Loops. Ralph, stateful ralph, actor-and-reviewer: the shapes a loop over one or two agents takes. Guide
Settings of its own. A third argument annotated with a pydantic model becomes fields on /config and lines in a -c setup.yaml. Guide
Many turns at once. Write async def run and a flow can have as many turns going as it likes. Guide
A flow that calls a flow. Composition, with the inner flow's agents supplied by the outer one. Guide
Testing one. Without spending a turn. Guide
Flowverses. A git repository with a flows/ directory in it, offered under its own name. official is there from the start. Guide
What a run leaves behind
Cycles. Every run of a flow is a directory under ~/.humanize/cycles/, holding what the run was and what happened in it.
Tracing. hmz trace collect turns a run plus the backends' own transcripts into a Chrome trace: one process per agent, one track per row of its sessions, one slice per thing it did. Open it in Perfetto. Guide
Picking a run up. A loop stopped on Thursday — by esc, or by a machine going down — carried on from where it stopped. Guide
Unattended. The same flows from a script. Guide · In CI.Guide
Where the detail is
| CLI | Every command and flag |
| TUI | Every key and /command |
| Flows | The @flow contract, settings, composition, flowverses |
| Agents | Turns, sessions, hooks, shapes, efforts, permissions, skills, and what each backend can do |
| Machines | Containers, worktrees, where a session works |
| Providers | Accounts, and adding a CLI of your own |
| Remote execution | hmz anchor, and what lands where |
| Tracing | Cycles, the trace format, what a slice carries |