> ## Documentation Index
> Fetch the complete documentation index at: https://vlyai-1c28d863.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Choosing an agent

> When to pick Claude Code, OpenAI Codex, or Gemini CLI for any given prompt. The full decision tree.

Three agents, three sweet spots. This page is the decision tree.

## TL;DR

```mermaid theme={null}
flowchart TD
    A[New prompt]
    A --> B{How big is the change?}
    B -->|Single line / single file| C[OpenAI Codex]
    B -->|Multi-file feature| D{What kind?}
    D -->|Layout / design / schema| E[Gemini CLI]
    D -->|Refactor / logic| F[Claude Code]

    style C fill:#FFEDD5,stroke:#FF6600
    style E fill:#CFFAFE,stroke:#06B6D4
    style F fill:#EDE9FE,stroke:#6D28D9
```

If you're unsure, use **Claude Code** — the default. It handles all three cases competently; the others are optimizations.

## The decision tree

<Steps>
  <Step title="Is the change small? (One file, one function, one line.)">
    **Yes:** [OpenAI Codex](/features/agents/openai-codex). Faster, cheaper.
    **No:** continue.
  </Step>

  <Step title="Is the change primarily about layout, visual design, or schema modeling?">
    **Yes:** [Gemini CLI](/features/agents/gemini-cli). Stronger spatial intuition.
    **No:** continue.
  </Step>

  <Step title="Default to Claude Code">
    Multi-file refactors, complex logic, integrations, security-sensitive code — [Claude Code](/features/agents/claude-code) is the safe pick.
  </Step>
</Steps>

## Worked examples

| Prompt | Best agent | Why |
| - | - | - |
| "Fix the typo on the homepage" | Codex | Tiny |
| "Add Stripe subscription billing" | Claude Code | Multi-file, security-sensitive |
| "Redesign the dashboard with a sidebar" | Gemini | Layout-heavy |
| "Refactor the auth flow to use a state machine" | Claude Code | Logic refactor |
| "Make the avatar 2px larger" | Codex | Tiny |
| "Design a schema for a forum (categories, threads, posts, votes)" | Gemini | Schema modeling |
| "Add real-time presence to the comment editor" | Claude Code | Multi-file, careful state |
| "Move the brand color from inline Tailwind to design tokens" | Gemini | Multi-file design |
| "Add validation to the new-task form" | Codex | Single concern |
| "Add multi-tenancy to this single-tenant app" | Claude Code | Major architectural change |

## Switching mid-prompt

If you've started typing a prompt with one agent selected, switch the dropdown — your typed text stays. Submit with whichever agent fits.

## Workspace defaults

Set a workspace-wide default in [agent preferences](/features/agents/agent-preferences). Most users default to Claude Code and switch per prompt as needed.

## Comparison

<table className="vly-compare">
  <thead>
    <tr>
      <th>Agent</th>
      <th>Best for</th>
      <th>Speed</th>
      <th>Credits</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Claude Code</td>
      <td>Multi-file refactors, complex logic</td>
      <td>Standard</td>
      <td>Standard</td>
    </tr>

    <tr>
      <td>OpenAI Codex</td>
      <td>Tight, single-file changes</td>
      <td className="yes">\~1.5–2× faster</td>
      <td className="yes">Lower</td>
    </tr>

    <tr>
      <td>Gemini CLI</td>
      <td>Layout, design, schema</td>
      <td>Standard</td>
      <td>Standard</td>
    </tr>
  </tbody>
</table>

## Related

<CardGroup cols={3}>
  <Card title="Claude Code" icon="brain" href="/features/agents/claude-code">
    Deep dive.
  </Card>

  <Card title="Agent preferences" icon="settings" href="/features/agents/agent-preferences">
    Set defaults.
  </Card>

  <Card title="Fallback behavior" icon="shuffle" href="/features/agents/fallback-behavior">
    What happens if your agent is unavailable.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.