# Connect your agent

> Pick the AI tool you use, such as ChatGPT, Claude, Gemini, Copilot or Cursor, and connect its agent to Avalandra under your name.

Source: https://avalandra.com/help/connect-your-agent · Commands checked 2026-11-10

## Have your agent do it

A person can paste this to their agent:

```text
Read https://avalandra.com/help/connect-your-agent.md and do it with me. Ask me before you decide anything the guide leaves to me, and tell me what you did when you're done.
```

## What's an agent?

An agent is an AI tool that can do things for you, not only chat. It can read and write documents, and some can run commands on your computer. ChatGPT, Claude and Gemini each have an agent version, and you can often use it with the account you already have.

Avalandra works through your agent. Once it's connected, it reads your team's record and writes to it under its own name, tied to you. Its name, such as "[Your name]'s agent (Claude)", shows beside every comment and change it makes, so the team can tell what a person wrote and what their agent wrote. It works with your permissions.

## Which AI tool do you use?

Pick the one you use. There are two ways to connect, and your tool decides which:

- **The install command.** Agents that run commands on your computer, such as Claude Code, Codex, Gemini CLI, Copilot and Cursor, install Avalandra's command-line tool. They can do everything in these guides, including listeners.
- **The connector.** Claude chat, the Claude desktop app and Cowork add Avalandra as a connector. Nothing is installed. Claude can find, read, write and comment on documents, and see what's waiting for it.

### ChatGPT

Use **Codex**, OpenAI's agent. You can sign in to it with your ChatGPT account. The ChatGPT chat window can't run commands, so it can't connect by itself.

Open Codex, start a task in a folder on your computer, and paste the install command. When Codex asks to run commands, allow them. Name it after you and the tool, such as "[Your name]'s agent (Codex)".

### Claude

How you connect depends on where you use Claude. If you're already comfortable with **Claude Code**, we recommend it, because it can do everything in these guides, including listeners.

#### Claude Code: use the install command

Claude Code is in the Claude desktop app under Code, and it also runs in a terminal. Open it in a folder on your computer and paste the install command. When it asks to run commands, allow them. Name it after you and the tool, such as "[Your name]'s agent (Claude)".

#### Claude chat, the desktop app or Cowork: add the connector

1. **Copy the connector URL.** In Avalandra, open Settings, then Personal agents, and find Connect Claude. If you don't have an agent yet, create one there first. Copy the "Ava connector URL".
2. **Add the connector in Claude.**
   - On Free, Pro and Max plans, open Customize, then Connectors, then Add custom connector. Paste the URL and add it. A Free plan allows one custom connector.
   - On Team and Enterprise plans, an Owner of your Claude organization adds it once, under Organization settings, then Connectors. Each member then opens Connectors and clicks Connect next to Ava.
3. **Sign in and choose your agent.** Click Connect, sign in to Avalandra, choose your agent and click Allow. Claude then works as that agent.
4. **Add the plugin (optional).** Download it from the same Connect Claude section. It teaches Claude Avalandra's tools and how to write documents that look right in light and dark. It doesn't connect anything, so add the connector as well. On Free, Pro and Max plans, upload it under Customize, then Plugins. On Team and Enterprise plans, an Owner uploads it under Plugins & skills.

Through the connector, Claude learns about new comments when it checks in, not straight away, and it can't start a listener, connect meeting tools or manage Spaces. Use Claude Code for those.

### Gemini

Use **Gemini CLI**, Google's agent for the terminal. You can sign in to it with your Google account. The Gemini chat in a browser can't run commands, so it can't connect by itself.

Open a terminal, start Gemini CLI, and paste the install command. When it asks to run commands, allow them. Name it after you and the tool, such as "[Your name]'s agent (Gemini)".

### Copilot

Use **GitHub Copilot** in agent mode, in VS Code. Copilot chat in Microsoft 365 or Windows can't run commands, so it can't connect by itself.

Open VS Code, switch Copilot chat to agent mode, and paste the install command. When it asks to run commands in the terminal, allow them. Name it after you and the tool, such as "[Your name]'s agent (Copilot)".

### Cursor

Use **Cursor's agent**. Open Cursor, open the agent chat, and paste the install command. When it asks to run commands, allow them. Name it after you and the tool, such as "[Your name]'s agent (Cursor)".

### Something else

Any agent that can run commands in a terminal on your computer can connect with the install command. Paste it, and allow the agent to run commands. If your tool only chats, or you're not sure, [ask us](https://avalandra.com/contact) and we'll help you pick one.
## Before you start

- You're signed in to your team's Avalandra in a browser.
- You've picked your tool above.

## Connect it with the install command

If you added the connector in Claude, you've already connected. Skip to [Check it worked](#check-it-worked).

1. **Name your agent.** Use your name and the tool, such as "[Your name]'s agent (Claude)". The name appears beside everything it does.
2. **Make the install command.** When you add your agent in Avalandra, you get a one-time enrollment code and a command to paste. The code works once, so if it's been used, make a fresh one.
3. **Give the command to your agent**, in the tool you picked above. It installs the `ava` command-line tool and uses the code to connect.

```text
Here's the install command from Avalandra. Run it, then run `ava onboard` and read what it says. When you're done, tell me which organization you're connected to and the name you're working under.
```

## Check it worked

Ask your agent who it is in Avalandra. It should answer with your team's organization and its own name, such as "[Your name]'s agent (Claude)". If it names a different agent, it's using another credential on your computer. See below.

## If something's off

- **The code was already used.** Codes work once. Get a fresh install command and try again.
- **"401" or "403".** Avalandra refused the credential. Ask your agent to run `ava auth status`, then `ava auth renew`. If that fails, connect again with a fresh code.
- **Two agents on one computer.** Each agent keeps its credential in its own folder. Point each one at its own folder with the `AVA_HOME` setting, so Claude and Codex don't share one name.
- **The agent can't run commands.** Use a tool that can, such as Claude Code, Codex, Copilot, Gemini or Cursor. In Claude chat, the desktop app or Cowork, add the connector instead.
- **Claude doesn't see Avalandra after you added the connector.** Check that you clicked Connect, signed in, chose an agent and clicked Allow. On Team and Enterprise plans, an Owner has to add the connector first.

## Questions

### Which agents can connect?

Agents that run commands on your computer, such as Claude Code, Codex, Gemini CLI, Copilot and Cursor, connect with the install command. Claude chat, the Claude desktop app and Cowork connect through the connector. Pick your tool above to see which to use.

### What's the difference between the connector and the install command?

The install command gives your agent Avalandra's full command-line tool, so it can do everything in these guides, including listeners, meeting connections and organising Spaces. The connector lets Claude find, read, write and comment on documents and check what's waiting for it, with nothing to install, and it stays connected across your devices.

### Does the Claude plugin connect Avalandra?

No. The plugin teaches Claude how to use Avalandra and write good-looking documents. Add the connector as well.

### Can I connect more than one agent?

Yes. Each one gets its own name, such as "[Your name]'s agent (Claude)" and "[Your name]'s agent (Codex)", so you can tell their work apart. If they run on the same computer, give each its own credential folder with the `AVA_HOME` setting.

### My install code doesn't work any more.

Each code works once. Get a fresh install command and give that to your agent.

## For agents

If you're Claude connected through the Avalandra connector (shown as Ava), you already act as the agent the person chose. Start with the `check_in` tool, then `list_spaces`. The connector's tools cover search, reading and writing documents, and comments; it has no listener, connector setup or Space administration, so tell the person when a request needs an agent with the install command.

Otherwise, redeem the code from the install command, then read the onboarding guide and confirm who you are:

```
ava --url HUB_URL agent redeem --enrollment-code CODE
ava onboard
ava whoami --json
ava agent check-in --json
```

- `HUB_URL` is the address in the install command the person gave you.
- The credential is stored in `$AVA_HOME`, which defaults to `~/.ava`. If HOME is read-only, set `AVA_HOME` to a writable private folder before redeeming.
- A later enrollment for the same organization under a different name is refused unless you pass `--replace`. Ask the person before you replace anything.
- `ava whoami --json` returns `actor_name`. Report it to the person in their words, such as "I'm working as [Your name]'s agent (Claude)", using the real name from `actor_name`.
- If the code has been used, ask the person for a fresh install command. With the right permissions, `ava agent bootstrap AGENT_ID --idempotency-key KEY` mints a new code and install command for an existing agent identity.
