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

# 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](https://haarness.ai/docs/start/connect-a-provider.md). If you have not sent a message
yet, [Your first chat](https://haarness.ai/docs/start/first-session.md) is the shorter path. This page covers everything
you use day to day.

```sh
cd ~/code/my-project
haarness
```

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

```sh
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](https://haarness.ai/docs/start/connect-a-provider.md).

## 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**.

| You pick | What happens |
| --- | --- |
| A text file | A snapshot of the file is added to your message (up to 128 KiB) |
| `@path:10-40` | Only those lines are added |
| A folder | The list opens that folder |
| An image, PDF, audio or video file | It is attached instead |
| An agent | The agent is asked to hand that work to it |
| A resource from an MCP server | It is read into your message when you send it |

The mention shows as a chip such as `[@src/app.ts]`. Backspace removes it. Resources appear only
when a connected [MCP server](https://haarness.ai/docs/cli/mcp-servers.md) 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](https://haarness.ai/docs/providers/media-and-limits.md).

## Talk to the agent while it works

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

| Press | What happens to your message |
| --- | --- |
| **Enter** | It is sent to the running turn. The agent reads it at its next step |
| **Alt+Enter** | It waits in a queue and runs after the current work |

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`](https://haarness.ai/docs/tui/review.md#undo-a-change) 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.

| Key | Answer |
| --- | --- |
| `y` | Allow once |
| `n` or Esc | Reject. Other requests waiting in this chat are rejected too |
| `a` | Always: every chat on this Haarness server, until it stops |
| `w` | This folder: every chat in this folder, kept after restarts |
| `r` | Repository: this Git repository and its worktrees, kept after restarts |
| `u` | Once + Auto: allow this request, then switch this chat to Auto |

- **`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](https://haarness.ai/docs/desktop/use-your-chrome.md#approve-a-site-in-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](https://haarness.ai/docs/security/permissions.md).

## 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](https://haarness.ai/docs/security/permissions.md) 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

| Press | Does |
| --- | --- |
| **F2** or `/models` | Pick a model. Type to filter, **Ctrl+F** marks a favourite |
| **Tab** / **Shift+Tab** | Cycle agents: build, plan, review, explore, general, and yours |
| **Alt+A** or `/agents` | Pick an agent from a list |
| **Alt+R** or `/reasoning` | Set how hard the model thinks. See [Reasoning](https://haarness.ai/docs/tui/reasoning.md) |
| **Ctrl+T** | Show the model's thinking compactly, in full, or not at all |

`/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](https://haarness.ai/docs/tui/terminals.md).

## 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](https://haarness.ai/docs/tui/messages.md).
- 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

| Command | Changes |
| --- | --- |
| `/themes` | Colour theme |
| `/language` | Interface language, from 17. English until you choose |
| `/keybinds` | The [shortcuts](https://haarness.ai/docs/tui/keyboard-shortcuts.md) you can rebind |
| `/usage-statistics` | Whether Haarness [shares usage counts](https://haarness.ai/docs/cli/stats-and-insights.md#what-does-haarness-share-with-haarness-cloud) |

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.

```toml
[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](https://haarness.ai/docs/tui/review.md): check, comment on and undo what the agent changed
- [Find messages and ask side questions](https://haarness.ai/docs/tui/messages.md)
- [Keyboard shortcuts](https://haarness.ai/docs/tui/keyboard-shortcuts.md) and [slash commands](https://haarness.ai/docs/tui/slash-commands.md)