Choose where a project lives
- On this device opens local files without adding them to cloud storage.
- Personal Cloud (only you) adds a cloud project for your account rather than sharing it with a team.
- Team adds a cloud project to a team where you have permission.
These locations describe Workspaces sharing, not every data transfer. Hosted AI, attachments and other online features can send selected design context or files even when you work on a local project. Review Projects before sharing confidential designs.
Open Workspaces from the desktop, or use Open in Workspaces on a project's tree entry when offered. Select the project, then open its local copy to edit. An existing user-created Git repository is not automatically adopted.
Browsing a project in Workspaces is different from opening its working copy. The editor's open project and checked-out branch determine design context. Selecting another project in the list does not switch the editor.
Add an existing project
Save intended changes, choose Add project, review the saved .kicad_pro,
destination and included files, then add the project. Preparation and conversion
use a separate copy, not the original design.
Project added confirms the cloud addition; Open project is a separate local step. If opening fails, recover that same project rather than add a duplicate. The compatible flow permits another Add after confirmed completion without requiring Done; pending or unknown work still needs recovery.
Follow Add a saved project for file preparation, dependencies, exclusions and continuing an unfinished addition.
Save, Commit, Push and Pull
- Save writes editor changes to disk.
- Commit records local Workspaces history.
- Push publishes reviewed work to the checked-out cloud branch.
- Pull brings that branch's cloud changes into the local copy.
Save and Commit alone do not publish. Unsaved editor changes, saved file changes and unpushed commits are different states; an unavailable status is not clean.
Standalone Commit/Push act on the source branch. When offered inside a pending branch switch, whether they continue the switch is build-dependent. Read the review's target and continuation wording, then check the branch actually open. See Save and sync.
Ignore rules edit .traceignore, not .gitignore. In capable desktop
sessions, the AI can read it and make an explicitly requested policy edit.
Do not hide tracked .xo drawing or placement changes to bypass review.
Branches and parked work
Check the branch actually open before editing. Branch history includes inherited commits, not just commits originally authored on that branch.
Where the advanced flow is supported, Move changes carries unpublished work to the target through a three-way merge; Leave changes here keeps a stash on the source branch; Stay declines the switch. Move and Leave do not Push. Restore is explicit and merges parked work with current saved destination work, including published changes and unpushed commits. Conflicts need review.
Follow Branches and stashes before switching, restoring or discarding work. Parking alone is not switch completion.
Review pull requests
Use Pulls to propose a merge between permitted branches or from a fork. Review actual file diffs, not just the description or changed-file list. A merge preview is a separate branch, not a merged PR. Intended preview edits must reach the cloud before acceptance.
Follow Pull requests and conflicts.
Recover uncertain operations
A spinner or accepted request does not confirm cloud publication, local apply or editor opening. Use Reconcile original operation, Continue, or the matching recovery control to check the original result. Reading its receipt does not execute it again. Do not create a new request while the earlier outcome is unknown.
Compatible builds offer Cancel merge attempt for an original uncertain PR merge. It does not close the PR or undo an already completed merge. Follow Workspaces recovery.
Use Workspaces with the desktop agent
Ask can inspect supported views on a capable desktop. Agent, including execution after Plan approval, can request advertised actions through native review. Approval to edit CAD does not automatically authorize Push, branch changes or merging. Read the review and confirm only the intended operation.
App CLI and companion boundary
The native C++ trace-cli workspaces
is part of Trace desktop. Supported builds provide saved-file operations using
native Workspaces owners; headless success is not a GUI open/reload result.
The Electron Trace Plugin for Altium/KiCad does not implement these native
Workspaces handlers. Other integrations do not gain native operations from an
API version or a shared account. For command-line use, install Trace and sign
in to the desktop first, then use its bundled trace-cli.
See Workspaces integration for capability,
read-snapshot and original-request contracts.