> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modaal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your agent

> Modaal orchestrates a coding agent that writes your Swift code. Start instantly with the built-in free preview, then connect your own agent — Claude, Codex, Gemini, Copilot, Cursor and more — using a subscription you already pay for.

<Info>
  Modaal is the **orchestrator**; the **agent** is the model that actually writes your code. Every new project starts on Modaal's built-in **free preview** agent so you can try things immediately. When you're ready, connect your own agent — it's almost always **cheaper than paying per-API-call**, and you can **switch any time**.
</Info>

## Why connect your own agent?

<CardGroup cols={3}>
  <Card title="Use a plan you already have" icon="wallet">
    Already subscribed to Claude, ChatGPT/Codex, Gemini, or Copilot? Sign in and Modaal runs on that plan — no separate API bill.
  </Card>

  <Card title="More capable models" icon="rocket">
    The free preview is for trying Modaal out. Your own agent gives you the full, latest model and higher limits.
  </Card>

  <Card title="Switch any time" icon="arrows-rotate">
    Connect several agents and flip the default whenever you like. Your project doesn't change — only who writes the code.
  </Card>
</CardGroup>

***

## Open Agent settings

Click your **profile avatar** in the top-right corner to open the **User Menu**, then choose **Agent settings**.

<Frame caption="User Menu → Agent settings.">
  <img src="https://mintcdn.com/modaal/XlqSOtN6T6Qmy64H/images/connect-agent-0-user-menu.png?fit=max&auto=format&n=XlqSOtN6T6Qmy64H&q=85&s=38f101ae490bb6ed09791c710797e223" alt="Modaal User Menu with Agent settings highlighted" style={{ width: "300px" }} width="224" height="366" data-path="images/connect-agent-0-user-menu.png" />
</Frame>

This opens **Choose your build agent** — the list of every agent Modaal can drive. Each row shows the agent, its current status, and one action button. **Show more** reveals the full catalog.

<Frame caption="The agent list. Each row has a status (“Not installed”, “Installed · Not signed in”, “Signed in…”) and one action.">
  <img src="https://mintcdn.com/modaal/XlqSOtN6T6Qmy64H/images/connect-agent-1-choose.png?fit=max&auto=format&n=XlqSOtN6T6Qmy64H&q=85&s=eb3b8056fd87ec2fe17dc2047a152210" alt="Choose your build agent panel listing available agents" style={{ width: "600px" }} width="731" height="658" data-path="images/connect-agent-1-choose.png" />
</Frame>

***

## The two kinds of action button

Before you start, it helps to know that agents differ along two simple axes — and those two axes are all that change the buttons you see.

### 1. Getting the agent onto your Mac — **Get** vs **Check**

| Button    | What it means                                                                                                                                         | Examples                                                                           |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| **Get**   | Modaal can **install** this agent's CLI for you (via `npm` or Homebrew). Just click it.                                                               | Claude Agent, Codex CLI, Gemini CLI, GitHub Copilot CLI, OpenCode, and most others |
| **Check** | Modaal **can't install** this one — you install its CLI yourself, then Modaal detects it. Click **Check** (or **Re-check**) once it's on your system. | Cursor, OpenHands, Mistral Vibe                                                    |

### 2. Signing in — **in-app login** vs **Login via Terminal**

After the agent is installed, you sign in with your own account:

* **In-app login** — Modaal signs you in directly. For some agents (like Claude) you'll pick *how* to sign in from a small menu; for others it starts straight away. These agents can also be **re-authenticated** later from the **⋯** menu.
* **Login via Terminal** — Modaal opens a Terminal window where the agent's own CLI handles sign-in. Once you've signed in there, come back and click **Re-check** so Modaal picks it up.

<Tip>
  You don't need to memorize which agent is which — the panel always shows the right button for the right step. The rest of this guide walks the happy path with **Claude Agent**.
</Tip>

***

## Connect an agent, step by step

<Steps>
  <Step title="Install it — click Get (or Check)">
    Find the agent you want and click **Get**. Modaal downloads and installs its CLI for you (this can take a minute). If the agent shows **Check** instead, install its CLI yourself first, then click **Check**.

    When it's installed, the status changes to **Installed · Not signed in** and the button becomes **Login**.

    <Frame caption="After installing, the agent shows “Installed · Not signed in” and a Login button.">
      <img src="https://mintcdn.com/modaal/XlqSOtN6T6Qmy64H/images/connect-agent-2-installed.png?fit=max&auto=format&n=XlqSOtN6T6Qmy64H&q=85&s=4f1e95ed29a61e006b6ee98c9bf8d965" alt="Claude Agent installed but not signed in" style={{ width: "600px" }} width="758" height="681" data-path="images/connect-agent-2-installed.png" />
    </Frame>
  </Step>

  <Step title="Sign in with your subscription — click Login">
    Click **Login**. If the agent offers more than one way to sign in, pick the one that matches your plan. For **Claude Agent** you choose between:

    * **Claude Subscription** — use your Claude (Pro/Max) subscription.
    * **Anthropic Console** — use Anthropic Console (API usage billing).

    Pick **Claude Subscription** to use the plan you already pay for. A browser window opens for you to sign in and approve access.

    <Frame caption="Choose how to sign in. Pick “Claude Subscription” to use a plan you already have.">
      <img src="https://mintcdn.com/modaal/XlqSOtN6T6Qmy64H/images/connect-agent-3-login-methods.png?fit=max&auto=format&n=XlqSOtN6T6Qmy64H&q=85&s=ee565897ff9a409c0961aebde30cf3c2" alt="Login method menu showing Claude Subscription and Anthropic Console" style={{ width: "600px" }} width="725" height="654" data-path="images/connect-agent-3-login-methods.png" />
    </Frame>

    <Note>
      Agents that use **Login via Terminal** instead open a Terminal window — sign in there, then return to Modaal and click **Re-check**.
    </Note>
  </Step>

  <Step title="Make it your default — click Use as default">
    Once you're signed in, the status shows **Signed in as \<your account>** and the button becomes **Use as default**. Click it to tell Modaal to write your code with this agent.

    <Frame caption="Signed in. Click “Use as default” to start building with this agent.">
      <img src="https://mintcdn.com/modaal/XlqSOtN6T6Qmy64H/images/connect-agent-4-signed-in.png?fit=max&auto=format&n=XlqSOtN6T6Qmy64H&q=85&s=bb52f462eace26f4a85ab80dc9b1bfa4" alt="Claude Agent signed in with Use as default button" style={{ width: "600px" }} width="726" height="654" data-path="images/connect-agent-4-signed-in.png" />
    </Frame>

    The button turns into a **✓ Default** marker. That's it — your next message in Modaal is handled by your own agent.
  </Step>
</Steps>

***

## Switching agents later

You can connect as many agents as you like and switch the default whenever you want — open **Agent settings** again and click **Use as default** on a different one. Useful tools live in each row's **⋯** menu:

* **Re-check** — re-detect status (use this after signing in via Terminal, or installing a **Check** agent).
* **Re-authenticate** — sign in again (in-app login agents).
* **Log out** — sign out (only some agents support this in-app; otherwise sign out from the agent's own CLI).
* **Show details** — expand the row for version and account info.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="The agent replies with “API Error: 401” or “Invalid authentication credentials”">
    This almost always means your sign-in token has gone stale — a **transient** issue, not a broken account. The fix is to refresh your credentials:

    1. Open **Agent settings** (User Menu → **Agent settings**).
    2. On your agent's row, open the **⋯** menu and click **Re-authenticate** if it's there, then sign in again.
    3. If there's no **Re-authenticate** option, click **Log out** and then **Login** again. For agents that sign in through Terminal, sign out and back in via the agent's own CLI, then click **Re-check**.

    Once you've signed back in, retry your request. Other transient auth errors (403, “token expired”, “unauthorized”) clear the same way.
  </Accordion>

  <Accordion title="It still shows “Installed · Not signed in” after I signed in">
    Click **Re-check** on the agent's row — sign-ins done in a Terminal window are only picked up on re-check. If it still won't catch, **Log out** / **Login** again from Agent settings.
  </Accordion>

  <Accordion title="My agent isn't in the list">
    Click **Show more** to reveal the full catalog. If it's a **Check**-type agent (e.g. Cursor), install its CLI yourself first, then click **Check** so Modaal can detect it.
  </Accordion>
</AccordionGroup>

<Tip>
  Connecting your own agent is the single biggest upgrade over the free preview — you get the full model on a plan you already own. If you're not subscribed to any, **Claude**, **ChatGPT/Codex**, **Gemini**, and **GitHub Copilot** all have plans that work well with Modaal.
</Tip>

<Note>
  **Need help?** Join our [community on Discord](https://discord.gg/KyQzDXxgU3).
</Note>