> ## 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.

# Agent mode

> The default mode for vly. Describe a change; the agent decides what to edit, plans implicitly, and writes code. Best for most everyday work.

export const PromptBlock = ({children, variant}) => <div className={`vly-prompt ${variant || ""}`}>{children}</div>;

Agent mode is the default workflow in vly. You describe what you want — anything from "make the buttons bigger" to "add Stripe subscription billing" — and the agent decides what files to touch, what schema to change, and what code to write. Plan and code happen as a single, fast cycle.

## When to use it

<CardGroup cols={2}>
  <Card title="✅ Most everyday edits" icon="check-circle">
    Adding a feature, fixing a bug, restyling, refactoring. If you're not sure which mode to use, start here.
  </Card>

  <Card title="✅ Multi-file changes" icon="files">
    Edits that touch the schema *and* a page *and* a component. The agent traces dependencies for you.
  </Card>

  <Card title="✅ When you trust the prompt" icon="thumbs-up">
    Your prompt is clear and the change feels low-risk. Skip the Plan-mode review step.
  </Card>

  <Card title="❌ Schema migrations on production" icon="x-circle">
    Use [Plan mode](/building/plan-mode) so you can review the migration before it runs.
  </Card>
</CardGroup>

## How it works

```mermaid theme={null}
sequenceDiagram
    participant You
    participant Agent
    participant Build

    You->>Agent: prompt
    Agent->>Agent: read project context
    Agent->>Agent: classify change<br/>(schema? page? component?)
    Agent->>Agent: write files (streaming)
    Agent->>Build: trigger build
    Build-->>Agent: type-check feedback
    Agent->>Agent: self-correct (up to 3 retries)
    Build-->>You: live preview URL
```

A few things worth noting:

* **The agent reads your full project context** before generating, not just snippets. It knows the schema, the auth model, your custom instructions, your design system.
* **Type-check failures auto-retry** up to three times. You only see the build that succeeded.
* **Conflict-free for files you've manually edited.** If you edited `components/Header.tsx` by hand and the agent decides to change it, the agent will respect your edits as the new starting point.

## Anatomy of a good agent-mode prompt

Three things make a prompt land cleanly:

<Steps>
  <Step title="Be concrete about the user-facing behavior">
    "Add a settings page where users can change their display name and avatar" beats "Add a settings page".
  </Step>

  <Step title="Mention scope">
    "Just for the logged-in user — admins shouldn't see anyone else's settings here."
  </Step>

  <Step title="Reference existing things by name">
    "Add a column to the existing `Tasks` table called `notes` (optional text)" beats "add a notes feature to tasks".
  </Step>
</Steps>

A worked example:

<PromptBlock variant="bad">
  Add a way for users to share things.
</PromptBlock>

<PromptBlock variant="good">
  Add a "Share" button to each task in the task list. Clicking it copies a link to the task to the clipboard. The link is `/share/{taskId}`. Anyone with the link can view the task (read-only) without signing in. Logged-in users on the same team can also edit it. Show a toast confirming the copy.
</PromptBlock>

The bad version forces the agent to guess at six decisions. The good version is unambiguous.

## Switching agents per prompt

Agent mode runs against your **default agent** (set in workspace settings), but you can override per-prompt:

<CardGroup cols={3}>
  <Card title="Claude Code" icon="brain">
    The default. Strong reasoning across many files. Best general-purpose pick.
  </Card>

  <Card title="OpenAI Codex" icon="terminal">
    Fast, surgical. Best on small, targeted changes (one file, one function).
  </Card>

  <Card title="Gemini CLI" icon="sparkles">
    Best for multi-file design work and schema modeling.
  </Card>
</CardGroup>

See [Choosing an agent](/features/agents/choosing-an-agent) for the full decision tree.

## What you can ask for

<Tabs>
  <Tab title="Add a feature">
    ```
    Add a "Favorites" feature to the task list. Each user can favorite tasks
    by clicking a star icon on each row. Favorited tasks appear in a separate
    "My Favorites" section at the top of the page, sorted by most recently
    favorited.
    ```
  </Tab>

  <Tab title="Refactor">
    ```
    Refactor the task list to use a shared `<TaskRow />` component instead of
    duplicating the markup. The component should accept the task object and
    render the title, due date, priority, and assignee avatar.
    ```
  </Tab>

  <Tab title="Schema change">
    ```
    Add an `archived` boolean field to the `tasks` table (default false). When
    true, the task doesn't show in the default list. Add an "Archive" action
    in the task menu that toggles this. Add a separate "Archived" view that
    lists only archived tasks, with an "Unarchive" action.
    ```
  </Tab>

  <Tab title="Integration">
    ```
    When a task is marked done, post a message to our team's Slack channel
    `#shipped` with the task title and who completed it. Use the Slack
    integration.
    ```
  </Tab>

  <Tab title="Performance fix">
    ```
    The dashboard is slow when there are 100+ tasks. Add pagination — show
    25 per page with prev/next buttons. Use a Convex paginated query.
    ```
  </Tab>
</Tabs>

## When the agent gets it wrong

The agent is good but not infallible. Common failure modes:

<AccordionGroup>
  <Accordion title="It misinterpreted the prompt" icon="message-square-x">
    Switch to [Plan mode](/building/plan-mode) so you see the plan before code is written. Often the misread is visible in the plan and you can correct it in one reply.
  </Accordion>

  <Accordion title="It made the change but broke something else" icon="alert-triangle">
    Roll back via [version history](/building/version-history) (one click). Then re-prompt with the additional constraint: "Same change, but don't break the existing `<Header />` layout."
  </Accordion>

  <Accordion title="It picked an integration you didn't want" icon="puzzle">
    Be explicit. "Use Resend for email (not SendGrid)" or "Use the existing Convex storage for files (not S3)."
  </Accordion>

  <Accordion title="It generated working code but it doesn't match your style" icon="palette">
    Add a [custom instruction](/building/custom-instructions) so this preference is global. Then re-prompt with "Refactor according to my custom instructions." Easier than fighting it every time.
  </Accordion>
</AccordionGroup>

## Tips

<Tip>
  **Iterate in small chunks.** Five small prompts beat one giant one. Easier to roll back, easier to reason about, easier for the agent to get right.
</Tip>

<Tip>
  **Reference your custom instructions explicitly when needed.** "As per my custom instructions, do X" is a valid prompt and surfaces relevant rules.
</Tip>

<Tip>
  **Use Plan mode for the first prompt of any project.** Once you trust the project's shape, drop back to Agent mode for incremental work.
</Tip>

## Related

<CardGroup cols={3}>
  <Card title="Plan mode" icon="workflow" href="/building/plan-mode">
    Same flow, with a review step before code is written.
  </Card>

  <Card title="Code mode" icon="code" href="/building/code-mode">
    Hand-edit when a prompt is overkill.
  </Card>

  <Card title="Iterating effectively" icon="repeat" href="/building/iterating">
    Patterns for making 50 small changes a day.
  </Card>
</CardGroup>


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