Workspaces and linked projects
Grouping related projects, linking them at a coupling level, cross-project context, and what the app cannot set up.
Last updated:
On this page
A workspace groups related Vibeless projects, such as a frontend and its API, or the services in a monorepo. A link between 2 projects in a workspace lets one project's agent read the other project's spec, at a depth you control.
Where to find it
- Header. The selected workspace's name appears next to the panel title, before the project picker.
- Dashboard, Settings tab. The Workspace card and the Linked Projects card sit below the Repository card. See Dashboard.
The app has no screen for creating a workspace, renaming one, moving a project into a workspace, or creating a link. Links are created by a connected agent (see below). In the app you can view links, change their coupling level, and remove them. All of this depends on a workspace being selected in the header (see The workspace switcher).
What a workspace is
Every project belongs to at most one workspace. Projects that were already registered when workspaces were added each got a workspace of their own, named after the project. A project created since then belongs to no workspace, because the app has no way to add it to one.
A workspace holds 2 kinds of shared data:
- Member projects. The projects that belong to it.
- Workspace-level context nodes. A context node is one entry in a project's spec map (a rule, a spec, or a standard; see Context Editor and Search). Workspace-level nodes apply to every member project.
The workspace switcher
The header shows the workspace you selected last. The app remembers that choice on this computer.
- With more than 1 workspace, the name is a button. Click it to open the Workspaces menu and pick another one.
- With 1 workspace, the name appears as a static label.
- If no workspace has been selected yet, nothing appears. The menu only appears once a workspace is selected, so the app has no control for making the first selection on a computer.
Switching workspaces does not filter the project picker. It changes which workspace's links the Linked Projects card reads.
What a link is
A link connects 2 projects in the same workspace. It has 3 properties:
- Coupling level. How much the other project's agent can read. The levels are awareness, dependency, read, and governance.
- Direction.
bi(both ways, the default) oruni(one way). On a one-way link, only the source project's agent can read the target. On a two-way link, each project's agent can read the other. - Created by.
agentwhen an agent made the link through MCP,userotherwise.
Coupling levels
Each level includes everything in the levels above it.
| Coupling level | What the linked project's agent can read |
|---|---|
| awareness | Name, goal statement, and tech stack |
| dependency | Awareness, plus each phase's name, status, and order |
| read | Dependency, plus constraints, decisions, and context nodes |
| governance | Read, plus the context nodes shared on the link |
A phase is a stage of planned work in a project. A constraint is a rule the project's code must follow. A decision is a logged choice with its reasoning.
Governance is the only level that changes the rules the agent is held to. The other levels change only what it can look up. Context nodes shared on a governance link are added to the agent's working rules at session start and before tool use, through the same hooks that deliver the project's own rules. This hook delivery ignores the link's direction, so on a one-way governance link both projects' agents receive the shared nodes. The app has no screen for choosing which nodes a governance link shares.
How to use it
Change a link's coupling level
- Open the project and select Dashboard, then Settings.
- Find the link in the Linked Projects card. Each row shows a shortened id of the other project, the direction, and who created the link.
- Choose a new level from the menu on the right of the row.
The app confirms with Link updated. The new level applies the next time an agent reads across the link.
Remove a link
- In the Linked Projects card, find the link.
- Select the trash icon on the row.
The link is deleted at once, with no confirmation step, and cannot be undone. The app shows Link removed. Neither project is changed, and the agent loses access to the other project's data from that point.
The Isolation card on the same tab shows a Discoverable setting. Its button reads Coming soon and does nothing in this release.
How agents use it
The 5 workspace tools appear in the agent's tool list only when the agent's project belongs to a workspace. Full details are in the MCP tools reference.
| Tool | What it does | Writes anything |
|---|---|---|
vibeless_get_workspace_context | Returns the workspace, its member projects, the links between them, and the workspace-level context nodes | No |
vibeless_get_linked_project_context | Reads another project through a link, limited by the coupling level | No |
vibeless_check_cross_project_constraint | Returns the project's own constraint check, plus workspace-level rules and references to nodes shared on governance links | No |
vibeless_link_projects | Creates a link from the agent's own project to another member of the workspace | Yes, a new link |
vibeless_create_project | Creates a new Vibeless project | Yes, a new project |
A few behaviors are worth knowing before you let an agent work across projects:
- Reads are checked by the app, not the agent. The app confirms that a link connects the 2 projects and that both still belong to the workspace before it returns any data. Without a link, the call fails.
- Agents can only link from their own project. The source must be the agent's project, and the target must be a member of the same workspace. The agent picks the coupling level, including governance. Review agent-created links (marked
agent) in the Linked Projects card and lower or remove any you did not intend. - The cross-project check returns data only. As with
vibeless_check_constraint, the agent decides whether its proposed action complies. Shared governance nodes come back as references, so the agent looks up their text separately. - Agent-created projects count toward your plan.
vibeless_create_projectis subject to the same project limit as a project you create in the app. At the limit, the call fails and the agent is told to ask you to upgrade or delete a project. See Account, plans, and projects.
How it connects to team sync
Workspaces, workspace-level context nodes, and links are stored in a local registry on your computer. Team sync does not send them to your organization. A teammate who opens a shared project does not get your workspace or your links. See Organization and team sync.
Rules and limits
- A link only connects projects in the same workspace.
- A locked project cannot be read through a link, and an agent cannot create a new link to one. A locked project is one held dormant after a plan downgrade. It appears by name only in the workspace's member list, and the header project picker hides it.
- The coupling levels and directions are fixed to the values above. The app rejects any other value.
If something looks wrong
- Linked Projects says "No linked projects" but you expected some. The card reads links from the workspace selected in the header. If the header shows a workspace menu, switch to the workspace the project belongs to.
- The header shows no workspace name. No workspace has been selected on this computer, and the app has no control to select the first one. The Workspace card shows None and the links card lists no links. Agents are not affected: their workspace tools depend on the project, not on the header.
- The agent has no workspace tools. The agent's project does not belong to a workspace, which is the case for every project created after workspaces were added. The 5 tools appear only for projects that belong to one.
- The agent gets a forbidden error reading another project. No link connects the 2 projects in the needed direction, or one of them has left the workspace. Check the direction badge: on a
unilink, only the source project can read. - The agent cannot read a project it is linked to. The target project is locked. See Account, plans, and projects for how locked projects work.