# Linked folders > A project can include other folders you already have, left exactly where they are, each with its own repository and version control. - Area: Desktop, mobile and web - Plans: All plans - Last checked against the product: 2026-10-16 - Web page: https://agentsroom.dev/docs/linked-folders ## What it does A project can include other folders you already have, left exactly where they are, each with its own repository and version control. Typical cases: a web app in one repository and its API in another, a game and its port to a newer engine version, a library and the projects that use it. You add a folder once. From then on every agent of the project, whether you start it from the agent list, from a backlog ticket or from your phone, still starts in the project folder and also gets access to every linked folder, which it finds listed in its brief. Nothing on disk is moved, copied or symlinked. The project folder stays the main one: auto-commit when work is done, one worktree per ticket and team step diffs keep working on it only. The other repositories are reviewed and committed by hand in the **Changes** tab. **Video (1 min 28 s):** [Linked folders, shown in the real app](https://youtu.be/TPLqm9FGbkE). A shop lives in one repository and its API in a neighbouring folder; the API folder is added in Project settings, one instruction makes the agent edit a file on each side, and the repository picker of the Changes tab shows and commits each repository apart. ## Where to find it - Desktop: **Project settings > General > Linked folders**. The card carries a **Tutorial** link to the video. - **Changes** tab: the repository picker lists the project folder ("name (project folder)") and each linked folder that is a git repository ("name (linked folder)"). - Mobile: read-only list at the bottom of the project's **…** menu, under **Linked folders**. ## How to use it 1. Open **Project settings > General > Linked folders**. 2. Click **Add a folder** and pick the folder with the folder dialog. Repeat for each one. 3. Start an agent. It starts in the project folder and gets every linked folder on top. 4. Open the **Changes** tab and pick a linked repository in the picker to review, stage and commit its changes there. To take a folder out, click the cross next to it (**Remove from the project**). Nothing is deleted on disk. A folder that cannot be found on this computer stays in the list with the warning "Not found on this computer: skipped when an agent starts.", and the agent's terminal prints "Linked folder not found, skipped for this launch". ## Settings - `linkedFolders` (project, Project settings > General > Linked folders): absolute paths of the other folders that belong to the project. Empty by default ("No linked folder: the project only covers its own folder."). Stored on this machine only. ## Agent tools (MCP) - `settings_get` / `settings_set` at scope `project`, key `linkedFolders`: read or change the list. ## Providers Linked folders are listed in the brief of every provider. They are also granted natively at launch, through the CLI's own `--add-dir`, to Claude Code, Codex, GitHub Copilot, Antigravity, Kimi and Mistral Vibe. The other CLIs (OpenCode, Aider, Grok, Amp, oh-my-pi, Freebuff, Devin, Cursor) have no such flag: they find the folders listed in their brief and open them by full path when their own permissions allow it. ## Mobile Present. The list is shown read-only in the project's **…** menu (folders are picked with the computer's folder dialog, so they are added on the desktop). The **Changes** screen offers each linked folder that is a git repository in its picker, next to the worktrees. An agent started from the phone gets the same linked folders as one started from the desktop. ## Limits - Up to 10 linked folders per project. The project folder itself and a duplicate are refused ("This is the project folder itself.", "This folder is already linked."). - Linked folders are paths of this computer: they are not synced to your other machines. - Agents launched on a remote SSH host do not receive them; the terminal says so ("not passed to this remote launch: it is a path on this computer, not on the host"). - Auto-commit, one worktree per ticket and team step diffs stay on the project folder. - You cannot choose which folder an agent starts in: it is always the project folder. - Works on macOS, Windows and Linux. ## Common questions - **Can one project include several folders without moving them?** Yes: **Project settings > General > Linked folders**, **Add a folder**. Each folder keeps its own repository. - **How do I give an agent my app and its API at the same time?** Open the app's repository as the project, then add the API folder under **Project settings > General > Linked folders**. Every agent you start then works in both, and you commit each one from the **Changes** tab. Video: https://youtu.be/TPLqm9FGbkE - **Why did my agent not see a linked folder?** The folder is missing on this computer (the settings and the terminal say so), the agent runs on a remote SSH host, or its CLI has no native flag and its own permissions block paths outside the project. - **Do I still need to type --add-dir?** No, AgentsRoom passes it on every launch for the CLIs that support it. - **Is there a video that shows it?** Yes, 1 min 28 s, filmed in the real app: https://youtu.be/TPLqm9FGbkE ## Related - [Workspaces](https://agentsroom.dev/docs/workspaces.md): projects with a mission and no repository, and the notice for a folder holding several repositories. - [Git Worktrees](https://agentsroom.dev/docs/worktrees.md): the worktree per ticket, which stays on the project folder. - [Multi-Project Multi-Agent](https://agentsroom.dev/docs/multi-project-multi-agent.md): running agents across several projects. - [SSH Connections](https://agentsroom.dev/docs/ssh-connections.md): remote hosts, where linked folders are not passed.