Using the terminal UI

The terminal UI (TUI) is where you talk to an agent about the folder you are in. You type a request, the agent reads, edits and runs things, and you watch, steer and review.

You need: a model connected. If you have not sent a message yet, Your first chat is the shorter path. This page covers everything you use day to day.

cd ~/code/my-project
haarness

A plain launch opens a fresh chat. To pick up where you left off:

haarness --continue          # the last chat in this folder
haarness --session <id>      # a specific chat (or -s <id>)
haarness --auto              # open the chat in Auto
haarness --approvals yolo    # open the chat in Yolo

If no provider is connected yet, Welcome to Haarness opens first. See Connect a provider.

What you see

• The transcript. Your messages, the agent's replies, and one compact row per tool call. Click a row to open it, press Ctrl+R to open or close the one nearest the prompt, or run /tools show to open them all.
• The prompt. Where you type. A new chat shows three hints: / commands, @ files · agents and ! shell. When a newer Haarness is out, a new chat also says so above them, with the command that installs it: haarness --update.
• The status band under the prompt. On the left: the agent, the model, the folder and its Git branch, and approvals: review, auto or approvals: yolo (in red; approvals: --yolo when you started Haarness with --yolo). On the right: what the agent is doing, queued messages, and how to stop it.
• The sidebar. The current goal, the agent's plan, token usage, running child agents, MCP servers and recent chats. On a wide terminal it sits beside the transcript; on a narrower one it opens over it. Ctrl+B shows or hides it, and the TUI remembers your choice.

Send a message

Type and press Enter. For a new line, press Shift+Enter or Ctrl+J. A long paste collapses into a chip such as [#1 pasted 20 lines]; it is sent in full.

Up and Down on the first or last line of the prompt recall earlier prompts. Alt+E (or /editor) opens the draft in $EDITOR. Ctrl+C clears a draft; Up brings it back.

A message that starts with / is a command. If no command has that name, nothing is sent: the status line says Unknown command, suggests the closest one, and your text stays so you can fix it. To send such a message as text, start it with a space.

Mention a file, agent or resource

Type @ and part of a name. Pick a match with the arrows and press Tab or Enter.

The mention shows as a chip such as [@src/app.ts]. Backspace removes it. Resources appear only when a connected MCP server offers them.

Attach an image or a PDF

Drag files from your file manager into the terminal, or paste their paths. Each file becomes a chip above the prompt.

• Images (PNG, JPEG, WebP, GIF, HEIC), PDFs, audio and video are accepted.
• Up to 8 files at once, and 20 MiB in total.
• Backspace on an empty prompt removes the newest chip.

Whether the model can read a given format depends on the provider. See Media and limits.

Talk to the agent while it works

You do not have to wait for a turn to finish.

The empty prompt says which one Enter does. A queued message shows above the prompt; click it to edit, send or remove it, or run /queue. To make Enter queue by default in this project, run /input-mode queue (/input-mode steer switches back).

Stop a turn

Press Esc twice, or Ctrl+C twice, within five seconds. The first press tells you what the second will do. /cancel (or /stop) stops it at once.

Stopping a turn also stops the child agents it started. Your files keep whatever the agent had already written; use /undo to roll them back.

With nothing running, Ctrl+C twice quits, and so does Ctrl+D on an empty prompt.

Closing the window does not stop the work

The agent runs in a background server for this folder, not in the TUI. Closing the terminal, starting /new or switching chats leaves running turns and child agents going. Reopen Haarness and you are back in the live chat, with anything waiting for you still waiting.

When you quit, the TUI prints the chat's title and the command that reopens it, such as haarness -s <id>, and says so if the agent is still working.

Answer an approval

When the agent wants to do something your rules say to ask about, a card appears above the prompt with what it wants to run, edit or fetch. When a shell command runs a script file, the card can show the script's first lines too, so you know what you are allowing.

• y and n wait a moment. The button lights up and the answer goes after a short pause. Press the same key again or Enter to answer at once; Esc, Backspace or Ctrl+C takes it back. If you keep typing ("yes, but…"), your text goes to the prompt and nothing is answered.
• a, w, r and u are staged. The card first says exactly what the answer grants; Enter or the same key again confirms it.
• Moving around. ← → or Tab move between the buttons, and Enter picks one. ↑ ↓ scroll a long command or script, and Ctrl+E opens the card to show all of it.

Repository appears only inside a Git repository, and Once + Auto only in Review. A request that must always be asked, such as a Haarness Cloud action that spends money, offers only Allow once and Reject. A website in your Chrome shows an Allow in Chrome card with Allow in this chat (a, the default), Allow once (y) and Deny (n).

The card takes the keyboard only when the prompt is empty, so a message you are typing never answers it. Press Ctrl+G to move to the card, and Ctrl+G again to go back to the prompt.

What each answer remembers, and how to take it back, is in Permissions.

Switch between Review, Auto and Yolo

Every chat is in one of three approval modes:

• Review asks before the things your rules say to ask about, such as working outside the project or reading a .env file. Edits and commands inside the project run without asking.
• Auto sends each of those requests to a reviewer model first. It allows a routine request once, blocks a risky one with a reason the agent reads (the row says Stopped by Auto's reviewer), or leaves it to you with a short note on the card. Auto never saves an "always" rule. Haarness Cloud actions that spend money or delete something, websites in your Chrome, changes to Haarness's own settings files, and asks you configured for a specific command still come to you. New chats start in Auto.
• Yolo approves every one of those requests once, without asking. Deny rules, the plan agent's limits and the requests only you can answer still hold.

Ctrl+Y steps the open chat through Review, Auto and Yolo; /approvals review, /approvals auto and /approvals yolo pick one. haarness --approvals yolo opens a chat in Yolo. The mode applies to this chat and the agents it starts, not to your other chats.

The mode is kept with the chat on the Haarness server. It stays after you quit, it is the same in Desktop and on your phone, and /new starts the next chat in the current chat's mode. Permissions explains which model reviews and how to turn the reviewer off.

Answer a question

Sometimes the agent asks you to choose. Use the arrows and Enter, or press a number. On a multiple-choice question, Space ticks options. When the question allows it, type your own answer instead. Esc cancels the question.

Switch model, agent or reasoning

/plan, /build, /review and /explore switch straight to that agent. Text after the command is sent as your message. Switching model with F2 keeps your draft.

Run a shell command yourself

Type ! on an empty prompt, then the command, then Enter. It runs in the project folder through the same permission rules as the agent's commands. Its output shows under the command: the first 10 lines, then a +N more lines row you can open. A command that fails is marked ✗ with its exit code. The command and its output are saved in the chat, so the agent sees them with your next message. Esc leaves shell mode.

A shell command cannot run while a turn is running. For an interactive shell, use a terminal tab.

Scroll, find and copy

• Page Up / Page Down or the mouse wheel scroll the transcript.
• Alt+↑ / Alt+↓ jump to the previous or next message; Alt+Shift+↑ / Alt+Shift+↓ to your previous or next prompt.
• End or Ctrl+End jumps back to the latest output.
• Alt+M searches every message in the chat. See Find messages.
• Drag with the mouse to select; the selection is copied when you let go.
• /copy copies the last reply. /export writes the chat to a Markdown file in your temporary folder and copies its path.

Switch chat

Ctrl+L (or /sessions) opens the list of chats in this folder. Chats waiting for you come first, marked ⚠ for an approval or ? for a question. Enter opens one; → shows its actions (fork, rename, archive, copy its id). Alt+N (or /new) starts a fresh chat. The previous chat keeps running if it was busy.

Make it yours

A few more settings go in the [tui] section of config.toml, in the same folder as your haarness.json: ~/.config/haarness/config.toml on macOS, Linux and Windows, or $HAARNESS_HOME/config/config.toml when you set HAARNESS_HOME. The TUI reads it when it starts.

[tui]
background_mode = "auto"   # auto | theme | terminal

[tui.statusline]
command = ["my-haarness-status"]
refresh_ms = 2000
timeout_ms = 5000

background_mode = "terminal" keeps your terminal's own background colour; theme paints the theme's. The status line command gets the chat (model, agent, branch, what it is doing) as JSON on stdin and in HAARNESS_STATUS_CONTEXT; its output is shown under the prompt, in place of the model name.

Next

• Review changes: check, comment on and undo what the agent changed
• Find messages and ask side questions
• Keyboard shortcuts and slash commands