Adding an external agent

Business Summary: Adding an external agent puts a coding agent you already pay for, such as Claude Code or Codex, one @ away in every chat. You pick the agent, the computer it runs on, and the folder it works in.

Step-by-step

1. Open Profile → External agents and choose Add external agent. You can also choose Add an agent from the @ menu in any chat, or the + next to the search bar at the top of the app.
2. Search for the agent you use, for example Claude Code, Codex or Cursor CLI, and select it. Each entry shows the agent's logo and a one-line description.
3. Check the Name and purpose. The name is what you type after @ in chat, so keep it short. The purpose reminds you and your team what you hand this agent.
4. Under Runs on, choose the computer. Harmony tells you whether it found the agent installed there, for example Found on This Mac: Codex 0.146.0.
5. Optionally set a Working directory: the folder the agent starts in, such as your project's repository. Leave it empty to use the computer's home folder.
6. Choose how the agent signs in under Authentication, for example Claude plan or ChatGPT plan. This only records your choice; the actual sign-in happens in the agent on your computer.
7. Choose Add agent. The agent appears in your list with a status, and in the @ menu of every chat.

flowchart LR
  Pick[Pick the agent]
  Name[Name and purpose]
  Where[Choose the computer]
  Folder[Working directory]
  Done[Agent appears in the @ menu]

  Pick --> Name --> Where --> Folder --> Done

How this fits in Harmony

An external agent is a saved setup: which agent program to start, on which computer, in which folder. When you ask it in chat, Harmony sends your request to that computer and the runner starts the agent there. The agent uses whatever sign-in it already has on that computer, so if Claude Code works when you type claude in Terminal, it works from Harmony too.

You can add the same kind of agent more than once. For example, add Claude Code (web app) pointing at one repository and Claude Code (API) pointing at another, so each starts in the right folder.

What you'll see

Each agent in your list shows a status:

Active agents also appear as small logos next to the search bar at the top of the app.

Agents you can add

Harmony lists dozens of coding agents with their logos, including Claude Code, Codex, Gemini CLI, Cursor CLI, GitHub Copilot CLI, Cline, Roo Code, Kilo Code, OpenCode, Aider, Amp, Goose, Factory Droid, Qwen Code, Kimi CLI, Grok CLI, Junie, Warp, OpenHands, Devin and Jules. If yours is not listed, choose Another CLI agent and enter the command that starts it, or MCP server or API endpoint for agents you reach over the network.

Example scenario

Lena already uses Codex in her terminal with her ChatGPT plan. In Profile → External agents she adds Codex, names it Codex, sets Runs on to her MacBook, and sets the working directory to her team's checkout-service repository. Harmony shows Found on Lenas-MacBook: codex-cli 0.146.0. From then on she types @Codex in the Checkout workstream to hand it work.

FAQs {#faqs}

Q: The agent says Not installed. What do I do? A: Install the agent on that computer the way its maker describes, then open Terminal and sign in to it once. The runner checks again when it restarts; reconnect the computer with Pair again if the status does not update.

Q: Can I change the folder or computer later? A: Yes. Choose Manage on the agent, change the settings, and choose Save.

Q: Can I pause an agent without deleting it? A: Yes. Use the switch on the agent's row. Paused agents keep their settings.

Q: Does Harmony store my agent's API key? A: No. Keys and sign-ins stay on the computer that runs the agent. See Privacy and security for external agents.

Q: Can I add the same agent twice? A: Yes. Give each a different name and working directory, for example one per repository.