humanize

Orchestrate, execute, and observe agent flows

• Install
• Usage
• Documentation
• Security
• Maintainers
• Contributing
• License

pip install git+https://github.com/humanfia/humanize.git

From source, with uv:

git clone https://github.com/humanfia/humanize.git
cd humanize
uv sync

Python ≥ 3.12, and the coding agent CLIs you intend to drive (claude, codex, kimi) on your PATH. Isolation and remote execution ask for more.

To use the TUI:

hmz

If you don't want to use the TUI, you can run a flow over the agents you name, one -a apiece:

hmz exec -f flame_chase \
    -a claude-code/claude-opus-4-8:high -a codex/gpt-5.6-sol:high "fix the build"

An agent is a CLI, a model and an effort, written either way round:

hmz exec -f ralph_loop -a cli=claude,model=claude-opus-4-8,effort=high "fix the build"

-f takes the name of a flow humanize came with, one of your own under .humanize/flows here or in your home directory, or the path to a file anywhere else.

Every run is one cycle, written down under ~/.humanize/cycles as it happens: the flow, the agents, and every session they opened. Collect what it left behind, and open the file in ui.perfetto.dev:

hmz collect

Moor an agent to another machine, so that its work lands there:

hmz anchor --target ssh://build-box claude

• Flows — writing a flow and running it (hmz exec)
• Agents — sessions, goals, models and efforts, names
• Isolation — a container of the agent's own
• Remote execution — acting on another machine (hmz anchor)
• Tracing — trajectories into a trace (hmz collect)

An hmz anchor port is equivalent to a shell on that machine. An export bounds which files a request may name; it does not confine the commands that request can run. Give --token a real secret, and prefer ssh:// or docker://, which need no open port at all.

humanize runs every agent with permission prompts disabled, as flowbench does, and there is no setting that turns them back on — /afk governs whether an agent may ask you a question, not whether it may act. Drive one only in a workspace you are willing to have rewritten — including under isolation, which confines the agent to a container of its own but mounts that workspace into it.

@futrime

PRs accepted. Ask a question or discuss a substantial change first in issues.

Install the hooks once, and every commit is checked before it is made:

uv sync
uv run pre-commit install

A commit runs the formatter, the linter and the type checker. CI runs those over every file, and the tests on each Python the package claims. To run any of it by hand:

uv run pre-commit run --all-files   # format, lint, types
uv run pytest                       # the tests
uv run pytest --run-agents          # also drives claude, codex and kimi for real

If you edit this README, please conform to the standard-readme specification.

Apache-2.0 © Zijian Zhang