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

# Agent Mode

> Agent mode gives the AI direct access to edit your schematic and PCB files. It reads, writes, runs checks, and streams results in real-time — with every change versioned and undoable.

## What Agent Mode Does

Agent mode is the primary working mode in Trace. When you ask the AI to make a change — add a component, route a trace, fix a DRC violation, generate manufacturing files — it executes the change directly on your design files.

The AI can:

* Read your schematic and PCB files
* Make targeted edits (add/remove/modify components, connections, traces)
* Run ERC and DRC checks
* Generate Gerber, drill, and position files
* Search for symbols and footprints
* Take screenshots for visual analysis
* Create matched length groups
* Annotate reference designators
* Route traces (quick routing or advanced cloud layout)

Every edit is versioned automatically. If you don't like a change, click undo on the message and you're back to where you started.

## When to Use Agent Mode

Agent mode is best for bounded, concrete tasks:

| Good for Agent Mode                         | Better suited for Plan Mode                        |
| ------------------------------------------- | -------------------------------------------------- |
| "Add a 100nF cap between VDD and GND on U1" | "Design a complete power supply section"           |
| "Route the SPI bus"                         | "Lay out the entire board from scratch"            |
| "Fix the DRC violation on net /CLK"         | "Redesign the analog front-end for better noise"   |
| "Generate Gerbers and drill files"          | "Create a 4-layer stackup with impedance control"  |
| "Change R3 from 10k to 4.7k"                | "Optimize all resistor values for this LED driver" |

If your task has more than 3-4 steps or would benefit from research before execution, consider [Plan Mode](/guides/plan-mode) instead.

## How It Works

When you send a message in Agent mode, the following happens:

```mermaid theme={null}
sequenceDiagram
  participant You
  participant App as Desktop App
  participant Server as Backend
  participant AI as Trace AI

  You->>App: "Add ESD protection to USB data lines"
  App->>Server: POST /chat/stream (SSE)
  Server->>AI: Analyze request + design context
  AI-->>Server: Reasoning + tool calls
  Server-->>App: Stream (thinking, status, tool calls)
  App->>App: Execute tools locally
  App->>Server: Tool results
  AI-->>Server: Continue reasoning or respond
  Server-->>App: Final response + done
  App->>App: Convert .trace_sch → .kicad_sch
  App-->>You: See changes in editor
```

1. **Your message** goes to the backend with your conversation history and project context.
2. **The AI reasons** about what to do — you see thinking blocks stream in real-time.
3. **Tool calls dispatch** — the AI requests actions like "read this file" or "write this component." These execute locally on your machine.
4. **Results return** — your app sends tool results back. The AI continues with that information.
5. **Changes sync** — after all edits, the `.trace_sch` converts to `.kicad_sch` and your editor reloads.

## The Activity Feed

As the AI works, you see an interleaved activity timeline in the chat:

* **Status messages** — Friendly updates like "Reading schematic...", "Adding component...", "Running ERC..."
* **Thinking blocks** — The AI's reasoning process, collapsible for review
* **Text responses** — Explanations of what was done and why
* **Tool activity** — Which files are being read or modified

This gives you full visibility into what the AI is doing at every step.

## Tool Execution

Tools execute locally on your machine — your design files never leave your computer. The server only sees tool results (e.g., "file written successfully" or "DRC found 3 violations").

### File Tools

| Tool                | What it does                                    |
| ------------------- | ----------------------------------------------- |
| `read_file`         | Read a schematic, PCB, or project file          |
| `write`             | Create or overwrite a file                      |
| `search_replace`    | Make targeted edits using exact string matching |
| `grep`              | Search for patterns across project files        |
| `list_dir`          | List files and directories                      |
| `delete_trace_file` | Delete a file (with confirmation)               |

### Design Tools

| Tool                   | What it does                                      |
| ---------------------- | ------------------------------------------------- |
| `run_erc`              | Run Electrical Rule Check                         |
| `run_drc`              | Run Design Rule Check                             |
| `take_snapshot`        | Capture a visual screenshot for analysis          |
| `annotate_schematic`   | Auto-annotate reference designators               |
| `autoroute`            | Run the autorouter (quick or advanced engine)     |
| `match_lengths`        | Create matched length groups for high-speed buses |
| `generate_gerbers`     | Generate manufacturing Gerber files               |
| `generate_drill_files` | Generate Excellon drill files                     |

### Server-Side Tools

These run on the backend (not your machine) and are also available in Agent mode:

| Tool                                   | What it does                                          |
| -------------------------------------- | ----------------------------------------------------- |
| `search_web`                           | Find datasheets, reference designs, application notes |
| `search_parts_nexar`                   | Query distributors for availability and pricing       |
| `parse_datasheet`                      | Extract structured data from PDF datasheets           |
| `search_symbols` / `search_footprints` | Find library components by description                |

<Note>
  For the complete tool reference with all parameters, see [Intelligent Tools](/concepts/intelligent-tools#ai-tool-reference).
</Note>

## Multi-Tab Parallel Execution

Each chat tab is an independent execution unit. You can:

* Run Agent mode in one tab while asking questions in another
* Have two Agent tabs making edits to different parts of the design simultaneously
* Start a long routing task in one tab and continue working in another

Tabs don't interfere with each other — each has its own streaming state, conversation history, and backend client. File-level locking prevents conflicts when two tabs try to edit the same file.

## Stopping and Connection Recovery

### Stop

Click **Stop** (the ■ button on the composer or on your latest message) at any time. Stop halts generation on the server too — the AI doesn't keep working (or billing) in the background after you stop it. What happens next depends on how far the response got:

* **Stopped before anything streamed** — the round trip is cancelled cleanly and your prompt is restored to the input box, ready to edit and re-send.
* **Stopped after partial output** — the partial response (text, thinking, completed tool work) is kept in the conversation, so nothing the AI already did is thrown away.

### Network drops

If your connection drops mid-response, the AI keeps working server-side and Trace automatically reconnects, continuing the response where it left off. If automatic reconnection fails, a **Resume** banner appears — click it to continue the same response without re-running your prompt or re-doing completed work.

## Versioning and Undo

Every edit the AI makes is automatically versioned:

* **Local history** — git commits in `.history/` (works offline)
* **Cloud sync** — saved to Trace's backend for cross-device access
* **Per-message undo** — click the undo button on any assistant message to restore the state before that message's edits

Rolling back is non-destructive — it creates a new version, so you can always go forward again. See [Version History](/guides/version-history) for details.

## Optimistic Concurrency

When the AI edits a file, it uses a hash-based safety mechanism:

1. Read the file + compute a hash
2. Make the edit
3. Before writing, verify the hash hasn't changed (nobody else modified the file)
4. If the hash matches, write succeeds. If not, the AI retries with the updated content.

This prevents data loss when you and the AI (or two AI tabs) edit the same file around the same time.

## Extended Thinking

For complex Agent tasks, the AI shows its reasoning in collapsible thinking blocks:

* How it's analyzing your design
* What tradeoffs it's considering
* Why it chose a particular approach
* What constraints it's working around

Thinking blocks auto-collapse as the AI moves to the next step. Click to expand and read the full reasoning.

<Tip>
  Extended thinking uses a 10,000-token budget per reasoning step. This allows deep analysis of complex design decisions even in Agent mode — you don't need Plan mode just to get thoughtful reasoning.
</Tip>

## Todo Tracking in Agent Mode

For multi-step Agent tasks, the AI may create a todo checklist to organize its approach:

* The todo widget appears in the chat panel
* Items update in real-time as the AI completes each step
* You can see exactly where the AI is in the process

This happens automatically for complex requests — you don't need to ask for it.

## Example Prompts

### Adding Components

```
Add TVS diodes (PESD5V0S2BT) on the USB D+ and D- lines for ESD protection.
Place them close to the USB connector.
```

### Modifying Values

```
Change all bulk decoupling caps on the power rail from 10uF to 22uF.
Keep the same 0805 package.
```

### Routing

```
Route the I2C bus (SDA, SCL) with 0.2mm traces.
Keep them parallel and add 4.7k pull-ups to 3.3V if not already present.
```

### Validation

```
Run DRC on the board. For any clearance violations, increase the
trace spacing to meet the minimum. Don't move any components.
```

### Manufacturing

```
Generate Gerber files, drill files, and pick-and-place position file.
Package everything into a ZIP ready for JLCPCB submission.
```

### Research + Edit

```
Check if the ADS1115IDGSR is in stock at LCSC. If yes, add it to
the schematic with proper decoupling and I2C pull-ups connected to
the STM32's I2C1 peripheral.
```

## Tips for Effective Agent Mode Usage

1. **Be specific about what you want changed.** "Fix it" is vague. "Change R4 to 4.7k because the LED current is too high" gives the AI clear intent.
2. **One task per message for precision.** For complex changes, break them into steps. This makes undo granular — you can roll back one step without losing others.
3. **Attach context when relevant.** Drag a datasheet into the chat if you want the AI to implement a specific reference circuit.
4. **Let the AI run checks.** After edits, ask "Run ERC" or "Run DRC" to validate. The AI can then fix any issues it introduced.
5. **Use multi-tab for parallel work.** Route traces in one tab while reviewing the schematic in another.

## Limitations

* Agent mode requires the desktop application (files must be local)
* Not available on the Free plan (Ask mode is free; Agent requires Pro/Ultra/On-Demand)
* Complex multi-step tasks may produce better results in [Plan Mode](/guides/plan-mode) where the AI researches and plans before executing
* PCB version rollback is limited — version restore is fully implemented in the schematic editor but has reduced functionality in PCBnew

## Next Steps

* [Ask Mode](/guides/ask-mode) — when you want answers without changes
* [Plan Mode](/guides/plan-mode) — when the task needs research and approval
* [AI Modes Overview](/concepts/ai-modes) — comparing all three modes
* [Using Prompts](/guides/ai-prompts) — prompt writing tips
* [Version History](/guides/version-history) — understanding the undo/rollback system