Skip to main content

​
Overview

Every time the AI modifies your schematic or PCB, Trace automatically creates a version snapshot. You never lose work — you can roll back to any previous state at any time. Version history works through three complementary systems.

​
Local History

Local history is the primary versioning system. It works offline and requires no account or network connection.

​
How It Works

  • Trace maintains a .history/ directory inside your project folder
  • Each version is a git commit containing the full file content at that point in time
  • Versions are created automatically in the background after every AI edit
  • The git-based system supports atomic commits, so partial saves can’t corrupt your history

​
Background Saves

Version saves happen in the background without interrupting your workflow. After the AI completes an edit, Trace:
  1. Captures the current state of modified files
  2. Commits them to the local .history/ repository
  3. Records a summary of what changed
If a background save fails (e.g., disk full), it logs a warning but doesn’t block your work. The next successful save will capture the current state.

​
Cloud Sync

Cloud versions are stored in Trace’s backend (Supabase) and sync across devices.

​
When Cloud Versions Are Created

Cloud versions are saved at the same time as local versions — after each AI edit. They contain the full file content (not diffs), so any version can be restored independently.

​
Cross-Device Access

If you sign in to Trace on a different machine, your cloud-synced versions are available for restore. This is useful for:
  • Moving between a desktop and laptop
  • Recovering after a machine failure
  • Sharing a specific version state with a collaborator
Cloud sync requires an internet connection and a Trace account. Local history works regardless.

​
Per-Message Undo

Every assistant message in the chat is tagged with a version_id that represents the state of your design after that message’s edits were applied.

​
How to Undo

Click the undo button on any assistant message in the chat to restore your design to the state before that message’s edits. The rollback is:
  • Non-destructive — Rolling back creates a new version rather than deleting history, so you can always go forward again
  • Instant — The restore loads from local history first (fast), with cloud as fallback
  • Scoped — Only the files that were modified by the AI are affected

​
Version ID Semantics

To understand rollback correctly:
  • The version_id on message N represents the state after message N’s edits
  • To restore to the state before message N, Trace uses the version_id from message N-1
  • If message N-1 has no version_id (it was a question, not an edit), Trace walks further back to find the last edit

​
Restore Dialog

For browsing and restoring from the full version history (not just per-message), Trace provides a dedicated restore dialog.

​
What the Dialog Shows

ColumnDescription
TimestampWhen the version was created
SummaryA brief description of what the AI changed
HashThe git commit hash for the local version
Changed FilesWhich files were modified in this version

​
How to Access

Open the restore dialog from the chat panel’s version history menu. Select any version and click Restore to roll back to that state.

​
AI Edit Undo/Redo

Beyond per-message rollback, Trace maintains a full undo/redo stack for AI edits through the AI_COMMIT system:
  • Each AI edit is recorded as an atomic commit with before/after state
  • Undo reverses the last AI edit, restoring all modified files to their previous state
  • Redo reapplies a previously undone edit
  • The undo/redo stack is per-tab, so undoing in one conversation doesn’t affect another
This is separate from the manual undo (Ctrl+Z) in the schematic and PCB editors, which handles your own manual edits.

​
Best Practices

  1. Use Plan mode for risky changes — Plan mode lets you review before execution. If you don’t like the result, undo rolls back everything the plan did.
  2. Check version history before major redesigns — If you’re about to have the AI redesign a section, note the current state so you can easily find it in history.
  3. Local history survives uninstalls — The .history/ directory is inside your project folder, not in the app. It persists even if you uninstall and reinstall Trace.
  4. Cloud sync is a backup, not a replacement — Local history is faster and works offline. Cloud sync adds cross-device access and disaster recovery.