Installation
Humanize comes two ways. Humanize Desktop is an app for macOS and Windows: download it, open it, and it sets up everything else itself. Humanize CLI is the hmz command, for macOS, Linux, and Windows through WSL: the terminal interface, hmz web and hmz exec. The app runs the CLI underneath, so with the app you get both.
Either way, Humanize drives a coding agent CLI you already use, such as Claude Code or Codex, under your own login, so you also sign in to one.
At a glance
- You will have Humanize Desktop or the
hmzcommand, and at least one coding agent it can drive. - Use it when you are setting Humanize up on a machine for the first time, or adding a backend to one that has it.
- You need macOS 11 or newer, Windows 10 or 11 with WSL 2, or Linux; and
npmfor most of the coding agent CLIs. The CLI on its own needs Python 3.12 or newer, which uv fetches for you.
| Humanize Desktop | Humanize CLI | |
|---|---|---|
| Platforms | macOS, Windows (with WSL) | macOS, Linux, Windows (in WSL) |
| You get | every epic in an app window, notifications, self-updates | hmz, hmz web and hmz exec in a terminal |
| Install | download the app | uv tool install hmz |
Humanize Desktop
Download the installer for your platform from the latest release, or from humanfia.ai, which picks it for you.
macOS
- Download
humanize-<version>-macos-universal.dmg. It runs on Apple silicon and Intel, on macOS 11 or newer. - Open it, and drag Humanize Desktop onto Applications.
- Open Humanize Desktop from Applications. The first time, macOS stops it: see The first time it opens.
The first time it opens
Humanize Desktop is not yet signed with an Apple Developer ID, so the first time you open it, macOS says it cannot check it and offers only Done or Move to Trash. Choose Done, then either:
open System Settings → Privacy & Security, scroll to the message about Humanize Desktop, and click Open Anyway; or
in a terminal, take the quarantine off the app:
shxattr -dr com.apple.quarantine "/Applications/Humanize Desktop.app"
Either is once: macOS remembers it, until you install the app again.
Windows
On Windows, Humanize runs in WSL, and so do your repositories and coding agent CLIs. The app is the window onto it.
Install WSL, if you have not. In PowerShell:
powershellwsl --installThis installs WSL 2 and Ubuntu; restart when it asks, and make your Linux user. Any distribution will do, as long as it is the default one:
wsl --list --verbosemarks it with*and shows its version as2.wsl --set-default <distro>changes it.Download
humanize-<version>-windows-x64-setup.exeand run it. It installs Humanize Desktop for you alone, so it asks for no administrator rights, and puts it in the Start menu.Open Humanize Desktop from the Start menu.
Inside WSL, sign in to a coding agent, as on any Linux machine. A CLI installed on Windows is not seen.
What the first launch does
The first time, the app says Installing Humanize CLI, with each step, while it installs uv and hmz -- in WSL, on Windows. From then on it shows its mark while hmz web starts, then the page, with the sidebar of your epics. It keeps hmz at its own version, so with the app, update the app rather than hmz. What else it does is on Humanize Desktop.
Now sign in to a coding agent, if you have not.
Humanize CLI
On macOS and Linux, in a terminal; on Windows, in a WSL terminal (wsl --install first, as above):
uv tool install hmzpipx install hmzpip install hmzEach one gives you the hmz command, from PyPI. uv tool and pipx put it in an environment of its own, on your PATH from every directory. pip installs into whichever environment is active, so hmz is there only while that environment is. No uv yet? curl -LsSf https://astral.sh/uv/install.sh | sh installs it, and uv fetches the Python hmz needs.
Or run it without installing
uvx runs hmz from an environment uv makes and caches, with nothing put on your PATH. Every argument after hmz goes to it:
uvx hmz # the terminal interface, in this repository
uvx hmz web # every epic on this machine, in a browser
uvx hmz@latest # the newest release, rather than the one uv cached
uvx --from 'hmz[all]' hmz # with the extras belowEach line is a whole hmz command, so type uvx hmz wherever these pages say hmz. hmz update does not apply here: uvx hmz@latest is how this way moves to a new release.
Three backends need an extra
Skip this unless you want DeepSeek Harness, Kimi Code or litellm. Each needs a Python package in Humanize's own environment:
| Extra | For |
|---|---|
hmz[dsh] | DeepSeek Harness (dsh). It has no CLI to install. |
hmz[kimi] | Kimi Code (kimi), alongside its CLI. |
hmz[litellm] | litellm (litellm): a model called directly, with no CLI to install. And its gateway, which runs most CLIs as any account litellm can reach (which). |
hmz[all] | All three. |
uv tool install 'hmz[all]'pipx install 'hmz[all]'pip install 'hmz[all]'You can add one later without reinstalling Humanize. The agent menu lists a backend that is missing its extra, with the install command on its row. With Humanize Desktop, add an extra with uv tool install as above; the app keeps it when it updates hmz.
Sign in to a coding agent
Humanize does not talk to a model itself: it drives a coding agent CLI that you install and sign in to yourself, and runs it as you signed it in -- nothing is copied. One is enough. On Windows, do this in WSL. Pick yours:
npm i -g @anthropic-ai/claude-code
claude auth loginnpm i -g @openai/codex
codex login # no browser here? codex login --device-authcurl https://cursor.com/install -fsS | bash
cursor-agent login# install Google's Antigravity CLI so that `agy` is on your PATH, then:
agy # it asks you to sign in to a Google accountnpm i -g @xai-official/grok
grok login # no browser here? grok login --device-authnpm i -g @moonshot-ai/kimi-code
kimi login # and the [kimi] extra, abovenpm i -g @qwen-code/qwen-code
qwen # then /auth for a plan or a key, and /quit once it is setnpm i -g opencode-ai
opencode auth loginnpm i -g @mimo-ai/cli
mimo auth loginnpm i -g @minimax-ai/code
mcode login # or a MiniMax API key: mcode provider set-minimax-keynpm i -g @earendil-works/pi-coding-agent
pi # then /login, and /exit once you are signed incurl -fsSL https://omp.sh/install | sh
omp # then /login, and /exit once you are signed in# no CLI: install the [dsh] extra, above, and give it a DeepSeek API key
export DEEPSEEK_API_KEY=sk-…If you are already signed in, there is nothing to do.
An API key, or two accounts of one CLI
Make an account on the Accounts page of /settings inside hmz. It can hold a login, an API key, or a gateway of your own, and one flow can run two accounts of the same CLI at once.
Check it works
hmz --versionhmz 0.1.0With Humanize Desktop, the window opens on the sidebar of your epics instead. With the CLI, open the terminal interface in any directory:
hmzExample: the first time hmz opens
The first time, Humanize asks each CLI it found which models it runs. That can take a minute. It then asks one question of its own. Here it is on a machine with Claude Code, Codex and Qwen Code signed in:
╭────────────────────────────────────────────────────────────────╮ │ │ │ Report errors to Humanize? │ 1 │ Send error reports to help fix bugs. Sent: the error and │ │ where in Humanize it occurred; … Never sent: nothing you │ │ typed: no task, prompt, or command; … You can change this │ │ later in /settings. │ │ │ │ Yes No │ │ │ │ enter yes esc ask again next time │ │ │ ╰────────────────────────────────────────────────────────────────╯ assistant · qwen/qwen3-coder-plus:high 2 ────────────────────────────────────────────────────────────────────── ❯ ────────────────────────────────────────────────────────────────────── ◉ chat · ~/src/demo 3 / commands · shift+enter newline · ctrl+c exit
What to look at, by number:
- The reporting question, a box over the screen. It says in full what a report carries and what it never does. Its answers are the two buttons: Yes has the focus, so enter says yes, and → moves to No. Answer either way:
/settingschanges it later, and esc asks again next time. See Reporting. - The line above the prompt names the agent Humanize would start:
role · cli/model:effort. Here the role isassistant, and the CLI is the first one Humanize found that could say what it runs. Seeing a CLI and a model here is the proof that Humanize can drive it. - The status line says which flow is chosen,
chat, and the directory. On the right are the keys that work right now.
Check it worked
hmz --versionprints a version.- The line above the prompt reads
assistant · <cli>/<model>:<effort>, not onlyassistant. /flow, then enter on a role, lists your CLI on itsclirow.
Leave with /exit. Now make your first run.
Notes on particular backends
DeepSeek Harness: the key, the models and the platforms
The [dsh] extra installs on Linux (x86-64 and arm64) and on macOS (arm64).
Give it a key in any one of these ways:
DEEPSEEK_API_KEYin the environment, or in a.envfile in the project.DEEPSEEK_BASE_URLpoints it at another endpoint.- The key saved by dsh's own CLI, if you also have it:
dsh web, then Settings → Models. - An account on the Accounts page of
/settings:keyfor a DeepSeek key, or a gateway for a key that belongs to a proxy or another vendor, which also asks for its URL:openai-gateway(OpenAI's Chat Completions or Responses API, URL ending in/v1),anthropic-gateway(Anthropic's Messages API, URL without/v1) orgemini-gateway(Gemini's API, URL ending in/v1beta). A gateway runs at the endpoint's own effort, and an agent that may search there can fetch pages but not search.
Until it has a key, Humanize lists dsh but does not pick it for you. Its models are deepseek-v4-flash and deepseek-v4-pro, at the efforts max, high, low and off:
hmz exec -f chat -a assistant=dsh/deepseek-v4-flash:high "say hello"chat and the six loops FlowBench scores ship with Humanize. A flow from a flowverse, such as flame_chasoid:parallel_git_pr, runs once you install it from /flow; hmz exec installs nothing.
A dsh agent works with full access whatever its flow declares. See Security.
Any other CLI that speaks the Agent Client Protocol
Add it on the Accounts page of /settings, and it is offered beside the thirteen above. See Many backends, one agent.
Where Humanize keeps things
Everything Humanize remembers is under ~/.hmz/: your runs, what each directory was set up to run, your accounts, the flowverses it fetched and the flows you installed. Set HUMANIZE_HOME to keep it somewhere else. A project's own flows, and the runs you export from it, are in .hmz/ in that project. The full list is in the CLI reference.
Older versions used ~/.humanize/ and .humanize/. You don't have to do anything about them: Humanize renames each one to .hmz the first time it looks there. If both are there, it uses .hmz and leaves the old one alone. With HUMANIZE_HOME set, ~/.humanize is left where it is, so move any flows of your own in ~/.humanize/flows to ~/.hmz/flows yourself. See Files.
Troubleshooting
The line above the prompt reads only assistant
No CLI has answered: Humanize found none, or the one it found is not signed in and cannot say what it runs. Typing a task then says hmz: no coding agent is installed.
Humanize looks on your PATH, then in ~/.local/bin, /usr/local/bin, /opt/homebrew/bin, /usr/bin and /bin. See which ones a shell finds:
command -v agy claude codex cursor-agent grok kimi mcode mimo omp opencode pi qwenA CLI that is listed but still not offered is usually not signed in: run its sign-in from step 2 again, then open hmz again.
hmz: command not found
pip installed into an environment that is not active, or uv tool's and pipx's directory is not on your PATH. Run uv tool update-shell or pipx ensurepath, and open a new shell.
A model I expected is missing
What a CLI runs is asked once and remembered for a week, then asked again in the background. To ask now, open /flow, enter on a role, then on its model row, and press Check again under the list.
dsh, kimi or litellm is listed with an install command
Its extra is missing. Run the command on its row, or reinstall with the extra from Three backends need an extra.
Upgrade
hmz updatehmz update asks PyPI for the newest release and has whatever installed hmz install it -- uv tool, pipx, or pip in an environment you made -- keeping the extras it was installed with; in a terminal a spinner shows while PyPI is asked. hmz and hmz web say when a newer release is out. An install from a checkout is updated there, with git pull. By hand, the same is:
uv tool upgrade hmzpipx install --force hmzpip install --upgrade hmzEach moves Humanize to the newest release. uv tool upgrade keeps the extras it was installed with; pipx and pip install again, so name an extra again: pip install --upgrade 'hmz[all]'.
With Humanize Desktop, update the app instead: it puts the uv tool hmz back at its own version the next time it opens with no epics running, older or newer, keeping its extras.
What changed is in each release's notes, on GitHub Releases.
Uninstall
Stop any run you left running first: hmz in its directory, then /exit. To remove Humanize Desktop, see its page. For the CLI:
uv tool uninstall hmzpipx uninstall hmzpip uninstall hmzTo also forget everything Humanize remembered, your accounts included, remove ~/.hmz, or wherever HUMANIZE_HOME points:
rm -rf ~/.hmzThe coding agent CLIs and their own logins stay as they are.
Next steps
- Your first run: choose a flow, give it an agent and a budget, and watch it work.
- Security: what to check before a flow touches work you care about.
- Accounts: run a CLI as an API key, a gateway or a second login.
- Many backends, one agent: what each backend can and cannot do.