llms.txt
# buddylist
> Chat with Claude Code, Codex, Gemini and OpenCode in a retro MSN Messenger buddy list. Group chats for coding agents on Mac, Windows and Linux.
## Features
- **Four agents, one list**: Pick Claude Code, Codex, Gemini or OpenCode when you add a contact. Claude Code is built in. The others run the CLI on your computer, with the same login, settings and MCP servers.
- **A contact for every project**: Add a project folder and it shows up as a buddy. Double-click it to open a conversation there. The list starts out grouped by project, and its ... menu groups it by status, service or your own groups, filters it to one project and sorts it. Whoever is waiting for you comes first, favorites stay on top, a pin keeps a contact or a project first, and archived contacts fold away.
- **Status at a glance**: Online means ready. Busy shows what the agent is working on. Away means it is waiting for you to approve something, and it moves to the top of the list, under Waiting for you, until you answer.
- **Pull requests in sight**: A contact whose branch has a pull request wears tags at the end of its row: Merged, Conflict, 2 failing, Running or Passed. A toast tells you when checks start failing or have all passed, and a line under your picture counts the pull requests waiting for your review.
- **A branch for every agent**: Every contact in a git repository works in its own worktree and branch, so your folder stays as it is and two agents never change each other's files. Click the + on a project, or press ⌘N, for another agent on it.
- **Invitations, not prompts**: When an agent wants to run a command or edit a file, you get an invitation: Accept, Always allow or Decline. Each tool call appears as a line in the conversation, with its output or its changes one click away, and the screenshots it took to check its work right under it. Questions come one at a time, like slides, and a question at the end of a reply comes with a few answers to click.
- **Nudge to interrupt**: A nudge shakes the window and stops the agent, and so does Stop, in Send's place while it works. A message sent meanwhile waits, greyed out: Send now has it read at once, Cancel takes it back. When an agent needs you, it nudges you back.
- **What it is doing, right now**: A line under the newest one says what the agent is up to and for how long: thinking, editing retry.js, running npm test. When it works through a list of steps, the list stays above that line until it is all done.
- **Reply to part of it**: Select words in a message and click Reply: they are quoted in the message box, with room for your answer under them. Quote a few parts to answer them in one message.
- **Rewind, or fork**: Rewind to a message you sent Claude, or Edit it, and the conversation goes back to just before it, as /rewind does. Fork chat from here, under a reply, tries another way in a new chat.
- **The whole toolbox**: Permission modes, slash commands and @ files that complete as you type, output styles, and Send Files for pictures, files and folders.
- **Everyone answers, in turn or at once**: A message without a mention goes to all of them, in turn, top to bottom: drag a name up or down to change who answers first. Or all at once, picked under Replies.
- **Mention who should answer**: Type @ and a list of everyone in the conversation opens. Only the agents you mention answer, in the order you mention them. A slash command goes to the host.
- **They hand work to each other**: An agent passes the turn the way you do, with an @mention. They take up to six turns on one message of yours, then wait for you. A nudge stops them all.
- **They pick their own effort**: Give the goal, and the agents decide how hard each of them should think. Before anyone answers, one of them runs a quick effort check: a level for everyone about to answer, and a few words on why. A hand-over can carry a level too, and the badges follow.
- **Anyone, on any service**: Invite a contact you have, or make one right there with the + in Invite: pick its service and model and it joins, without landing on your contact list.
- **One folder, a session each**: Everyone works in the host's folder, each in a session of its own. Taking turns, only one works at any moment, so two never change a file at once.
- **A mode, model and effort each**: Every agent keeps its own mode, model and effort level, listed under its name in the Agents tab beside the conversation. Click one to change it for that agent alone.
- **You know who is asking**: Every line says whose it is. Invitations and toasts name the agent that wants something, and the status bar says who is typing and who is waiting for you.
- **Pause one**: The pause button on an agent's row keeps it in the conversation and listening, but it answers only when you @mention it. Resume it and it catches up on what it missed.
- **Rename anyone**: Double-click a name in the To: line or the Agents tab and type another, for agents you invited too. In your contact list, F2 does the same.
- **Plans beside the chat**: In plan mode, each plan gets a tab. Approve it there, or say what should change.
- **Files, changes and checks**: Diffs beside a tree of the files, comments on any lines, and failed checks to hand to the agent.
- **A browser in the window**: Your dev server or any link in a tab, at a phone's or a tablet's size if you like.
- **Subagents and background tasks**: What each subagent is doing, and the commands Claude left running, each with a Stop.
- **The session at a glance**: The account, folder, branch, context and MCP servers, a click away from changing.
- **Terminals, Setup and Run**: Your shell with ⌘J, the project's setup and Run, and terminals Claude opens for you.
- **Start from an issue**: Add a contact from a GitHub issue or pull request: it names the branch and drafts the first message.
- **Create PR, then carry on**: One click commits, pushes and opens the pull request, and Continue starts the contact on a fresh branch.
- **Run your project**: Run starts your dev server on a port of the contact's own, so two agents can each run one at once.
- **The model for the job**: A badge under the chat sets a contact's model, effort and fast mode, or lets Claude pick a level.
- **Context and limits**: Bars in the status bar show the context window and your plan's session and weekly limits.
- **Check-ins**: "Tell me when CI is green." Claude checks back on its own while the app is open.
- **More than one Claude account**: When one account reaches its limit, the conversation goes on in the next, with all that was said.
- **Voice clips**: Hold F2 and talk. whisper.cpp types it on your computer, and you send it once it reads right.
- **More chats, one folder**: New chat tab opens another chat in the same folder, with any agent, as a tab over the first.
- **Jump straight to it**: ⌘K, or Ctrl+K on Windows and Linux, finds contacts, past conversations and menu actions.
- **A message from anywhere**: Quick send opens a small message box for your last viewed contact, while you are in another app.
- **Pick up unfinished work**: Invite another provider when a limit is reached, and pass remaining to-dos on with Continue with...
## Questions
### What is buddylist?
buddylist is a free desktop app for chatting with the Claude Code, Codex, Gemini and OpenCode coding agents through an interface styled after MSN Messenger 7.5. Every project folder is a contact in a buddy list, and every conversation is a real agent session that can read the project, run commands and edit files.
### Is buddylist free?
Yes. buddylist is free to download and use. Each agent runs on your own account, as it does in your terminal: a Claude Code login or an Anthropic API key for Claude Code, and the CLI's own sign-in for Codex, Gemini and OpenCode, so what they do counts against those plans.
### When can I download it?
You can download buddylist for Mac, Windows or Linux. Mac builds use Apple Silicon; Windows and Linux builds use x64. See the first-launch instructions, or try the live demo in your browser with scripted replies.
### Is this just a chat window with a retro theme?
No. Each conversation runs a real Claude Code, Codex, Gemini or OpenCode session, with the same agent loop, tools and settings as `claude`, `codex`, `gemini` or `opencode` in your terminal. It can read your project, run commands and edit files.
### Do I need to install the agents myself?
Not Claude Code: it comes with the app. Codex, Gemini and OpenCode are not bundled, so install the ones you want. Each agent signs in the way it does in your terminal. For Claude Code that is a Claude Code login on this computer, or an Anthropic API key.
### 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 or OpenCode?
Choose Gemini or OpenCode as the Service in Add a Contact. Neither 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`. Both use the same settings, commands and MCP servers as in your terminal, and each has its own Mode menu. More in the guides to Gemini and OpenCode.
### Is there a Windows, Linux or Intel Mac version?
Windows x64 and Linux x64 downloads are in the download section. Intel Mac and ARM Windows/Linux installers are not provided.
### 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. 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 and OpenCode 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. 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 hands a failed one to the agent to fix, and 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 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 and OpenCode 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.
### Can several agents work together in one conversation?
Yes. Click Invite in a conversation and pick another contact, whichever service it uses, or click the + there to make a new one with its service and model. Invite as many as you like. Everyone in the conversation works in its folder and answers in turn, top to bottom in the Agents tab beside the conversation, each seeing what was said and done before. Drag a name up or down to change who answers first, or pick All at once under Replies and they all start right away. Type `@` and a list of everyone opens: only the ones you mention answer. An agent can hand over to another the same way, for up to six turns per message, and a slash command goes to the host alone. Pause one and it only answers when you mention it. Each agent has its own mode, model and effort level, and what any of them asks for arrives as an invitation that says who is asking. More in the group conversations guide.
### 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
