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

# Your first chat

This walks through one short chat in the terminal UI: ask about your code, let Haarness change
something, check the change, undo it, and come back to the chat later.

**You need:** Haarness [installed](https://haarness.ai/docs/start/install.md) and a model
[connected](https://haarness.ai/docs/start/connect-a-provider.md). **Next you will:** learn the rest of the
[terminal UI](https://haarness.ai/docs/tui/tour.md).

Using Desktop instead? The same steps are in [Work in a chat](https://haarness.ai/docs/desktop/the-conversation.md).

## Open Haarness in your project

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

Haarness opens in that folder and works on the files inside it. If no model is connected yet,
**Welcome to Haarness** opens first so you can connect one.

## Ask a question

Type a question and press Enter:

```text
Explain how this project is organised
```

You see each step as it happens, such as the files it reads and the searches it runs, then its
answer. To start a new line instead of sending, press Shift+Enter or Ctrl+J.

To point at a file, type `@` and part of its name, then pick it from the list.

## Ask for a change

```text
Add a --verbose flag to the CLI and document it in the README
```

Haarness edits the files and runs the commands it needs, such as your tests. **Inside the project
it does this without asking.** It stops to ask before it:

- reads or writes files outside the project folder
- reads a secret such as a `.env` file
- changes Haarness's own settings files
- switches to a different agent
- generates images or video, which costs money

To make it ask before every edit and every command as well, add this to
`~/.config/haarness/haarness.json` (create the file if it does not exist):

```json
{
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}
```

[Permissions](https://haarness.ai/docs/security/permissions.md) explains the rules and what you can allow or deny.

## Answer a permission prompt

When Haarness asks, a card above the prompt shows what it wants to do, and these answers:

| Answer | Key | Allows |
| --- | --- | --- |
| Allow once | `y` | This request only |
| Reject | `n` or Esc | Nothing. The agent is told you said no |
| Always | `a` | Matching requests in every chat, until the Haarness server stops |
| This folder | `w` | Matching requests in every chat in this folder, remembered after restarts |
| Repository | `r` | Matching requests in every worktree of this Git repository |
| Once + Auto | `u` | This request, then switches this chat to Auto |

`y` and `n` light their button and answer a moment later; press the same key again, or Enter, to
answer at once, or Esc to take it back. `a`, `w`, `r` and `u` reach past this one request, so the
card first says exactly what they grant: press Enter, or the same key again, to confirm.
**Repository** appears only inside a Git repository.

If you were typing when the card arrived, your text stays in the prompt and nothing is answered:
press Ctrl+G to move to the card, and Ctrl+G again to go back.

## Let it work without asking

Every chat starts in **Review**, which asks about the things listed above. **Ctrl+Y** switches the
open chat to **Auto**. In Auto, a reviewer model looks at each of those requests: it allows a
routine one once, blocks a risky one with a reason the agent reads, or leaves it to you with a
short note on the card. Auto never saves an "always" rule, and some requests still always come to
you, such as Haarness Cloud actions that spend money or delete something. Press Ctrl+Y again to go
back to Review.

The status band under the prompt shows `approvals: review` or `auto`. The mode belongs
to the chat: it stays after you quit, and Desktop and your phone see the same one.
[Permissions](https://haarness.ai/docs/security/permissions.md) has the details.

## Review what changed

```text
/diff
```

A full-screen review opens with the changed files and their diffs.

| Key | Does |
| --- | --- |
| `s` | Switch between uncommitted changes, the whole branch, and the last turn |
| `c` | Comment on the line under the cursor |
| Esc or `q` | Close the review |

When you close it, your comments are added to your next message, ready to send back as feedback.

## Undo a change

```text
/undo
```

`/undo` stops any running work and undoes the latest change. Your message goes back into the
prompt so you can edit it and send it again. `/redo` brings the change back, and `/timeline`
goes back to any earlier point in the chat. If you have edited the same files since, Haarness
refuses to undo rather than overwrite your edits.

## Stop a run

Press Esc twice while Haarness is working, or Ctrl+C twice. The first press says what the second
will do. `/cancel` stops it at once. The chat stays open, so you can ask for something else.

## Leave and come back

Closing the terminal does not stop work that is already running: Haarness keeps going in the
background. When you quit, it prints the chat's title and the command that reopens it:

```sh
haarness -s <id>
```

Or reopen the last chat in the current folder:

```sh
haarness --continue
```

Inside the terminal UI, `/sessions` (or Ctrl+L) lists your chats, and `/new` starts a fresh one.
To quit, press Ctrl+D on an empty prompt, press Ctrl+C twice, or type `/exit`.

## Keys for day one

| Key | Does |
| --- | --- |
| Enter | Send |
| Shift+Enter or Ctrl+J | New line |
| `@` | Add a file or an agent to your message |
| `/` | Run a command. `/help` or Ctrl+P lists them all |
| F2 | Switch model without losing your draft |
| Esc, Esc | Stop the current run |
| Ctrl+Y | Switch this chat between Review and Auto |
| Ctrl+L | Switch chat |
| Ctrl+D | Quit, on an empty prompt |

To attach a PDF, image, audio or video file, drop it on the terminal or paste its path: up to 8
files at once and 20 MiB in total.

## Run a prompt without the UI

```sh
haarness run "List the TODO comments in this project"
```

This prints the answer and exits, using your default model. [Run a prompt from a script or
CI](https://haarness.ai/docs/cli/headless-runs.md) covers choosing a model, JSON output and permissions.

## Next

- [Using the terminal UI](https://haarness.ai/docs/tui/tour.md): everything else in the terminal UI
- [Review changes](https://haarness.ai/docs/tui/review.md): the review screen in depth
- [Local or Cloud](https://haarness.ai/docs/start/local-or-cloud.md): what a Haarness account adds