# Questions and answers

What people ask about buddylist, by topic. The [landing page](https://buddylist.dev/#faq) answers the first questions: what buddylist is, whether it is free, which agents you install yourself, which systems it runs on, and what it sends about you.

## Getting started

### Is this just a chat window with a retro theme?

No. Each conversation runs a real Claude Code, Codex, Gemini, OpenCode or Hermes session, with the same agent loop, tools and settings as `claude`, `codex`, `gemini`, `opencode` or `hermes` in your terminal. It can read your project, run commands and edit files.

### How do I chat with Codex?

Choose **Codex** as the **Service** in **Add a Contact**. Codex is not bundled, so install the Codex CLI first with `npm install -g @openai/codex` and run `codex login`. It uses the same login, `config.toml`, `AGENTS.md` and MCP servers as `codex` in your terminal. Codex contacts have their own Mode menu, and **Activities** has `/compact`, `/review` and your Codex skills. They have no plan approval. More in the [Codex guide](codex.md).

### How do I chat with Gemini, OpenCode or Hermes?

Choose **Gemini**, **OpenCode** or **Hermes** as the **Service** in **Add a Contact**. None is bundled. For Gemini, install Gemini CLI 0.33 or newer with `npm install -g @google/gemini-cli` and run `gemini` once to sign in. For OpenCode, run `npm install -g opencode-ai` and `opencode auth login`. For Hermes, install [Hermes Agent](https://hermes-agent.nousresearch.com) and choose a provider with `hermes model`. Each uses the same settings, commands and MCP servers as in your terminal, and has its own Mode menu. More in the guides to [Gemini](gemini.md), [OpenCode](opencode.md) and [Hermes](hermes.md).

## Code and GitHub

### Is there a terminal in the app?

Yes. **Terminal** in a conversation's toolbar, or ⌘J, opens your own shell in that contact's folder, beside the conversation. It is a real terminal, so `vim`, `htop`, colours and Ctrl+C work as they do in Terminal. The **+** after the tabs opens another one, each in a tab you can rename and drag into another order. Putting the terminal away keeps its shells running, and closing the window closes nothing: a terminal belongs to its contact. ⌘F, or Ctrl+Shift+F on Windows and Linux, finds text in its scrollback. The agent doesn't see what you type or what is printed. More in the [terminal guide](terminal.md).

### Can an agent open terminals for me?

A Claude contact can. Say "open three terminals", or "a terminal for the dev server and one for the tests", and each gets a tab beside the conversation, with the name you gave it. Ask for "two terminals running claude" and the command is typed into each one once its shell is up. You are asked first when a command is to run, and shown the command. It is typed once: the agent can't type into a terminal afterwards, and isn't told what the command prints. Codex, Gemini, OpenCode and Hermes can't do this yet.

### Can I see what an agent changed?

Yes. Every edit in the conversation has a **Show changes** link. For everything at once, open the **Changes** tab beside the conversation with **Changes** in the toolbar or ⇧⌘G. It lists the commits the branch made and every file that differs from the project's main line, committed or not, with the lines it gained and lost, as a list and as a tree. Click a commit for only its files, or **Uncommitted changes** for what changed since the last commit. Click a file for its diff, with numbered lines and the changed words marked, click a line, or drag over several, to comment on them, and mark a file as **Viewed**. In a wide pane the files stand beside the diffs, and their edge drags them wider or narrower. The **⋯** at the top shows the diffs side by side, wraps long lines or lets them scroll, lists the tests and generated files after the rest, and opens or closes every diff at once. While the branch has a pull request, your reviewers' threads stand under their lines, to send to the agent, answer or resolve. The tab never stages, commits or undoes anything. To read any file, not only a changed one, the **All files** tab next to it shows the folder as a tree, and opens a file in a tab of its own.

### Can an agent open a pull request for me?

Yes. **Create PR** in the conversation's toolbar asks the contact to commit what is left, push the branch and open the pull request with the GitHub CLI, and it asks before it runs anything, as its mode says. The button then turns into **View PR**, with a mark that is red while a check fails, amber while they run and green once they have all passed. Its **▾** shows the checks beside the conversation, failing ones first, and turns **Auto-merge** on or off: GitHub then merges the pull request by itself once what it requires has passed. Where the repository requires nothing, buddylist merges it itself once its checks pass, while the app is open. Once it is merged or closed, **Continue** moves the same contact to a fresh branch from the project's main line, **Archive** puts it away and **Delete** removes it, after asking. **Create PR manually** opens GitHub's own page for it instead.

### How does it know about my pull requests?

It asks the GitHub CLI. Install `gh` and click **Connect to GitHub** under your name once. A contact whose branch has a pull request then wears tags at the end of its row that say how it stands: **Merged**, **Conflict**, a count such as **2 failing**, **Running**, **Passed** or **Closed**. Click the tags to open the pull request on GitHub. The one for its checks shows them beside the conversation instead, and **Conflict** asks the agent to resolve the conflicts. A toast tells you when checks start failing or have all passed, and the line under your picture counts the pull requests waiting for your review. The **Checks** tab beside a conversation lists its pull request's checks, the failing ones first, with the step that failed and its errors. **Send to chat** hands a failed one to the agent to fix; with several failures, **Send all to chat** sends them together in one message. **Re-run failed** starts them over. A merge on GitHub shows within a minute. Apart from Auto-merge and Re-run failed, the app only reads, and without `gh` all of it is left out.

### Can I look at my app without leaving the conversation?

Yes. **Browser** in the toolbar, or ⇧⌘B, opens a web page in a tab beside the conversation: type `localhost:3000` or just `3000`, or right-click a link in the conversation and choose **Open beside the conversation**. A dev server that reloads on a change reloads there too. The **⋯** at the end of the page's bar shows it at a phone's or tablet's size, opens an HTML file from your computer, and can make a click on a link in a reply open it there. The camera on the bar takes a screenshot of the page to draw on, with a pen, boxes, arrows and text, and puts it in the message box. Otherwise the page can't reach the app, your files or the agent, and the agent doesn't see it. More in the [browser tab guide](browser-tab.md).

### Can I run my dev server from a conversation?

Yes. **Run** in a conversation's toolbar starts your project's own command in that contact's folder. The first time it asks for the command and suggests one, such as the `dev` script of your `package.json`. It can be a few lines, run one after the other until one fails, or a script file of the project that **Choose file...** in the same dialog picks. Each contact gets a port of its own in `PORT`, so several contacts on one project can each run a dev server at once. The conversation shows what was started, a link to `localhost` and the output. The agent is not told, and **Stop Run** stops everything the command started. More in the [Run button guide](run-button.md).

### How do I add a project that is on GitHub?

Choose **Add project** in the contact list's **...** menu. **Open GitHub project...** clones a repository: type its address or `owner/name`, or pick one of your own from a list. **Open project...** picks a folder that is already on your computer, and **Quick start...** starts a new project with a git repository and a first commit, and a private repository on GitHub if you leave that box ticked. Each ends in **Add a Contact** with the folder filled in. Listing and making repositories needs the GitHub CLI; cloning by address works without it.

### Can I start an agent on a GitHub issue or pull request?

Yes. **Add a Contact** has a **Start from a GitHub issue or PR** field: pick one of the project's open ones from its list, or type a number or paste a link. An issue names the contact after its title, and the branch after its number and title. A pull request checks out its own branch, also from a fork, so what the contact pushes goes to the pull request. The title, text and link wait in the message box as a draft, and nothing is sent until you press Enter. It needs the GitHub CLI, and the app only reads from GitHub.

### What runs when I start an agent on someone else's pull request?

Nothing the pull request brings, until you say so. Its contact works in a worktree of its own, and the project's setup script waits there, since installing runs a package's own scripts: **Run setup** in the **Setup** tab starts it once you have looked the changes over. In that worktree Claude Code takes the project's settings from your main checkout, so hooks, allow rules and MCP servers the pull request adds don't run. Codex, OpenCode and Hermes don't start what the branch sets up either, and Gemini trusts none of the worktrees unless you tell it to. The agent can still run the branch's code, such as its tests, as on any branch.

## Working with agents

### Can two agents work on one repository without undoing each other's work?

Yes. Every contact you add in a git repository works in its own git worktree in `~/.buddylist/worktrees/`, on a new branch, so the folder you picked is never touched. For another agent on the same project, point at the project in the list and click the **+** at the end of its line, or right-click one of its contacts and choose **New contact in this project**. Press Enter and the branch is named after the first thing you ask for, in a few words from Claude, or type a name of your own. The new contact keeps the service, model and mode of the first. Files git doesn't track, such as `node_modules` and `.env`, are not copied. Deleting the contact can remove its worktree too, and the branch and its commits always stay. In a folder that is not a git repository, contacts work in the folder itself. To ask another agent about the very same folder instead, open a chat tab: ⇧⌘A, or the **+** over the To: line, starts a chat there with any agent, as a tab over the conversation.

### Can I choose which model an agent uses?

Yes. Pick a model in **Add a Contact**, or click the model badge under a conversation to switch later. The list is searchable and takes any model by its exact name, and **Add models...** chooses which ones it offers. Claude Code and Codex are asked for their own lists, so new models show up by themselves. The same badge sets how hard the model thinks, for the models that take a level. Both are remembered for the contact, and nothing is written to your Claude Code or Codex settings. **Default** leaves the model to your own settings for that service. On a model that has fast mode, Opus today, it turns that on too, with a ⚡ on the badge: faster answers from the same model, at a higher price.

### Can the agents decide how hard to think?

Yes. Tick **Let Claude decide** at the bottom of a contact's effort menu and it picks its own level for every message you send. First it replies with a level and a few words on why, then it answers on that level. In a group conversation, **Tools > Effort > Let the agents decide** works the same way: before anyone answers, one agent names a level for everyone about to answer, such as `@Claude(high) @Codex(low)`. A level you choose yourself holds until the agents pick again. Gemini, OpenCode and Hermes have no effort levels.

### What happens when an agent makes a plan?

In plan mode, Claude writes a plan and waits for your answer before it changes anything. The plan opens in a pane beside the conversation, and the window grows to make room for it. Each plan has a tab: approve it, or choose **No, keep planning** and say what should change. The conversation keeps a **View plan** link, and **File > View a plan** lists every plan and how you answered it. Codex, Gemini, OpenCode and Hermes have no plans to approve.

### Can I change a message I already sent?

Yes, to a Claude contact. Point at the message for a row under it: **Rewind to this message**, **Edit** and **Copy**. Rewind takes the conversation back to just before it without sending anything, so Claude forgets the message and everything after it, as `/rewind` does in a terminal, and its words go back in the message box. **Edit** does the same once you send the new version, and **Esc** leaves everything as it was. Files Claude changed stay as they are. Messages in a group conversation and slash commands can't be rewound. To try another way without losing this one, **Fork chat from here** under a reply makes a new chat that goes on from there. A message you send while an agent works waits, greyed out, until it is read: **Send now** stops the turn so the agent reads it at once, and **Cancel** takes it back.

### Can another agent finish the work if I reach a limit?

When a provider reports a usage limit, **Invite another agent** opens the invitation picker. Choose an agent from another provider to join the same conversation and folder. Its first turn gets a recap of what was said, and its own login and limits apply. On an unfinished checklist, **Continue with...** sends the remaining to-dos to the agent you choose and asks it to inspect existing changes before carrying on. Nothing switches providers automatically. More in the [accounts guide](accounts.md#continuing-with-another-provider).

### What are subagents?

A Claude contact often hands part of a job to a subagent, an agent of its own that works beside it and comes back with a report. The **Subagents** tab beside the conversation lists them: what each one is doing right now, how long it has been at work and its report once it is back. **Stop** ends one subagent and lets Claude carry on with the rest. The commands and watchers Claude leaves running are not subagents: the **Background** tab lists those. Codex, Gemini, OpenCode and Hermes don't say what their subagents do. More in the [subagents guide](subagents.md).

### Can an agent check back later on its own?

A Claude contact can. Say "keep an eye on CI and tell me when it's green", "look at the deploy again in 10 minutes", or type `/loop`. Claude says how often it will check back, and so does the status bar. When a check-in is due, Claude answers it without you sending anything, and "stop checking" ends them. Check-ins last while buddylist is open, and one that repeats ends by itself after 7 days. Codex, Gemini, OpenCode and Hermes can't do this. More in the [check-ins guide](check-ins.md).

## Day to day

### Can I use more than one Claude account?

Yes. **Tools > Settings... > Accounts** adds another Claude login, such as a personal one beside your work one, through Claude's sign-in page in your browser. Personal and team accounts can share an email address; choose the organization during sign-in. **Use** there, or **Switch account...** under the usage meter in a conversation, puts one in use for every Claude contact. When the account in use reaches its session or weekly limit, the conversation asks to switch to the next one and sends your message again from there, with everything said so far. **Always allow** switches without asking from then on. Every account shares your Claude Code settings, `CLAUDE.md`, skills and plugins, and switching leaves `claude` in your terminal using your own login. **Disconnect** on that login signs it out in both places; **Remove** signs out and forgets an added account. More in the [accounts guide](accounts.md).

### Is there a keyboard shortcut to find contacts and actions?

Press **⌘K** on Mac or **Ctrl+K** on Windows and Linux in the contact list or a chat. The command palette searches contacts, conversation previews, the files of a chat's folder and the current window's menu actions. Type a name or a few words, use the arrow keys and Enter to choose, or Esc to close it. Past conversations open in message history, where **Continue** resumes them. More in the [command palette guide](contact-list.md#command-palette).

### Can I change the keyboard shortcuts?

Yes. **Settings > Shortcuts** has the keys for the command palette, the contact list and Quick send from any app, adding a contact, the terminal, the tabs beside a chat, invitations and voice clips. Click a box and press the keys you want. Keys another shortcut has, or that every app keeps, such as Copy and Paste, are turned down, and **Use default** puts one back. More in the [settings guide](settings.md#personal).

### Can I send a message while I am in another app?

Yes. **Control+Option+S** on Mac, **Ctrl+Alt+S** on Linux or **Ctrl+Alt+Shift+S** on Windows opens Quick send for the contact and chat tab you last viewed. It shows the recipients and folder before you send. Enter sends, Shift+Enter adds a line, and Esc closes it while keeping your draft. **Quick send to last contact** in the menu-bar or tray menu works too. More in the [quick send guide](contact-list.md#quick-send).

### Can I save messages I use often?

Yes. The speech-balloon button under a conversation lists **Quick messages**. Choosing one puts its words at the caret for you to edit and send. **Save as quick message...** keeps what you are writing, and **Settings > Quick messages** lets you name, edit or remove saved messages. The list is shared across conversations. More in the [conversations guide](conversations.md).

### Can I see how much my agents have spent?

**Contacts > View spending...** shows reported costs in US dollars for today, this week and this month, with a breakdown by contact. Archived contacts count too. These are estimates from retained message history, not your bill or subscription balance. Some agents, including Codex, do not report dollar costs, and deleted history no longer counts. More in the [spending guide](contact-list.md#spending).

### Can my personal message show the song I am playing?

On Mac, click your name in the contact list and turn on **Show what I'm listening to**. Spotify or Apple Music's song title and artist replace your personal message while music plays. Your saved message comes back when playback stops or you turn the option off. This is optional and available only on Mac. More in the [music status guide](contact-list.md#music-in-your-personal-message).

### How do voice clips work?

Hold **F2**, say your message and let go. What you said is typed into the message box, so you can fix it before you press Enter. Your voice is turned into text on your computer by whisper.cpp, and the recording never leaves it. Neither whisper.cpp nor its model is bundled: run whisper.cpp and download a model; the guide has setup instructions for your platform. **Tools > Voice clips** changes the shortcut, and can send what you said as soon as you stop talking, without waiting for Enter. More in the [voice clips guide](voice-clips.md).

### Can I stop it from interrupting me?

Yes. Set your own status to **Busy** or **On The Phone** and the toasts, sounds, nudges and dock bounce stop, while the dock icon and the menu bar keep counting. **Appear Offline** hides the counts too. Nothing is answered for you: when you go back **Online**, every contact still waiting asks again. The app also shows you as Away after five minutes without input.

### Can I find an old conversation again?

Yes. Starting a new chat moves the conversation to message history instead of deleting it. Right-click a contact and choose **View message history** to browse and search its past conversations, save one as Markdown or delete it. **Continue**, or a double-click, makes one the current conversation again, and the agent picks up the session it had; one from your terminal is copied first, so the terminal's own stays as it was. The newest 50 per contact are kept, on your computer. To look through every contact at once, choose **Contacts > View all message history...** for every contact's conversations in one window, newest first, or type in the contact list's search box: from two characters on, it also lists the contacts whose conversations contain your text.

### What if I'm done with a project for now?

Archive its contact. Right-click it and choose **Archive contact**: it stops, its conversation window closes and it moves to an **Archived** section that stays folded. Its message history, folder and worktree are kept. The sidebar beside a conversation has the same folded Archived section: click a contact there to read its history. **Restore contact** brings it back as it was, and its conversation picks up where it left off. Turn on **Archive contacts once their pull request is merged** in Settings and it happens by itself, or right-click the project and choose **Archive all contacts** to put all of its contacts away at once. For the contacts you use most, **Add to favorites** lists them at the top.

### Can I use my own emoticons and winks?

Yes. Drop pictures into `emoticons`, `winks` or `pictures` inside the `pack` folder in [your app data folder](getting-started.md#where-your-data-lives), and restart the app. GIF, PNG, WebP and JPEG files work. Put an audio file with the same name next to a wink and it plays with sound. The app comes with its own smileys and 15 classic winks, and a file with the same name replaces the bundled one. Make sure you have the right to use what you add.

## Looks, privacy and updates

### Does it have to look like 2005?

No. **Tools > Look > Professional**, in the contact list or a conversation, takes the costume off: flat panes, your system's own type, line icons, slate by day and ink at night, and the messenger's blue as its one colour. Every button, menu and key stays where it was. **Messenger** brings the MSN look back, and a theme such as Olive Green gives either look its colour. More in the guides to the [professional look](professional-look.md) and the [MSN look](msn-look.md).

### Is there a dark theme?

Yes. **Tools > Theme** in the contact list or a conversation has **Light**, **Dark** and **Match system**. Dark is Luna at night: the title bars keep their blue and everything under them goes navy. XP's other colour schemes are there too, each by day and at night: **Olive Green**, **Silver**, **Royale** and **Pink**. Every window changes at once, and web pages in the Browser tab follow along.

### Where are my conversations stored?

On your computer: `~/Library/Application Support/buddylist/` on Mac, `%APPDATA%\buddylist\` on Windows, or `~/.config/buddylist/` on Linux (under `XDG_CONFIG_HOME` when set). Each agent keeps its own session transcripts, such as Claude Code's in `~/.claude/`.