Skip to main content

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.

​
The Big Picture

Trace is a desktop PCB design app with an AI assistant built in. You work in a graphical schematic and PCB editor. The AI works alongside you — reading your design, making edits, searching for components, and running checks — all through a chat panel on the right side of the editor. The core idea: the AI edits structured text, you edit visually, and both interfaces stay in sync with the same design.

​
The File Format Pipeline

This is the key architectural decision that makes Trace possible.

​
Two formats, one design

Your project contains two representations of the same circuit:
FormatWho uses itWhat it looks like
.trace_sch / .trace_pcbThe AIStructured text designed for language models to read and edit precisely
.kicad_sch / .kicad_pcbYou (the editor)Standard KiCad s-expression format that the visual editor renders

​
How they stay in sync

When the AI edits a .trace_sch file, Trace automatically converts it to the corresponding .kicad_sch file. The visual editor then reloads and you see the change. This conversion is debounced (batched over 200ms) so rapid edits don’t cause flickering. The .kicad_sch / .kicad_pcb files are what you keep. They’re standard KiCad — open them in vanilla KiCad anytime. The .trace_sch / .trace_pcb files are an intermediate step, like compiled output. You never need to touch them directly.

​
Where Things Run

Trace splits work between your machine and a cloud backend. Your design files never leave your computer.
Runs on your machineRuns on the server
Visual editor (schematic + PCB)AI reasoning
File reading and writingWeb search
Design rule checks (DRC/ERC)Parts search (DigiKey, Mouser, LCSC)
Gerber/drill file generationDatasheet parsing
AutoroutingSymbol/footprint search
Format conversion (trace → kicad)Component availability checks
When the AI needs to read or edit your files, it sends a tool call back to the desktop app. The app executes the tool locally and returns the result. This means your schematic and PCB data stay on your machine — the server only sees the tool results you send back.

​
Three Modes

ModeWhat it doesWhen to use it
AskAnswers questions, analyzes your design, explains circuits. Read-only — no changes to your files.”What does this capacitor do?” or “Explain the power path.”
AgentMakes direct edits to your schematic or PCB. Reads files, writes changes, runs checks.”Add a 100nF decoupling cap to U1” or “Route all traces.”
PlanResearches, creates a step-by-step plan, waits for your approval, then executes.”Design a USB-C charging circuit” or any multi-step task.
You can pick a mode explicitly or let Trace choose based on your message.

​
What Happens When You Send a Message

Here’s the full lifecycle of a single chat interaction in Agent mode:
  1. You send a message — typed in the chat panel.
  2. Backend classifies — determines mode (ask/agent/plan) and whether research is needed.
  3. Research phase (if needed) — the server searches the web, queries distributors, parses datasheets in parallel. Results stream as a collapsible research card.
  4. AI reasons — the model analyzes your design context, conversation history, and research results.
  5. Tool calls stream back — the AI requests actions like “read this file” or “write this component.” These execute on your machine, not the server.
  6. Results return — your app sends tool results back. The AI continues reasoning with that information.
  7. Response completes — the AI’s text response finalizes, file conversion runs, and your editor reloads with any changes.
The entire exchange streams in real-time — you see thinking steps, status messages, and text appearing as the AI works.

​
Trust and Control

​
Every edit is versioned

Every time the AI modifies your design, a version is saved automatically:
  • Local — git commits in a .history/ directory (works offline)
  • Cloud — synced for cross-device access
  • Per-message undo — click the undo button on any assistant message to roll back to before that message’s changes
Rolling back creates a new version. No history is ever deleted. You can always go forward again.

​
Plan mode approval

For complex tasks, the AI shows you exactly what it intends to do before doing it. You approve, adjust, or reject. Nothing executes without your say-so.

​
Validation during iteration

The AI runs ERC (electrical rule checks) and DRC (design rule checks) as it works — not just at the end. It catches its own mistakes during the design process.

​
Next Steps