The short version
Castforge can put several agents on one project at the same time. Three things keep them out of each other's way, and out of yours:
- Each one works in its own copy of the project, on its own branch, and the copies come back one at a time in a fixed order.
- Each one is a separate sign-in. Every agent is its own command-line tool, running as its own process, on its own account. Castforge does not read any agent's sign-in tokens.
- Actions are sorted into three classes by what they can do to you, and the project's safety level decides which of those classes stop and ask you first.
The rest of this page is the detail behind each of those.
Where each agent works
When the team runs several cards at once, each card gets its own lane. A lane is a real, separate checkout of your project on disk, created by Castforge inside its own application folder rather than inside the project folder you opened. Each lane has its own branch, and the role working there commits to that branch.
Castforge starts each role with its own lane as its working directory. When a role is sent to check work that was produced somewhere else, Castforge points the check at the copy that actually holds that work, and if it cannot identify that copy the check is refused rather than run against the wrong files. There is more on that in Your AI dev team.
When a role works in your project folder instead
Not every card needs its own copy, and sometimes one cannot be made. A role works directly in your project folder in two situations: when it is the only role writing anything right now, which is the common case and the tidiest one, because its work lands on your branch with nothing to merge afterwards; and when a separate copy could not be created, for example because the branch it would be cut from is missing work that earlier cards finished. That second case is recorded, and the role still runs rather than being blocked.
The rule that matters to you is the same either way: Castforge does not start a second writing role in a copy another role is already writing in. Castforge checks this at the last moment before it starts an agent, against where that agent is actually about to work rather than where it was expected to work. If the copy is already occupied, the second role does not start. Its card waits, the board shows it waiting and says why, and it goes as soon as the copy is free. Nothing is dropped and nothing is re-planned.
This is the check that decides it, so it is worth saying what it is not: it is not a warning after the fact. A second agent that has already started writing has already overwritten the first one's files, and no amount of reporting afterwards brings that work back. The decision happens before the second agent exists.
If your project has no git repository
Separate copies are made with git, so a project created without a git repository does not have them. That is a supported choice, and the New Project wizard says so at the moment you turn the toggle off.
Here is what it means in practice. The agents work one at a time, directly in your project folder, rather than each in its own copy. And the independent checks that need a second copy are skipped: the design check, and the review of a finished card. Both of them exist to look at the work in a copy separate from the one the agent wrote it in, and without git there is no such copy. When a check is skipped, the reason is recorded on the card and shown with it, and the run carries on: no card pauses, and nothing stops to ask you to repair a repository you chose not to create.
Nothing is degraded quietly here. You made the tradeoff deliberately, the app names it where you made it, and it names it again on any card whose check was skipped. If you want the separate copies and the independent check later, you can add git to the project at any point.
Coming back to your branch
Finished lanes do not race each other back into your project. They land one at a time, in an order worked out before anything is merged: whatever a card depends on lands first, and cards with no dependency between them land in board order. The order does not depend on which lane happened to finish first, so the same set of cards lands the same way twice.
A lane becomes eligible to land only once its card has been reviewed and marked done. If a lane has fallen behind while it was being worked on, because your branch moved on without it, Castforge first brings that lane up to date with your branch inside the lane's own copy. That write happens there and nowhere else: your project folder is not touched by it. Only after that does Castforge run a trial merge that writes nothing at all, and only a lane that comes back clean is actually merged.
A lane that cannot merge cleanly is parked, with its reason on the card. Your branch is left untouched, the lane and its branch are kept exactly as they are, and the other lanes in the batch carry on landing. A parked lane is re-checked on every later pass, so a conflict that clears up on its own lands with nothing for you to do. If the trial merge cannot be run at all, that lane is parked too, because a merge Castforge could not check is not one it will make. A lane that cannot be brought up to date parks the same way, with its reason on the card: its own copy is left clean rather than half merged, and your branch is never touched by the attempt.
Your own uncommitted work
If your project folder has uncommitted changes when lanes are ready to land, the landing waits. It does not merge over your work, and it does not tidy your folder to make room: Castforge will not commit, stash, clean or discard anything you had in progress, and it says so when it defers. Once you have committed or set aside what you were doing, the next pass lands the waiting lanes, and nothing has to be re-run.
Work an agent produces directly in your main project folder is a separate matter, and it is committed as the run goes. Working in a project has the full account of what a run commits and what it leaves alone.
One thing in the other direction, so it is not a surprise: rolling back to an earlier point is the one action that deliberately moves your uncommitted work. It puts what you had in progress into a named git stash first, and it stops before touching anything if that does not succeed, so the work stays recoverable. That action is in the third class below, which means it asks you on Careful and Balanced.
What an agent can touch
Castforge starts a role in its own lane or in your project folder, and gives it the tools its seat provides. Anything past that is checked, and what the check does depends on the safety level.
- Work that reaches outside your project folder is checked every time, at every safety level, against a built-in list of the places that matter: credentials and keys, browser profiles, other agents' settings folders, your other projects, system locations, and the commands that send a local file somewhere. What happens on a match depends on the level, which is the subject of the next section but one. The list itself is in Working in a project.
- Three roles read, review and report. The Lead, the Reviewer and the Researcher read, review and report. On the agents that support it, Castforge starts them without the file-editing tools, and on a Claude seat it also checks each shell command they make and refuses the ones it recognizes as changing your files. Castforge gives a Reviewer and a Researcher one tool of their own for saving their findings or reasoning into a file it names and places for them. How firmly that is enforced varies by which agent is in the seat, so it is worth reading that detail in Your AI dev team before relying on it.
- A tool from a server you connected yourself is treated cautiously until Castforge has reviewed it. A server cannot mark its own tools as harmless and earn a quieter answer that way.
- A role does not inherit your personal setup. Whatever you have installed in your home folder for your own terminal use, your own instructions file, your own hooks, does not reach a Castforge role. The project's own conventions file still applies, because that is context the role should have.
Sign-in and credentials
Every agent is its own command-line tool, signed in to its own account. Castforge starts that tool as a separate process and talks to it. It does not sign in on the agent's behalf and it does not hold the agent's credentials, which is also why signing out of some agents has to be finished in their own tool. Connecting AI agents covers all of that.
Castforge never reads an agent's sign-in tokens. Not to move them between agents, not to reuse them, not to look at them. Those folders sit on the list described above, so an agent reaching into another agent's settings folder is treated like any other sensitive location: on Careful and Balanced that stops and asks you, and on Autonomous it runs and is written to the log.
Credentials for the services Castforge connects for you, deploys and databases and the like, work differently, because there Castforge does hold a token you gave it. When a command needs one, the token goes into the environment of that one process and nowhere else:
- it is never put on the command line, so it cannot land in a shell history or in the text of a permission prompt;
- it is never written into what an agent is asked to do;
- it is never printed to the log or onto your screen;
- and a service you have not connected contributes nothing at all, rather than an empty value that fails later in a confusing way.
Being straight about the edge of that: a process can read its own environment. So this keeps a credential out of the prompt, the command line, the screen and the log, and it is not a claim that a connected service is unreachable. What an agent may actually do with a connected service is the subject of the next section.
No Castforge action hands an agent a browser. Nothing in the set of actions an agent can call opens a browser window or drives one. The browser windows Castforge opens are sign-in windows, and they open because you clicked a sign-in button.
What asks you first, by safety level
Every action an agent can take through Castforge belongs to one of three classes, decided ahead of time by what the action can do to you rather than by how it happens to be worded. Your project's safety level then decides which classes stop and ask you.
The levels are Careful, Balanced and Autonomous, and Working in a project is the full reference for them. This section is only about the three classes.
Reads that change nothing
These run without a prompt, at any level. They are the actions that look something up and stop there: checking whether your dev server is running, listing your database projects, checking whether a domain name is available, listing the components in your design system, listing the servers you have saved, reordering the milestones on your board, or moving a phase that has not started yet within its own milestone.
Changes you can undo
These ask you on Careful and Balanced. On Autonomous they run without asking. They change something real but leave it recoverable: a preview deploy, setting an environment variable on your project, pulling design components back into your project, connecting or disconnecting a saved server for the project, deleting a card or a phase from the board, clearing plan cards that have not run, and deleting or archiving a milestone.
Public, irreversible, or costs money
These ask you on Careful and Balanced. They are the ones you would want to be at the keyboard for: deploying to production, linking or creating a database project, running a database migration, buying a domain, attaching a domain to a live deployment, publishing your design system to the cloud, creating a cloud design project, starting a new milestone, resetting your working tree back to an earlier point, and reverting a card along with everything that depended on it.
On Autonomous there is no prompt for these, and they run unattended. That is what the level means, it is a deliberate choice, and the consequence is worth stating plainly: a project left on Autonomous can be deployed to production, have its database migrated, and have money spent, with nobody at the keyboard. Castforge still classifies every one of those actions and still writes down what happened, so an unattended run can be read back afterwards. If that is not the trade you want, Balanced is the setting to leave a long run on.
Two more things worth knowing about this class:
- "Allow always" cannot settle it. An earlier Allow always never carries over to this class. On Careful and Balanced, an action here asks you afresh, however many similar questions you have already answered.
- An action Castforge does not recognise is treated as belonging here. That is on purpose: an unfamiliar action is judged as the most consequential kind rather than the least. On Careful and Balanced it asks you. On Autonomous it runs like everything else, so being unfamiliar is not by itself a reason a project on Autonomous will stop.
The permission caveat you see names the agent actually seated, not a fixed one. Most agents let Castforge see each tool call as it happens and refuse the ones a level does not allow, so Careful and Balanced gate exactly what this page describes for them. GitHub Copilot decides for itself which actions to raise for approval. We measured that it raises none for file edits or shell commands inside your project folder, so on a Copilot seat Careful and Balanced gate only what Copilot chooses to ask about. Everything it does is still recorded in the conversation and still reversible. If you are relying on Careful or Balanced to stop a specific kind of action, check which agent is sitting in that seat first. A read-only role (the Lead, Reviewer or Researcher) is not seated on GitHub Copilot at all, for the same reason: Copilot does not let Castforge stop it from editing your files. We have not yet tested Copilot's own read-only controls on a live session, so that stays the rule for now. It applies to a chat in a project with a single agent as well as to a team. If Castforge fails to look up the project's team at that moment, it does not start Copilot until the lookup works. "Your AI dev team" describes what you will see and how to reseat the role.
When a check cannot get an answer
A gate that quietly does nothing is worse than one that fails, because the run just sits there and nobody can tell why. Castforge is built the other way round: when a check cannot reach a conclusion, it refuses out loud.
- A prompt that cannot be shown to you is refused, not skipped. If there is no window to draw it in, or the connection carrying it breaks, the action is declined and the agent is told so.
- A prompt nobody answers is refused after five minutes. The run carries on with that one action declined, and the record says the time ran out rather than pretending you said no.
- A prompt that reaches your screen is yours. Below Autonomous nothing else answers it, however long you take.
- A prompt that is handed no verdict asks. If the part of the app that draws a prompt is ever given no decision to show, it puts the question to you rather than settling it itself.
- A path Castforge cannot work out is treated as leaving your project, rather than assumed to be inside it.
- A check pointed at a working copy Castforge cannot identify is refused, rather than run against whatever files are at hand.
- A second role is not started in a copy another role is already writing in. Its card waits instead, with the reason shown on the board, and it goes when the copy is free.
- A merge that cannot be trial-run is not made, and the lane is parked with the reason on its card.
Refusing is not the same as never failing. What it buys you is that a Castforge gate ends in a decision you can read back, instead of in a run that hangs.