Skip to content

The terminal interface ​

Run hmz in a project folder to open the terminal interface. It opens on a new chat with the folder's last agent. You do everything from one prompt: type a line to talk, or type a / command to open a menu.

The terminal interface as it opens: the banner, an agent line above the prompt, and the status line with its key hintsThe terminal interface as it opens: the banner, an agent line above the prompt, and the status line with its key hints

Read the screen ​

From top to bottom:

PartWhat it shows
Opening boxThe banner and the version.
TranscriptWhat you and the agents said. Agent lines start with a green bullet; yours start with ❯.
Lines above the promptOn the right, one line per agent role: its name, role, harness, model and effort. While an epic runs, one line per outworlder and what you spent. On the left, lines you sent that an agent has not taken yet.
Prompt ❯The editor. It always has focus and grows to 10 rows.
Status lineThe state on the left, the active keys on the right.

Use the prompt ​

KeyWhat it does
enterSend the line. Blank lines are not sent.
shift+enter or ctrl+jStart a new line. ctrl+j works in every terminal; shift+enter works where the terminal reports it.
ctrl+cClear what you typed. On an empty prompt, see Stop a run.
↑ on the first row, ↓ on the lastWalk the prompt history.
← on an empty promptOpen the monitor (outside a chat). See Watch a run.
shift+tab, tabSwitch to the next or previous view.
ctrl+qQuit, same as /exit.

How input is routed ​

Humanize checks each line you send in this order and applies the first rule that matches:

The order in which a sent line is read: a side question in btw mode, a Humanize command, the chat harness's own input, a flow start, an unknown command, or words said to the agentThe order in which a sent line is read: a side question in btw mode, a Humanize command, the chat harness's own input, a flow start, an unknown command, or words said to the agent

  1. In btw mode, a line without a leading / asks a side question. See Ask a side question.
  2. A / line that names a Humanize command runs that command.
  3. In a chat, a line starting with $, /, ! or @ goes to the chat's harness. See Commands, skills and files in a chat.
  4. $<flow> <task> starts that flow on the task, such as $ralph_loop fix the build. If the flow is not set up here yet, /flow opens on it first, holding the task. See Start an epic. If a question is waiting, the line answers it instead.
  5. Any other / line fails with hmz: no such command: /<name>.
  6. Anything else goes to the agent: it starts or continues the chat, steers the running flow, or answers a waiting question. See Chat with an agent, Talk to a running flow and Answer a flow's questions.

If a command does not work in your current view, Humanize tells you where it works. Command arguments split like shell words, so quote arguments that contain spaces.

Recall prompt history ​

Humanize saves every line you send to ~/.hmz/history.jsonl with its folder. Press ↑ and ↓ to walk the lines sent in the current folder, or lines from all folders if you have not sent any here yet. Walk past the newest line to return to the draft you were typing. Consecutive duplicate lines are saved once.

Run commands ​

Type / to list the commands that work right now, along with their arguments and descriptions. Keep typing to filter the list.

A reel: typing / lists the commands, /se narrows to /settings, tab completes it and offers its pages, and enter opens the Notifications pageA reel: typing / lists the commands, /se narrows to /settings, tab completes it and offers its pages, and enter opens the Notifications page

KeyIn the list
↑ ↓Move the highlight.
tab or enterAccept the highlighted option. It replaces the word and adds a space without sending the line.
escHide the list until you type again.

The list also completes arguments: flows after /flow and $, the nine pages after /settings, and native or flow after /prefer. When a command is complete, one row shows its arguments and enter runs it.

CommandWhat it doesMore
/flow [flow] [task]Set up a flow, or start one on a task.Find and install flows, Start an epic
/epics [@daemon]View and manage epics here or on another daemon.History and search
/resumeResume the last epic here; in a chat, pick an earlier chat.Resume a run, Organise chats
/stopStop the flow or the chat's turn.Stop a run
/exit, /quitQuit. You can leave a running flow running.Leave it running and come back
/clearClear the current view; in a chat, start a new chat.Chat with an agent
/chatReturn to the chat after a flow takes the screen.Chat with an agent
/prefer [native|flow]Choose what $<name> runs in a chat when it matches both a skill and a flow.Skills
/btw [question]Ask side questions of the current session.Ask a side question
/aiTalk to Ai-chan.Ai-chan
/env [role]Inspect files, changes and a shell in the run's environments.Files, changes and terminal
/afk [on|off]Set whether an agent may ask you questions.Answer a flow's questions
/claim [on|off]Answer for one outworlder alone.Answer a flow's questions
/settings [page]Open the settings.Settings

The list shows only commands that apply right now: /claim appears only on an outworlder's view, and outside a chat /resume appears only when there is an epic to resume. For every key in every view, see Terminal commands and keys.

Switch views ​

While an epic runs, the interface keeps a separate transcript for each agent, session and outworlder. You read one view at a time.

A reel: shift+tab steps from the agent's view to the outworlder's view and back; the lines above the prompt mark which one is being readA reel: shift+tab steps from the agent's view to the outworlder's view and back; the lines above the prompt mark which one is being read

Press shift+tab for the next view and tab for the previous one. The cycle includes each session with an open turn, followed by each outworlder. The lines above the prompt mark your current view as reading, and mark any other view as unread when new lines arrive. Ended sessions leave the cycle; open the monitor to read them. A chat has only one view, so both keys do nothing.

The interface keeps the last 2000 lines of up to 32 transcripts.

Read the status line ​

The left side shows the current state: starting…, the active agents and their elapsed time (in a chat, running… then done), waiting for you, or, when idle, the agent (outside a chat, the flow that is set up) and the folder. Prefixes mark active modes: afk when agents may not ask you, details when tool calls are visible, btw in btw mode, and 2 flow updates when installed flows have newer releases. After you copy text, it shows copied for two seconds.

Two prefixes mark what the terminal follows. When you open an epic or chat on another daemon with follow from /epics @<name>, you see @<daemon> · <folder> and the transcript shows following <path> on <daemon>; esc comes back. Press esc at the prompt to return to that daemon's list. A new Ai-chan conversation shows Ai-chan · new · <scope> until your first line; a conversation you follow shows Ai-chan#<n> · <scope>. See History and search and Ai-chan.

The right side lists only the keys that work right now, such as enter send, shift+tab switch view, / commands, ← monitor and what the next ctrl+c does. In a narrow terminal, hints drop from the left of the key list; the state on the left side is never cut.

Use menus ​

/flow, /epics, /settings and /ai open full-screen menus. Every menu shares the same layout and keys.

The Notifications page of /settings: the way there across the top, the list with the cursor row filled, switches at the right, the Save button and the keys that workThe Notifications page of /settings: the way there across the top, the list with the cursor row filled, switches at the right, the Save button and the keys that work

KeyWhat it does
↑ ↓Move the cursor.
enterOpen or select the row.
→Enter what the row opens.
← or backspaceGo up a level.
escRevert a row you are editing, clear the search, or leave the menu.
tab, shift+tabMove between the search box, the list and the buttons.
/Search the list, when searchable.
mOpen the row's menu, when available.

You can also click any row, button or breadcrumb across the top.

  • Rows. A value ending in ▸ opens a sheet. A value ending in ▾ drops a list of options with ✔ on the active one. A switch reads ● on ▾ or ○ off ▾; its list opens on the opposite value, so pressing enter twice flips it.
  • Forms. Type on a form row to start editing it. Press enter to keep the value and move to the next unanswered row, or esc to revert it. On path rows, press tab to complete paths as in a shell.
  • Buttons. The primary action button sits last on the right in green. Destructive buttons are red.

Save or discard changes ​

Menus hold your edits until you save. While you have unsaved edits, the top line shows ● unsaved changes. Press Save, or leave the menu to open a Save? prompt with Save and Discard (esc returns to the menu).

A reel: enter on a switch drops its values, picking off marks the page as unsaved, and leaving the settings opens the Save? boxA reel: enter on a switch drops its values, picking off marks the page as unsaved, and leaving the settings opens the Save? box

Actions that install, fetch, import, export or upload take effect immediately.

Select and copy text ​

Drag across the transcript to copy from press to release. Double-click to copy a word, or triple-click to copy the whole line. Humanize copies the unwrapped text and sends it through the terminal to your local clipboard, so copying works over SSH. In most terminals, hold shift while dragging to use the terminal's own selection instead. The transcript follows new lines until you scroll up, and follows again once you scroll back to the bottom.

Change colours ​

By default, the interface uses your terminal's 16 colours and background. Set TEXTUAL_THEME to use a Textual theme instead:

sh
TEXTUAL_THEME=nord hmz

Unknown theme names are ignored. Set NO_COLOR=1 to turn colour off. See Themes and language.

Good to know ​

  • The interface draws without waiting for the network. In the background, it refreshes model lists, flowverse indexes and prices, and checks for new releases.
  • When a new release is out, the transcript prints hmz <version> is out: run `hmz update` to update once. See Install and update.
  • When installed flows have updates, the transcript prints updates available: …; update from /flow.
  • On first start, Humanize asks Report errors to Humanize?. See Report a problem.
  • When a background run finishes or asks a question, a card appears in the corner. See Notifications.
  • There is no separate command palette; type / for all commands.

Open source on github.com/humanfia · RSS: blog · news