Architecture · Workflow

Running two agents on one project

Two tasks, one project folder. Neither can see the other’s unfinished work, and nothing either produces reaches the working tree until it is integrated.

Last updated September 28, 2026

September 18, 2026 · Architecture · Workflow · 5 min read

The application states the arrangement in the review panel: "Review changes from this agent's isolated workspace. Integration preserves a recovery checkpoint."

Two properties are named in that sentence. Each task works in a copy of the project, and integration is the moment the copy's changes are written to the original.

Why isolation is about incompleteness

The boundary is not primarily a defense against a malicious agent. It is a boundary against partial work. Two agents editing one working tree can each read the other's half-finished state and build on a change that is about to be revised, which produces a reconciliation problem larger than the parallelism saved.

With separate copies, neither task observes the other until a person decides the work is ready to meet.

Integration is an action

Because changes stay in the copy, someone has to declare when they are finished. ClearFrame makes that an explicit step: the changes are reviewed, then integrated. The alternative, applying every change automatically and relying on version control to untangle the result, defers the work to a point at which the context that produced the changes is no longer available.

The trade-off is real and the product does not hide it. Explicit integration is slower per change. It suits work meant to be kept, and suits a disposable experiment poorly, where the result is wanted immediately. The browser workspace on this site exists for the second case; the desktop application is built for the first.

Integration is reversible

Integration writes to the project, which makes it the moment a recovery checkpoint carries the most weight. The panel names it at the point of decision rather than in documentation. The sequence is review, integrate, and still able to reverse.

The snapshot machinery described in file recovery is what makes that sequence possible.

The running result, not only the diff

A diff records what changed and not whether the change works. ClearFrame runs a live preview beside the conversation, so the review surface includes the running application. For a change to an interface, seeing the result and reading the diff are different activities.

Branching

Because a task works in its own copy, a new task can begin from the current state without disturbing the original. Branching follows from the architecture rather than being a separate facility, and it is what makes a second attempt inexpensive.

What isolation does not cover

Semantic conflicts remain. Two isolated changes can each be correct and be wrong together. Isolation removes the mechanical conflict and not the design one, which is why integration is a review rather than a merge.
External effects are not isolated. A task that writes to a shared database or calls a live API is not contained by the isolation of the file system.
Disk usage is a cost. An isolated copy of a large project is a copy of it.

What the review surface shows

The panel frames the change set precisely: changes from this agent's isolated workspace, with integration preserving a recovery checkpoint. Three facts are carried in one sentence, and each is load-bearing. The changes belong to one task rather than to the project. They are not yet in the working tree. Integrating them creates a checkpoint that can be returned to.

Because the framing is per task, reviewing two agents' work is two reviews rather than one combined diff. That is more steps and a clearer question. A combined view asks the reviewer to decide whether the project is correct; a per-task view asks whether this task's work is correct, which is a question with an answer.

The cost of a copy

An isolated copy of a large project is a copy. For a repository with a substantial history, the copy is not the whole history but it is not nothing either, and the cost scales with the number of tasks running at once. It is a straightforward trade: disk and copy time in exchange for a boundary that cannot be crossed by accident.

The alternative architectures have their own costs. A single working tree with per-task stashes moves the reconciliation problem to the person, and it does so at the moment the context is least clear. A shared tree with file locking avoids the copy and produces contention on the files agents most want to touch, which are usually the same few entry points at the root of a project.

How branching falls out of it

Branching is a consequence rather than a feature. If a task already works in its own copy, starting a second attempt from the current state requires no new mechanism — it requires another copy. The reason it is worth naming is that the capability is what makes a second approach cheap, and cheap second attempts change how work is planned. A change that might not work is worth trying when trying it costs a copy.

Where the boundary ends

File system isolation covers files. It does not cover the network, a database, a package registry or a deployed environment. A task that installs a package, writes to a shared database or calls a live API has effects that no copy contains, and the review panel will not show them because they are not files.

The limit sits directly beside the capability, because the review surface is convincing. A clean diff against an isolated copy invites the conclusion that nothing else changed, and anything outside the project did.