The workspace

A ticket the factory takes often crosses repositories: an API and the web app that calls it, a library and the services that use it. The app opened one repository at a time.

One repo is not enough#

A workspace is a set of repositories the agent works in together. One of them is the main one; the others are added to it.

A ticket that renames an API function and updates its callers is then one session, not two.

Any agent#

ACP lets a session add directories beyond the one it starts in. Claude Code and Codex support it; Grok Build and Cursor work in one folder only. A workspace that depends on that support only works with some agents.

So the factory doesn't ask the agent for it. It makes one folder that holds a worktree of each repository, side by side, all on the same new branch, and starts the agent there.

Every agent can work in one folder. The first prompt says what the folder holds, as a map, and to commit in each repository it changes.

One codebase#

An agent reads the instructions file of the folder it starts in. In a workspace that is the folder above the repositories, so the agent worked in each repository without its rules.

The first prompt now carries a map. For each repository it says what it is, from its package.json description or its README, its folders with the packages inside them, where its instructions are, and what it uses from another repository through a local dependency.

It tells the agent to read a repository's instructions before it works there, and to treat the repositories as one codebase: read across them, and change each one the work reaches.

Tools for all of them#

A chat of several repositories also gets a workspace tool server, for the whole session. Each tool acts on every repository at once, so the agent doesn't run git in each one and put the answers together.

Status gives each repository's branch, its commits ahead of its base and its uncommitted files. Diff is one diff, with paths that start with the repository's folder, such as api/src/routes.ts, and can be limited to some repositories.

Search skips ignored folders such as node_modules. Commit stages everything in each repository with changes, commits it with the same message and reports each one. A connector can't take the name workspace.

Choosing a workspace#

The workspace sits under the composer, beside where the agent runs. A single repository can run in place or in a worktree. A workspace of several always runs in worktrees, so Local is off for it.

A workspace is saved with a name. Editing it adds a repository, removes one, or makes another the main one.

Pull requests across repositories#

Each repository with commits on the branch gets its own chip above the composer. One of them opens the pull requests for all of them, and each one lists the others in its description.

Merge all checks every pull request first. If one has conflicts or checks still running, none is merged, so the repositories never end up half changed.

When the chat ends#

A worktree the agent never changed is removed with its branch. One with changes or commits stays, and the next chat says where it is.