Skip to main content

Add an agent

An agent is a named working folder with a provider, model and effort choice. Start with a folder you already use with Codex or Claude Code, or create a new folder for a new agent.

In the app​

  1. Open Agents and choose Add agent.
  2. Enter a Name people will recognize.
  3. Choose the agent’s Folder on this computer.
  4. Choose its provider and any model or effort options offered by the installed provider inventory.
  5. Save the agent. It starts with a Native chats channel.

A folder can belong to only one saved agent. Its folder is fixed after registration; create another agent if you need another folder.

In the terminal​

For a new folder-based agent:

catalex agents add --name Helper --folder /absolute/agent-folder --agent claude
catalex agents list
catalex channels list

For an existing agent, first inspect the folder with the onboarding command:

catalex agents onboard --name Helper --folder /absolute/agent-folder --agent claude --isolation folder

Review its findings, then apply the integration and register the agent:

catalex agents onboard --name Helper --folder /absolute/agent-folder --agent claude --isolation folder --apply

Read catalex agents onboard --help for the installed release’s options. Without --apply, onboarding changes nothing. With it, onboarding integrates the folder’s instructions and settings and reports the files changed. Folder isolation is a Claude Code option that keeps the package’s settings and MCP servers separate from user-wide configuration. Keep an existing agent on its intended provider.

Verify the agent​

Open its Native chats channel and start a conversation. Ask something that requires its own instructions, files or tools. For example, ask a scheduling agent for the opening hours from its clinic tool. Check that the reply matches the source.

If the folder has a deliberate restriction, test that restriction too. A generic answer to “Who are you?” does not establish that the folder’s tools or rules loaded.

Once the native reply works, add a messaging channel.

Change or remove an agent​

Choose Configure agent on the agent’s page or card to edit its name, model and effort. Settings defaults apply to new agents; existing agents keep their choices. Model and effort changes apply from the next message; a provider change applies to new chats.

Deleting an agent keeps conversation history. Removing an agent used by a messaging app requires Relay to be running and leaves its messaging accounts available for another agent.