Skip to content
aarness.
DocsStart here
On this page

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 and a model connected. Next you will: learn the rest of the terminal UI.

Using Desktop instead? The same steps are in Work in a chat.

Open Haarness in your project

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:

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

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):

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

Permissions 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 has the details.

Review what changed

/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

/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:

haarness -s <id>

Or reopen the last chat in the current folder:

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

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 covers choosing a model, JSON output and permissions.

Next