Orchestrate, execute, and observe agent flows
humanize runs flows over coding agents; whoever writes a flow is a weaver.
Three things to know before pointing one at a repository you care about. Each is explained in Security:
- humanize runs every agent with permission prompts disabled, and nothing turns them back on.
- A flow is a directory of Python, and reading one means running it, so adding a flowverse is trusting that repository with this machine.
- An
hmz anchorport is equivalent to a shell on that machine. - humanize asks, once, whether to report what goes wrong to its developers, and says what
a report carries before you answer. Nothing is sent by a machine that has not answered yes:
HUMANIZE_SENTRY=offsettles it for a scripted install, and/settingschanges it later.
pip install git+https://github.com/humanfia/humanize2.gitDeepSeek Harness arrives with humanize: its Python SDK and the runtime its turns are taken on are ordinary dependencies, so there is nothing extra to install for it.
To install DeepSeek's own dsh launcher and configuration UI (Node.js required):
npm install --global @deepseek-ai/dsh
dsh webNeeds Python ≥ 3.12 and at least one supported backend: agy, claude, codex,
cursor-agent, grok, kimi, pi, qwen, opencode, mimo or zcode on your PATH — or
none of them, since DeepSeek Harness arrives with humanize. See
Installation.
To use the TUI:
hmzThe run is held apart from the terminal, so closing the terminal does not end it: /detach
lets go of the terminal and leaves the flow running, hmz in the same directory opens it
again, and hmz daemon list says what is being held where.
DeepSeek Harness takes an API key and no subscription login. Run dsh web, save the key
under Settings -> Models, then open /flow in humanize, turn to its agents, set one to
dsh and leave its account row on as local — which uses the key and the base URL saved in
dsh. Alternatively, press a on that row to make a humanize key account, or set the key
before opening humanize:
export DEEPSEEK_API_KEY=sk-…
hmzTo run a flow over the agents you name, one -a apiece:
hmz exec -f official/flame_chase \
-a claude/claude-opus-4-8:high -a codex/gpt-5.6-sol:high "fix the build"To run DeepSeek Harness unattended with that environment variable:
DEEPSEEK_API_KEY=sk-… hmz exec -f ralph_loop \
-a dsh/deepseek-v4-flash:high "fix the build"To collect what a run left behind, and open it in ui.perfetto.dev:
hmz trace collectThe quickstart goes from here to a run you can read back. The home page has one for each role: running a flow, weaving one, and working on humanize itself.
docs.humanfia.ai/humanize2, in six parts. Its source is under docs/.
- Features — what humanize does, a diagram each.
- Flows — every flow it can run, from
chatto seven agents in three isolated lanes, with the shape of each one drawn. - User Guide — running flows. Tutorials first, then a page per feature, each opening with something you can paste.
- Weaver Guide — weaving them. Tutorials first, then a page per thing a flow may be written to do.
- Contributing — working on humanize itself: the checks a commit has to pass, the layers of the code, and these docs.
- Reference — the complete CLI, TUI and Python API.
@futrime, @SihaoLiu, @lyken17.
This project was initiated by Sihao Liu at UCLA PolyArch/humanize, then contributed by NVIDIA Research, MIT HAN LAB, NUNCHAKU and many community members.
PRs accepted. Ask a question or discuss a substantial change first in issues, and see Contributing for the checks a commit has to pass.
uv sync
uv run pre-commit installIf you edit this README, please conform to the standard-readme specification.