Agent Mode

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

How It Works

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

Your message goes to the backend with your conversation history and project context.
The AI reasons about what to do — you see thinking blocks stream in real-time.
Tool calls dispatch — the AI requests actions like “read this file” or “write this component.” These execute locally on your machine.
Results return — your app sends tool results back. The AI continues with that information.
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

For the complete tool reference with all parameters, see Intelligent Tools.

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 for details.

Optimistic Concurrency

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

Read the file + compute a hash
Make the edit
Before writing, verify the hash hasn’t changed (nobody else modified the file)
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.

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.

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

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.
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.
Attach context when relevant. Drag a datasheet into the chat if you want the AI to implement a specific reference circuit.
Let the AI run checks. After edits, ask “Run ERC” or “Run DRC” to validate. The AI can then fix any issues it introduced.
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 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 — when you want answers without changes
Plan Mode — when the task needs research and approval
AI Modes Overview — comparing all three modes
Using Prompts — prompt writing tips
Version History — understanding the undo/rollback system

Getting Started

Core Concepts

Guides

What Agent Mode Does

When to Use Agent Mode

How It Works

The Activity Feed

Tool Execution

File Tools

Design Tools

Server-Side Tools

Multi-Tab Parallel Execution

Stopping and Connection Recovery

Stop

Network drops

Versioning and Undo

Optimistic Concurrency

Extended Thinking

Todo Tracking in Agent Mode

Example Prompts

Adding Components

Modifying Values

Routing

Validation

Manufacturing

Research + Edit

Tips for Effective Agent Mode Usage

Limitations

Next Steps

​What Agent Mode Does

​When to Use Agent Mode

​How It Works

​The Activity Feed

​Tool Execution

​File Tools

​Design Tools

​Server-Side Tools

​Multi-Tab Parallel Execution

​Stopping and Connection Recovery

​Stop

​Network drops

​Versioning and Undo

​Optimistic Concurrency

​Extended Thinking

​Todo Tracking in Agent Mode

​Example Prompts

​Adding Components

​Modifying Values

​Routing

​Validation

​Manufacturing

​Research + Edit

​Tips for Effective Agent Mode Usage

​Limitations

​Next Steps

What Agent Mode Does

When to Use Agent Mode

How It Works

The Activity Feed

Tool Execution

File Tools

Design Tools

Server-Side Tools

Multi-Tab Parallel Execution

Stopping and Connection Recovery

Stop

Network drops

Versioning and Undo

Optimistic Concurrency

Extended Thinking

Todo Tracking in Agent Mode

Example Prompts

Adding Components

Modifying Values

Routing

Validation

Manufacturing

Research + Edit

Tips for Effective Agent Mode Usage

Limitations

Next Steps