16. Collaboration between several people

Several people can work on the same project, each from their own app, on their own computer, with their own roles and taking turns.

How it works

• Each person has their own app. Each one installs Team AI Console on their computer, with their own agent (Claude Code or Codex), their own agent account and subscription, their own license and their own git credentials. There is no central app or shared server: each copy of the app works on its own copy of the project.
• One project, one repository. All copies are clones of the same git repository. One person creates the project and turns collaboration on; the others join from their app with the repository address.
• Each person, their roles. The team’s roles are shared out: each person claims theirs (the analyst, QA, the developer…). One person can hold several roles, and every role needs an owner before the project starts.
• Taking turns. At any moment the turn belongs to one role, and so to the person who owns that role. That person writes in the chat and the agent on their computer does the work; the others see the project, the documents and the workflow step, but cannot write.
• The turn moves from one app to another. When the role finishes and the next one belongs to someone else, the turn is handed over: the app pushes the work to the repository, the other person’s app pulls it, notifies them (“It’s your turn”) and their agent starts with the context of the previous turn. The workflow goes on like this, person to person, until the end of the sprint.

For example: Ana holds the Product Manager and Business Analyst roles, and Luis the Tech Lead and Developer roles. Ana works in Ana’s app until the design is approved; on the handover to the Tech Lead, Luis’s app sends the notice, Luis carries on from Luis’s computer with Luis’s own agent, and Ana’s app stays read-only until the turn comes back to one of her roles.

What each person needs: the app installed, the agent signed in, a license that includes Collaborate (and Join a project, for whoever joins), git and access to the repository with their own credentials.

Where the work travels

It works only with projects in a git repository with a remote (GitHub, GitLab, Bitbucket…): the documents and the code travel in commits on the code branch, and the team state (roles, turn, history, conversation log and workflow log) on a branch of the app’s own, team-ai-console/collab, which only the app writes. The app keeps it in its data folder, outside the project: the project folder gets no files from collaboration and your code branch gets no state commits.

Preparing the project

• Create the project in a git repository (New project → In a git repository, to share it), or turn the folder into a repository with a remote. Without that, collaboration cannot be enabled: the project folder must be the root of the repository (not a subfolder of another one) and have a remote. If a project brings an old collab.json but is not in git, the app works in individual mode and says so in the Team panel.
• Projects that already collaborated (with collab.json inside the code): the first time an admin opens them, the app moves the state to the branch team-ai-console/collab and says so in the Team panel (with Dismiss) and in the chat. The old file stays with a note pointing to the branch. Until then, people who are not admins work in individual mode.
• The other people use Join a shared project (git)…: they paste the repository URL, choose the destination folder and click Clone and open. Their own git credentials are used (SSH key or token). The app leaves the folder on the team’s code branch (not on the remote’s default branch) and says so in the chat (“The project moved to branch X”). The same happens when reopening a shared project that was closed for a while. If the remote has no app branch, the project works in individual mode.

The Team panel

Opens with the Team option of the view switcher in the top bar; to go back, choose Chat.

• Who are you? — collaboration uses your git identity (name and email). If it is not configured, the panel asks for it.
• Enable collaboration — creates the branch team-ai-console/collab on the remote with the team state. Whoever enables it is the first admin. If the remote does not allow creating the branch (for example, because of branch protection), the panel shows the remote’s error and what to ask whoever manages it, and you stay in individual mode.
• Team’s code branch — the panel header shows ⎇ {branch}: the branch the team works on.
• Preparation: claim your roles — a table with each role, its owner and its status (free, pending approval, owned, turn). Buttons: Claim, Release and, for admins, Approve, Reject, Revoke and Assign to…. One person can hold several roles.
• Claims require admin approval — optional setting.
• Start project — when every role has an owner. The turn goes to the team’s first role.
• Members — members and admins (Make admin, Remove admin, Remove).
• Pending turn requests, with Hand the turn over or, for admins, Resolve as admin.
• Activity — who did what and when.
• While Enable collaboration, Check again or Disable collaboration work with git and the remote, a notice in the middle says what the app is doing (with Hide); if it fails, it shows the reason with Retry and Close, and if a minute passes without an answer, it says git is taking too long.
• Working mode — Disable collaboration (goes back to solo mode; if roles have already been claimed, only an admin can do it, with confirmation; the collaboration state is saved in archive/ on the app branch in case it needs to be consulted).

Turns

• Only the person who has the turn can type in the chat; the others see the notice “Turn of {role} ({person}). You can read…”.
• When a role proposes continuing with a role owned by another person, the button is Hand off to {role} ({person}): the app asks for confirmation, adds the turn’s conversation to the shared log (sessions/ on the app branch), pushes your code branch to the remote, hands off the turn and locks your chat.
• The person receiving the turn gets a system notification (“Your turn”) and the notice in the chat. When their turn starts, the agent receives the context: who is operating, which documents were produced in the previous turn and where the shared log is.
• Request turn — with the chat locked, you can request the turn for one of your roles, with a required reason. The person who has the turn approves or rejects it; an admin can resolve it if they do not respond.
• The active role and the flow step travel with the turn: when the turn moves to another machine, every machine marks the same step and the same role, and while someone holds the turn their step changes show up on the others.
• The code branch travels with the turn: if the person with the turn switches to or creates a branch (for example sprint/NN-x when a sprint starts), the other machines switch to it on their own and say so in the chat. If that branch is not on the remote yet, or you have local changes, your machine says so in the chat and stays on its branch; it tries again on its own.
• The Talk on the side chat works without having the turn: it does not ask for it, does not block anyone and is not added to sessions/. The requests you save travel with the next push of the project.
• The app syncs with the remote every few seconds and when you click the sync indicator, and pushes the changes of each turn.

Credentials

If the repository uses HTTPS and git has no saved credentials, the app asks for a Username and an access token (with links on how to create one in Bitbucket, GitHub and GitLab). The app never stores the token: it hands it to git once and, if you tick Remember, the system credential manager keeps it. With SSH this is not needed.