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

# Projects

> Projects are the top-level containers for your PCB designs in Trace.

## Project Structure

A Trace project consists of several files, all stored in a single directory:

| File            | Description                                                |
| --------------- | ---------------------------------------------------------- |
| `.trace_pro`    | Project configuration                                      |
| `.trace_sch`    | Schematic file (AI-friendly intermediate format)           |
| `.trace_pcb`    | PCB layout file (AI-friendly intermediate format)          |
| `.kicad_sch`    | KiCad schematic file (canonical format used by the editor) |
| `.kicad_pcb`    | KiCad PCB file (canonical format used by the editor)       |
| `.trace_sym`    | Custom symbol library                                      |
| `.trace_fp`     | Custom footprint library                                   |
| `fp-info-cache` | Footprint information cache                                |
| `.history/`     | Local version history directory (git-based)                |

## Dual File Format Pipeline

Trace uses two file formats that work together:

1. **`.trace_sch` / `.trace_pcb`** — A simplified, line-oriented format designed for AI agents to read and write efficiently. When the AI makes edits, it modifies these files.
2. **`.kicad_sch` / `.kicad_pcb`** — KiCad's native S-expression format used by the schematic and PCB editors.

When the AI edits a `.trace_sch` file, Trace automatically converts it to `.kicad_sch` using a Python converter (`trace_json_to_sexp.py`). The editor then reloads from the `.kicad_sch` file. This conversion is debounced at 200ms to batch rapid edits.

```
AI writes .trace_sch → syncTraceToKicad() → .kicad_sch → Editor reloads
```

You don't need to interact with `.trace_sch` files directly. They're managed by the AI pipeline. Your manual edits happen in the visual editor, which works with `.kicad_sch` / `.kicad_pcb` natively.

<Note>
  Because Trace stores designs in standard KiCad formats, you can open any Trace project in vanilla KiCad and vice versa. There's no vendor lock-in.
</Note>

## Local Version History

The `.history/` directory inside your project folder contains a git-based version history of your design. Every AI edit creates a new commit in this local repository.

* **Offline-first** — Works without an internet connection
* **Background saves** — Versions are created in the background without interrupting your workflow
* **Atomic commits** — Partial saves can't corrupt your history
* **Survives uninstalls** — The `.history/` directory is inside your project, not in the application

See the [Version History & Rollback](/guides/version-history) guide for details on browsing and restoring from local history.

## Backups

Trace maintains multiple backup layers:

* **Local history** — Git-based version snapshots in `.history/` (created automatically on every AI edit)
* **Cloud sync** — Versions saved to Trace's backend for cross-device access and disaster recovery
* **ZIP archives** — Periodic full-project snapshots
* **Backup files** — `.bak` copies of previous saves

## Creating Projects

Create a new project from the launcher with **File → New Project** or `Ctrl+N`. Choose a directory and project name. Trace creates the project structure automatically.

## Project Settings

Configure project-level settings including:

* **Board size** — Default board outline dimensions
* **Layer stack** — Number of copper layers and stackup
* **Design rules** — Minimum trace width, clearance, via sizes
* **Grid** — Snap grid for schematic and PCB editors

## Syncing

Project metadata syncs to your Trace account, including conversation history and AI context. The actual design files remain on your local machine.