> ## Documentation index
> Fetch the complete documentation index at: https://haarness.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Work in a chat

A chat is where you ask Haarness for something and watch it work. This page covers everything
from the first message to undoing a turn you did not like.

**You need:** Desktop [installed](https://haarness.ai/docs/desktop/install.md), a project open and a model connected.

## Start a chat

Click **New chat** at the top of the sidebar (⌘N on macOS, Ctrl+N elsewhere). An empty chat asks
**What should we work on in <project>?** and offers four starters: **Explore code**,
**Build a feature**, **Review changes** and **Fix a problem**. A starter fills in the message box
for you to finish. It does not send anything.

Type your request and press Enter to send. Shift+Enter starts a new line. To send with ⌘Enter or
Ctrl+Enter instead, change **Settings → General → Send message with**.

The chat is named after your request once Haarness has a title for it; until then the sidebar
shows **Untitled chat**.

## Add files and context

- **Mention a file or agent:** type `@` and pick from the list. Choosing an agent hands that part
  of the work to it. When the project has connected [MCP servers](https://haarness.ai/docs/cli/mcp-servers.md) that
  offer resources, the list shows those too; a resource you pick is read into the message when you
  send it. Dropping a text file from the project onto the chat adds it as an `@` mention.
- **Attach images, PDFs, audio or video:** click **+** (**Attach**) and choose **Attach files**,
  or drop the files on the chat. Up to 20 files and 20 MiB in total.
- **Attach a screenshot:** **+** → **Attach screenshots** lists your recent screenshots; pick
  the ones you want. On macOS it finds your screenshots folder by itself; on Linux, and to use
  another folder, click **Choose folder…**.
- **Paste something long:** a long paste becomes a **Pasted text · N lines** chip, so the message
  box stays readable. Click it to preview, or choose **Edit as text** to edit it in place. It is
  sent whole.
- **From the Files panel:** **Add file to context** or **Add selection to context** puts a file,
  or the lines you selected, into your message.

## Dictate a message (macOS)

Click the microphone button in the message box (**Start dictation**), or press ⌘⇧M, and speak.
The words appear at the cursor, or replace the text you selected, and are corrected as you go.
Click the button again or press ⌘⇧M to stop. Dictation never sends the message for you; read it
and press Enter.

- Recognition runs on your Mac with Apple's speech engine. The first time, macOS asks for
  microphone access and may download a speech model for your language.
- Before macOS 26, system dictation must be turned on, and macOS may use Apple's speech service
  when your language cannot be recognised on the Mac.
- The audio is not saved to a file and is not sent to the model; only the text you send is.
- Typing, switching chats, opening settings or closing the window stops dictation.

Dictation is not available on Windows and Linux.

## Choose the agent and the model

The controls along the bottom of the message box set how the next message runs:

| Control | What it sets |
| --- | --- |
| **Review** / **Auto** / **Yolo** | Whether permission requests wait for you. See [Review, Auto or Yolo](https://haarness.ai/docs/desktop/the-conversation.md#review-auto-or-yolo) |
| Agent, such as `build` | Who does the work: `build` makes changes, `plan` only plans |
| Model | The model, and its **Reasoning effort** when the model has levels |

In the message box, ⌘. and ⌘⇧. on macOS (Ctrl+. and Ctrl+Shift+. elsewhere) switch to the next
or previous agent; while a reply runs, ⌘. stops it instead. Tab moves keyboard focus as usual. If the model control reads
**Connect a provider**, nothing can answer yet: click it to
[connect a model](https://haarness.ai/docs/desktop/install.md#connect-a-model).

## Follow what it is doing

Haarness answers in plain text. Each step it takes shows as one line, such as *Ran `npm test`*,
*Read `src/server.ts`* or *Edited `src/app.tsx`*. Click a step to see the full command and its
output; an edit's step shows the change, and **Show in Review** opens it in Review. To keep steps
open by default, turn off **Settings → General → Compact tool activity**.

- **The model's thinking** shows as one line that ticks while it thinks, then a
  **Thought for 12s** step you can open. **Settings → General → Thinking display** switches
  between **Compact** (the default), **Show** and **Hide**.
- **Images:** a picture from your project that a reply shows, or that the agent read, appears in
  the chat. Click an image shown smaller than it is to see it full size.
- **Plan:** when the agent works from a checklist, a **Plan** tray above the message box shows its
  steps and updates as it goes. Click the tray's header to collapse it, or **Dismiss plan** to
  hide it until a new plan starts.
- **Command answers:** a slash command that answers with text, such as `/workflow` or
  `/goal status`, shows its answer in a tray above the message box. `/workflow run <name>` follows
  the run until it ends and shows the run ID that `/workflow cancel`, `pause` and `resume` take.
  The answer stays until you dismiss it or send your next message.

Short notices, such as a provider that connected or an error, appear just above the message box,
clear of any approval that is waiting.

## Approve or deny a request

By default, Haarness edits files and runs commands in your project without asking. It asks before
things like working in a folder outside the project or reading a `.env` file.
[Permissions](https://haarness.ai/docs/security/permissions.md) shows how to make it ask more, or less.

When it asks, a card appears above the message box. Its title says what Haarness wants to do,
such as **Access a folder outside this project**, and it shows the exact command or change. For a
command that runs a script file, **View script** shows the start of that script. The card never
takes the keyboard from the message box, so you can keep typing.

| Button | Allows |
| --- | --- |
| **Deny** | Nothing. The model is told you said no |
| **Allow once** | This request only |
| **Always for this folder** | Matching requests in this project folder, remembered after restarts |
| **Always for this repository** | Matching requests in every worktree of this Git repository |
| **Allow once, then Auto** | This request, then switches this chat to **Auto** |

The card shows **Deny**, **Allow once** and, between them, **Always for this folder** or, when
there is more than one way to allow more, an **Always allow** menu with the other three choices.
Hover it to read the rule an "always" answer saves, such as **Commands starting with git push**.

- Denying one request also denies the others waiting in the same chat.
- A request raised by a helper agent has **View agent chat**, which opens that agent's chat.
- A request that must always be asked, such as a Haarness Cloud action that spends money, offers
  only **Deny** and **Allow once**.
- A website in [your Chrome](https://haarness.ai/docs/desktop/use-your-chrome.md#approve-a-site-in-chrome) shows
  **Allow in Chrome**, with **Deny**, **Allow once** and **Allow in this chat**.
- If the request was answered somewhere else meanwhile, the buttons give way to
  **Already answered**.

### Review, Auto or Yolo

The button at the left of the message box shows the chat's approval mode. Click it to choose
**Review**, **Auto** or **Yolo**, press ⌘⇧A (Ctrl+Shift+A elsewhere) to step through them, or search
for **Switch approvals to Review**, **Switch approvals to Auto** or **Switch approvals to Yolo**
(⌘K or Ctrl+K). New chats start in Auto.

- **Review:** edits and commands inside the project run without asking. Requests
  outside that, such as using files outside the project, reading secrets such as `.env`, switching
  agents or generating paid media, wait for you. The browser asks about a site only when
  **Settings → Browser** sets it to **Requires approval**.
- **Auto:** a reviewer model answers those requests for this chat and its helper agents, even
  while Desktop is closed. It approves routine requests once, blocks risky ones with a reason the
  agent reads, and leaves the rest to you with a short note on the card. It never saves an
  "always" rule. A step it blocked reads **Stopped by Auto's reviewer**; a review that takes a moment
  shows **Reviewing…**.
- **Yolo:** every request that would wait for you or the reviewer is approved once, without asking.
  The button turns red while the chat is in Yolo. Deny rules still hold, and so do the requests
  below that always wait for you.

Some requests always wait for you, even in Auto and Yolo: Haarness Cloud actions that spend money or delete
something, edits to Haarness's own configuration, a website in your Chrome, and a site in
Desktop's browser set to **Requires approval** unless **Remember site approvals** is on. Unless
you configure another reviewer model, what the review reads stays with the chat's own provider.
[Permissions](https://haarness.ai/docs/security/permissions.md) explains what the reviewer sees and how to tune it.

The mode belongs to the chat and is kept by the Haarness server, so the terminal UI and your phone
see the same one, and closing Desktop does not turn Auto off. Before a chat exists, on a new chat,
the button sets the mode for new chats Desktop starts in this project or worktree. Chats started
from the terminal UI or your phone keep their own mode.

### Why does it keep asking?

Each **Allow once** covers one request. To stop being asked about the same kind of request, use
**Always for this folder**, or switch the chat to **Auto**. If Desktop is in the background,
**Settings → General → Permission notifications** tells you when a request is waiting.

## Answer a question

Sometimes Haarness needs a decision. A card titled **A question for you** shows the choices, and
the message box says a question is waiting. Click a choice to answer it, or type in
**Or write your answer…** and click **Reply**. When you may pick several, mark them and click
**Reply**. ⌘Enter or Ctrl+Enter answers from anywhere in the card.

## Send more while it works

You can keep typing while Haarness works. By default a new message **steers**: it joins the work
at the next step. Change it to **Queue** to hold messages until the current work finishes, in
**Settings → General → Messages sent while working** (all projects, or **Override for this
project**) or by typing `/input-mode queue`. To queue a single message whatever the setting,
press Option+Enter (Alt+Enter elsewhere).

Queued messages wait above the message box. You can edit, reorder or remove them, or push one
into the current work with **Steer now**.

## Ask a side question

Type `/btw` and a question, such as `/btw why did we pick a transaction here?`. The answer opens
in a **Side chat** column beside the chat. It knows the whole chat, but it uses no tools and adds
nothing to the chat, so the work carries on undisturbed.

- Ask follow-ups in the side chat's own box; **+** starts another thread.
- Open or hide it with ⇧⌘J (Ctrl+Shift+J elsewhere), **Open side chat** in the **Chat actions**
  menu (**⋯**), or **View → Side chat**.
- Threads are kept per chat, and an answer keeps streaming while you look at another chat.

A side chat needs a chat to ask about: send a first message, then use `/btw`. In the terminal UI
and the CLI, see [Ask a side question](https://haarness.ai/docs/tui/messages.md#ask-a-side-question).

## Stop a response

While Haarness works and the message box is empty, the send button turns into
**Stop response**. Click it, press Esc in the empty message box, press ⌘. (Ctrl+. on Windows and
Linux), or choose **File → Stop response**. The chat shows **Stopped** and stays open for your next message.

## Undo a turn

Open the **Chat actions** menu (**⋯**) beside the chat title and choose **Undo last turn**, or
type `/undo`. Haarness puts the files that turn changed back as they were, and puts your message
back in the message box. **Redo turn** (or `/redo`) brings the turn back. If you send a new
message instead, it replaces the undone turn.

If you edited the same files after that turn, the undo stops and reports a conflict rather than
overwrite your edits. Undo and redo are unavailable while a turn is running.

**Compact chat**, in the same menu, or `/compact` summarises a long chat so it takes less room in
the model's context.

## Find in a chat

Press ⌘F or Ctrl+F (**Find in chat**) to search the messages and tool output in this chat,
including older messages further up. Enter and Shift+Enter move between matches, and Esc closes
the search.

To find anything else, such as another chat, a file, a setting or a command, press ⌘K or Ctrl+K.

## Jump through a long chat

Once a chat has two of your prompts, a short stack of dashes appears at the top edge of the
transcript: the **Chat outline**, one dash per prompt, with a longer, brighter dash for the one you
are reading. Hover over it to list every prompt by its first line, and click one to jump to it. In
a narrow window the outline is hidden.

From the keyboard, ⌘↑ and ⌘↓ (Ctrl+↑ and Ctrl+↓ elsewhere) move to the previous or next prompt,
and ⌘⇧↓ jumps to the latest message. In the message box these work while it is empty.

## Fork, rename and archive

- **Fork:** hover over an answer and click **Fork from message**, or choose **Fork** in the
  **Chat actions** menu. The new chat starts with a **Continued from &lt;title&gt;** marker that
  opens the original.
- **Rename:** double-click the chat title, or choose **Rename** in the **Chat actions** menu.
- **Archive:** choose **Archive** in the **Chat actions** menu, use the archive button on the
  chat's row in the sidebar, or press Delete on the selected row. Archived chats leave the
  sidebar, but search still finds them and you can restore them.

## Continue on your phone

Type `/remote-control` (or `/rc`) in a chat to continue it from your phone or any browser signed
in to [Haarness Cloud](https://haarness.ai/docs/cloud/overview.md). Scan the QR code it shows, or open its link. The
chat keeps running on this computer, with its files and model keys, and a **Remote** chip appears
beside the message box while it is shared. Click it for the link again, or to **Stop sharing**.
With [Haarness for iPhone](https://haarness.ai/docs/cloud/iphone.md) or [Haarness for Android](https://haarness.ai/docs/cloud/android.md)
installed, the code opens the chat in the app, which can notify you when the chat needs you and
lets you answer from the notification. See
[Remote control](https://haarness.ai/docs/cloud/remote-hosts.md#continue-a-chat-on-your-phone).

## Close the window

Closing Desktop does not stop running work. Reopen the project and the chat is still there, with
any work that finished while you were away.

## Next

- [Review changes, files and terminals](https://haarness.ai/docs/desktop/projects-and-panels.md)
- [Permissions](https://haarness.ai/docs/security/permissions.md): what Haarness may do without asking