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

# AI Modes

> Trace has three AI interaction modes — Ask, Agent, and Plan. Each is designed for a different stage of the design process. Choose the right one, or let Trace choose for you.

## Overview

Every message you send in Trace is handled by one of three modes. Each mode has different capabilities, different levels of autonomy, and different guardrails. You can pick a mode explicitly using the mode selector in the chat panel, or let Trace's classifier choose automatically based on your message.

```mermaid theme={null}
flowchart LR
  You["Your message"] --> Classifier["Classifier"]
  Classifier --> Ask["Ask Mode"]
  Classifier --> Agent["Agent Mode"]
  Classifier --> Plan["Plan Mode"]
  Ask --> ReadOnly["Read-only analysis"]
  Agent --> Edits["Direct file edits"]
  Plan --> Approval["Plan → Approve → Execute"]
```

## The Three Modes

|                                 | Ask                                                                           | Agent                                                                       | Plan                                                                        |
| ------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **What it does**                | Answers questions and analyzes your design. Read-only — never modifies files. | Makes direct edits to your schematic or PCB. Reads, writes, runs checks.    | Researches, creates a step-by-step plan, waits for approval, then executes. |
| **Best for**                    | Learning, debugging, getting explanations, comparing approaches               | Adding components, routing traces, generating files, quick targeted changes | Complex multi-step tasks, full circuit design, board-level redesigns        |
| **Modifies files?**             | Never                                                                         | Yes                                                                         | Yes (after approval)                                                        |
| **Available on Free plan?**     | Yes (unlimited)                                                               | While free agent credits last                                               | While free agent credits last                                               |
| **Available on Web Dashboard?** | Yes                                                                           | No (requires desktop — files are local)                                     | No (requires desktop — files are local)                                     |
| **Thinking visible?**           | Sometimes                                                                     | Yes (for complex reasoning)                                                 | Yes (all phases)                                                            |
| **Todo tracking?**              | No                                                                            | Sometimes (complex tasks)                                                   | Always (from the approved plan)                                             |

## How the Classifier Works

When you send a message without explicitly selecting a mode, Trace's backend classifier analyzes your request and picks the appropriate mode:

* **Ask** is selected for questions, explanations, comparisons, and anything that doesn't require changing files. Examples: "What does this resistor do?", "Compare LDO vs buck converter for my use case."
* **Agent** is selected for direct, bounded edits. Examples: "Add a 100nF cap to U1 VDD", "Route the power traces", "Generate Gerbers."
* **Plan** is selected for complex, multi-step tasks that benefit from research and user review before execution. Examples: "Design a USB-C PD charging circuit", "Lay out this entire power supply section."

The classifier is a hint — it makes its best guess, but you can always override by selecting a mode manually before sending your message.

<Tip>
  If you're not sure which mode to use, just type your message and let the classifier decide. It gets it right the vast majority of the time. You can always switch modes and resend if the result isn't what you expected.
</Tip>

## When to Use Each Mode

### Use Ask Mode when you want to learn or understand

* "How does this circuit work?"
* "What capacitor value do I need for this LDO's output?"
* "Is there a better alternative to the STM32F103?"
* "Explain the DRC violation on net /VCC"
* "What's the thermal resistance of this package?"

Ask mode is free, unlimited, and available everywhere — desktop app and web dashboard. It uses the same AI backend and research tools (web search, parts search, datasheet parsing) as the other modes, but it will never touch your files.

[Full Ask Mode guide →](/guides/ask-mode)

### Use Agent Mode when you want the AI to make changes

* "Add a TVS diode on the USB data lines"
* "Change R3 to 4.7k"
* "Route the SPI bus traces"
* "Run DRC and fix any violations"
* "Generate Gerber and drill files"

Agent mode reads your design, makes edits, runs validation, and streams results in real-time. Every edit is versioned — you can undo any change with one click.

[Full Agent Mode guide →](/guides/agent-mode)

### Use Plan Mode when the task is complex

* "Design a 5V 3A buck converter with input protection"
* "Lay out the board with proper decoupling and power distribution"
* "Redesign the analog front-end for better noise performance"
* "Create a 4-layer stackup with controlled impedance for USB 2.0"

Plan mode researches your task, asks clarifying questions, presents a plan with Mermaid diagrams and component tables, and only executes after you approve. You stay in control of complex, high-stakes changes.

[Full Plan Mode guide →](/guides/plan-mode)

## Mode Availability by Plan

| Plan        | Ask       | Agent                         | Plan                          |
| ----------- | --------- | ----------------------------- | ----------------------------- |
| Free        | Unlimited | While free agent credits last | While free agent credits last |
| Pro / Ultra | Unlimited | Within usage limits           | Within usage limits           |
| On-Demand   | Unlimited | Within credit balance         | Within credit balance         |
| Enterprise  | Unlimited | Custom limits                 | Custom limits                 |

New accounts receive a one-time grant of [free agent credits](/guides/billing#free-agent-credits) (\~\$5, never expire, plus a small monthly top-up) that unlock Agent and Plan on the Free plan. Accounts on the legacy 14-day trial keep full access until the trial naturally expires.

When your monthly usage is exhausted, your credit balance reaches zero, or your free agent credits run out, Agent and Plan modes are disabled until the next billing cycle, credit purchase, or monthly free top-up. Ask mode always remains available.

## Switching Modes

The mode selector is in the chat panel, next to the message input. Click it to choose a mode before sending your message.

You can also switch modes mid-conversation. Starting in Ask mode to understand a circuit, then switching to Agent to make changes is a common workflow:

1. **Ask:** "How does the current limiting work on this LED driver?"
2. **Ask:** "What happens if I increase R4 to 1k?"
3. **Agent:** "Change R4 to 1k and add a test point on that net"

Each message is handled by whatever mode is selected when you send it.

## Next Steps

* [Ask Mode](/guides/ask-mode) — full guide to read-only AI analysis
* [Agent Mode](/guides/agent-mode) — full guide to AI-driven edits
* [Plan Mode](/guides/plan-mode) — full guide to multi-step planning workflows
* [Using Prompts](/guides/ai-prompts) — tips for writing effective prompts in any mode
* [Billing & Plans](/guides/billing) — plan limits and usage details