# Settings

**buddylist > Settings...** in the Mac menu bar, **Tools > Settings...** in the contact list or a conversation, or **⌘,** on Mac (**Ctrl+,** on Windows and Linux) opens the Settings window: what the app does on the left, and under **Projects** what each of your projects is set up with. **Tools > Project settings...** in a conversation opens it at that contact's project, and **Edit teams...** beside a new contact's **Team** opens it at [Teams](#personal).

There is no OK button. A switch or a box is saved as soon as you change it, and the bar at the bottom says so, or says why it could not be kept.

## Personal

**General.** The [look](professional-look.md) and the theme, sounds, the lines that say what a contact does, [suggested replies](conversations.md) under a question, whether a click on a link opens it [beside the conversation](browser-tab.md), showing you as Away while the computer sits idle, anonymous usage counts, and the keys for [voice clips](voice-clips.md).

**Quick messages.** The [quick messages](conversations.md) you put in the message box with a click, offered in every conversation. Each has a name, which is what the list under the conversation calls it, and the words it puts in the box. A message left without a name is called by its first words. **Save as quick message...** in that list adds the one you are writing.

**Teams.** The agents that join a new contact's conversation with it. See [Roles and teams](group-conversations.md#roles-and-teams).

- **Roles** are the agents. Each has a name, a service, a model and an effort level, when it answers, whether it is **Read only**, and its **Rules**: what it is told, after what its project tells every agent. The app starts with a **Reviewer**.
- **Teams** are roles that join together. Tick the roles a team has. **Add a Contact** offers them under **Team**. The app starts with **With a reviewer**.
- A change to a role holds from its agents' next conversation. A role you take out leaves its teams, and the agents made from it answer as any guest does.

**Models.** Which models **Add a Contact** offers for each service.

**Git.** How the branches and worktrees of your contacts are made. See [The contact list](contact-list.md) for what a worktree is.

- **Branch prefix** goes in front of every branch made for a contact, such as `safa/feature`.
- **Name a branch after the work** renames a made-up branch, such as `shop-2`, after the first thing you ask its contact to do. Turned off, the branch keeps the name it was made with, and **Add a Contact** shows that name in the branch field.
- **Remove worktrees with contacts** decides whether "Also remove its worktree" starts out ticked when you delete a contact. Deleting still asks.
- **Delete the branch with its worktree** deletes the branch on this computer when a contact's worktree is removed. What was pushed stays on the remote. Commits that were only on that branch are gone.
- **Archive contacts once their pull request is merged** puts a contact away as soon as GitHub says its pull request was merged, as **Archive** next to the **Merged** tag does. One that is working or waiting for you finishes first. Only a merge the app sees while it is open counts: a contact whose pull request was merged while buddylist was closed, or one you restore, keeps its **Continue** and **Archive** buttons.

## Agents & environment

**Agents.** The program each service runs, and whether it is there and signed in, as the [welcome wizard](welcome-wizard.md) checks it. Claude Code comes with the app. Codex, Gemini, OpenCode and Hermes are the ones your shell finds. Type a path, or press **Browse...**, to run another one. **Use default** goes back. A change holds from a contact's next conversation.

**Accounts.** The Claude accounts your contacts answer in: your own login, and the ones you added. **Use** puts one in use, and **Switch without asking** lets a conversation go on in the next one when the account in use reaches a limit. See [Accounts](accounts.md).

**Environment.** Variables that the scripts, terminals and agents of every project are started with.

- **Variables** have a name and a value. The value is kept out of sight until you press the eye. It is kept in the app's own data as plain text, like a `.env` file. Nothing is written into your repository.
- **Env files** are read each time something is started, so a change in the file needs no restart of the app. They are written like a `.env` file: `NAME=value`, with or without `export` and quotes. A variable typed in wins over one from a file.

## Projects

A project is a git repository, in whichever worktree, or a folder outside any. It shows here once a contact works on it. Every contact working on a project shares what is set here.

### Git

- **Start new worktrees from** picks the branch a new contact's branch starts from. Left alone, that is the remote's main line. The branch is fetched first.
- **Remote** picks where that branch, and a pull request you start a contact from, is fetched from. It is `origin` unless you choose another.

A folder outside a repository has no worktrees, so it has nothing to pick here.

### Environment

The same as the app's own, for this project alone. A project's variable wins over one of the same name set for every project.

- An env file that is not named in full, such as `.env.local`, is looked for in the contact's own folder. Each worktree then reads its own copy. One the worktree's branch has in git is read from the main checkout instead, in the same folder: the branch can be someone else's pull request, and what its file sets would reach the agent.
- These are always there:

| Variable                   | What it is                                                                                 |
| -------------------------- | ------------------------------------------------------------------------------------------ |
| `PORT`, `BUDDYLIST_PORT`   | the contact's own port, for scripts started with **Run** and the setup and cleanup scripts |
| `BUDDYLIST_ROOT_PATH`      | the project's main checkout                                                                |
| `BUDDYLIST_WORKSPACE_PATH` | the contact's folder                                                                       |

### Scripts

- **Setup script** runs in a contact's new worktree, right after it is made, and from the **Setup** tab beside a conversation whenever you press **Run setup**. Use it to install what the project needs, or to link it from the main checkout: `ln -s "$BUDDYLIST_ROOT_PATH/node_modules" node_modules`. The contact is there at once and the script runs behind it. Its conversation has a line for it, with what it prints, as for a [run](run-button.md). A worktree made from a [pull request](contact-list.md) is the exception: the script would run the pull request's code, so it waits until you press **Run setup**, and the conversation's line says so.
- **Cleanup script** runs in a contact's worktree before the worktree is removed. It gets two minutes. If it fails, the worktree is removed all the same and you are told what it printed last.
- **Run scripts** are what the [Run button](run-button.md) starts. The first one is the button's own. The others are under **Tools** in the conversation, and each can run next to the others.

Scripts run through your shell, in the contact's folder, with the project's environment. On Windows that is Git Bash, so they are written as on a Mac or Linux (see [Run](run-button.md)).

### Actions

What the contacts working on this project are told on top of what you type.

- **Every conversation** is told to a contact before anything else in each new conversation. Claude and Codex get it with their instructions. Gemini, OpenCode and Hermes get it with your first message.
- **Create PR** is added to what the **Create PR** button asks for.
- **Review comments** is added to the comments you send from the **Changes** tab: your own on a line, and a reviewer's.

### Misc

- **Main checkout** and **Worktrees** show where the project and its contacts' worktrees are. **Open** shows the folder.
- **Preview URLs** say where a run is looked at. The first is the link in the run's line, and the others follow it. Left empty, that is `http://localhost:$PORT`. An address can name the contact's port as a script would: `$PORT`, `${PORT}`, and `$((PORT + 1))` for the ports after it.
- **Files to copy** are the files git does not keep that every new worktree needs, such as `.env*`. One pattern on each line. They are copied from the main checkout when a contact's worktree is made. The line under the box says which files match right now.

Good to know:

- The settings are kept in the app's own data, under the project. Nothing is written into your repository.
- A change to a script or a variable holds from the next time something is started. What is running is not touched.
- The browser preview has no Settings window.