Code

Changing a session's scope

A session's scope is what it works on: its repositories, and the applications on them, its tasks and its bug reports. You can change it at any time until the session is Completed or Rolled Back: while the agent plans or builds, while it waits for your answer, between steps, in a Live session and in a Code conversation. You don't need to stop or cancel the session, and the agent is told about every change you make.

Key concepts

Scope. The repositories, tasks and bug reports a session works on. Adding an application adds its repository, and removing a repository removes the applications on it. Only the sandbox stays as it was once the agent has started. See Starting a session.

Told. The agent hears about each change. While it works, it hears about it in the step it's on: Claude Code after its next round of actions, such as reading files or running commands, and Codex the next time it uses one of Productmind's tools. Otherwise it's told at the start of its next step.

Leaving. A repository you remove after the agent has started leaves when the current step ends. Changes the agent hasn't pushed yet are pushed to its working branch first, with no pull request, and then its copy is deleted.

The scope at a glance

The chips under the session's tabs show its repositories, and its tasks or bug reports. While a change is on its way to the agent, the chip says so.

A repository you added after the agent started shows where it is:

The chip saysIt means
Adding...It's being copied next to the agent's work, in the background. The agent is told once it's there.
Joins at next stepNothing is running for the session right now, so the next step copies it, and the agent is told then.
AddedIt's copied, and the agent is told shortly.
Copy failedCopying it failed. Point at the mark to see why. It's tried again at the next step.

A repository you removed is crossed out until it has left. It reads Leaving, with where it is when you point at the mark, such as Saving its changes..., or Save failed if its changes couldn't be pushed.

A task or bug report you added shows a dot until the agent has been told: point at it to read Not told yet.

Each change also shows in the session's conversation, for example Repository added, with the repository and its branch.

Adding to the scope

To add a repository while the agent works

  1. On the session page, choose Add a base repository (the +) beside the repositories.
  2. Search for an application or a repository, and select it.

The repository joins the session on the session's working branch, and the agent gets a copy of it next to its work. Once the agent knows, the chip looks like the others. A repository added while the agent builds is published with the rest of that step's work, with its own pull request.

Until it has been copied, you can still change its base branch or make it read-only. If an application on it is read-only, it joins read-only. See Read-only repositories.

To add a task or bug report while the agent works

  1. Choose Add tasks to the session or Add bug reports to the session (the +).
  2. Select them, and choose Add N tasks or Add N bug reports.

The task joins the session and moves forward: to In Planning while the agent plans, or to In Progress while it builds and in a Live session. A bug report added to a bug fix session moves to In Progress if it is still Open, In Review or Confirmed. A Code conversation moves nothing. The agent is told, with the item's description.

If a task you add is in an application whose repository the session doesn't have, a message offers to add that too, for example Add acme/web too?: choose Add. Add a base repository also lists it under Suggested. It isn't added on its own, because a repository changes what the agent can push to.

If another session is working on the task, you're asked first, for example Move TASK-12 here?. Choose Move here to take the task out of that session and add it to this one: that session's agent is told the task left. Or choose Open SSID-4 instead to continue it there. A bug report that's in another unfinished session can't be added until you remove it from that session.

Removing from the scope

To remove a repository while the agent works

  1. On the repository's chip, choose Detach repository (the x).
  2. Read what removing it does, and choose Remove repository.

The confirmation lists what's at stake:

  • the agent is told the repository is no longer part of the session;
  • an open pull request on it stays open, but the session stops tracking it;
  • changes not pushed yet are pushed to its working branch, with no pull request, before its copy is deleted. A read-only repository has nothing to save;
  • while a step runs, the repository leaves when that step ends;
  • a running live preview keeps serving it until the preview restarts.

Once it has gone, the conversation says so, for example Saved acme/api's changes to task/add-csv-export and removed it from this session.

A repository the agent hasn't been told about yet, such as one that still reads Adding... or Joins at next step, is removed at once, without a confirmation.

To keep a repository you removed

While a removed repository's chip still reads Leaving or Save failed:

  1. On its chip, choose the ....
  2. Choose Keep repository.

The repository is back in the session as it was, with its branch, its read-only setting and its pull request. If the agent had already been told it was leaving, it's told it stays. Adding the same repository again does the same.

To remove a repository without saving its changes

If pushing a removed repository's changes fails, for example because a branch rule refuses the push, its chip reads Save failed and the conversation says why. Its copy is kept aside, and saving is tried again at the next step. To give up on those changes instead:

  1. On the chip that reads Save failed, choose the ....
  2. Choose Remove without saving..., then Remove without saving.

The next step deletes the copy and pushes nothing. The conversation shows Repository removed without saving.

The changes that weren't saved are lost. This can't be undone.

To remove a task or bug report while the agent works

  1. On the task's or bug report's chip, choose the x.
  2. Choose Remove.

The confirmation says what happens, for example TASK-12 leaves this session. The agent is told. Its status goes back to To Do. The agent is told to stop working on it, and the work it already did for it stays on the session's branch. The status goes back to the one it had before this session moved it, unless it has since left the statuses a session sets, for example once it's Done or Closed, or another unfinished session also holds it. The task's or bug report's history notes the removal. See Tasks and Bug reports.

Answering the agent's request for a repository

When the agent needs a repository the session doesn't have, it can ask you to add it, the way it asks a question: while it plans, and while it builds, until it opens its pull requests. The session's status becomes Awaiting User Input, and a window shows the repository, the applications on it and why the agent needs it.

To answer the agent's request for a repository

  1. Read the agent's reason.
  2. To let the agent only read the repository, turn read-only on. If an application on the repository is read-only, it can only be added read-only.
  3. Optionally, enter a note for the agent.
  4. Choose Add repository (Add read-only when read-only is on), or Decline.

When you add it, the repository is added as you, with the same checks as when you add one yourself, and the agent carries on with it. When you decline, the agent carries on without it, and reads your note. If it asks for a repository you removed that hasn't left yet, the window offers to keep it instead.

The agent can only ask for the repository of one of your workspace's applications. In a Code conversation, which can't pause, it asks in its reply instead.

How scope changes behave

The sandbox stays. Once the agent has started, the session's sandbox can't change, and a repository that one of the sandbox's applications runs from can't be removed.

A change you undo is never told. If you add something and remove it again, or remove a repository and keep it, before the agent was told, the agent hears about neither.

No runner is started for a change. An added repository is copied, and a removed one saved and deleted, by the step that is running, or between steps by the runner or Productmind agent already up for the session. When there is none, the next step does it.

Statuses follow the scope. A task or bug report you add moves forward as described above, and one you remove goes back. A task works in one session at a time, so adding one that another session is working on asks you to move it. See Code.

A running live preview keeps its applications. Restart the preview to include an added repository's applications. A removed repository the preview serves stays until the preview stops or restarts. See Live preview.

The Productmind agent on your machine must be up to date. For a session that runs on your Productmind agent, removing a repository and the agent's requests for one need a current version of the agent. Adding works with every version, but an older agent gets the added repository, task or bug report only at its next step. See Productmind CLI.

A session your AI coding assistant works over MCP reads its scope from Productmind when it asks for it. Removing a repository from it saves nothing: your assistant keeps its own copy.

Every change is in the audit log, with who made it. See Audit log.

Permissions

ToYou need
See a session's scopeSessions: Read
Add or remove a session's repositories, tasks and bug reportsSessions: Update
Keep a removed repository, or remove it without savingSessions: Update
Answer the agent's request for a repositorySessions: Update

Troubleshooting

Removing a repository says the Productmind agent is too old

The session runs on a Productmind agent whose version can't save a removed repository's work, for example "The Productmind agent on my-laptop is too old to remove a repository from a session it is working on". The repository stays in the session. A run of a session with a repository still leaving it is refused the same way. Update the CLI on that machine as described in Updating the CLI, then try again.

A repository can't be removed because the sandbox's application runs from it

The message names the application, for example "acme/web runs APP-1, an application of this session's sandbox". The sandbox stays as it was once the agent has started, and its applications run from their repositories, so the repository stays. To work without it, start a new session with another sandbox.

A repository can't be added while another one is leaving

The message says, for example, "acme/web is still leaving this session, and its copy uses the same folder as other-org/web". Two repositories with the same name can't be in the session at once. Try again once the leaving one has gone, when the current step ends.

"This session is finished: its repositories, tasks and bug reports can no longer change."

The session is Completed or Rolled Back, so its scope is final. Start a new session for more work.

Last modified on