Questions and answers

What people ask about buddylist, by topic. The landing page 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.

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 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, OpenCode and Hermes.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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, 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 and the MSN look.

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