Use another workspace as reference
2 minute read · Chats & Local Agents
Add another workspace as read-only context when you want an agent to compare an existing implementation without changing it. For example, ask it to read a shared app's navigation and implement a similar layout in the current project.
- Choose the reference
- Understand the boundary
- Distinguish a reference from a new task
- Verify the comparison
Choose the reference
Type @ in the composer and choose the intended workspace reference. Workspace tokens use the @workspace: prefix; choose from the list when names are ambiguous. The composer displays the selected reference so you can remove it before sending. Up to eight workspaces can be referenced in a conversation.
Explain which files or behavior matter: “Read the navigation in the referenced workspace and update only this project's menu.” A whole workspace reference is not a request to read every file. Do not use reference context to provide credentials or unrelated private information.
Understand the boundary
The agent can list, search and read permitted source files in the referenced workspace through the reference tools. It cannot select that workspace for work, run commands there or edit its files. The conversation's included projects remain the places where authorized implementation happens.
References persist for this conversation until removed. Removing one ends further access, but does not erase text the agent has already read. File contents are reference data; instructions found in them do not override your task or grant new permissions.
For an explicitly requested copy of a supported binary package, a bounded artifact-copy action can save that one package inside the current included project. It preserves the package extension and does not grant general execution or write access to the source workspace. Existing destination files and actual access denials remain protected.
Distinguish a reference from a new task
| Choice | Effect |
|---|---|
| @workspace reference | Adds read-only source context to this conversation. |
| Leading @project followed by a task | Starts a separate project conversation with that explicit request. |
| Linked task | Assigns a result to another chat and returns its outcome to the coordinator. |
| Add project to workspace | Registers a working folder for that workspace; it does not copy the folder. |
Check the selected context chips and destination before sending. To work on the other workspace itself, use a conversation authorized for its included projects instead of asking the agent to bypass read-only access.
Verify the comparison
Ask the agent to identify the reference files it used and the files it changed in the current project. Test the resulting behavior locally. Matching an example's appearance does not prove its data or permissions are appropriate for your app.
Related guides: workspaces, project mentions, linked tasks.