# Multi-Project Multi-Agent

> AgentsRoom runs several AI coding agents, on several projects, in parallel, inside one window.

- Area: Desktop, mobile and web
- Plans: All plans
- Last checked against the product: 2026-09-28
- Web page: https://agentsroom.dev/docs/multi-project-multi-agent

## What it does

AgentsRoom runs several AI coding agents, on several projects, in parallel, inside one window. The left sidebar lists every project grouped by zone (Work, Personal, Side Projects, Freelance, Learning, or any zone you create by drag and drop). Opening a project shows its room: the agents on the left, the focused agent's terminal in the centre, the side panel (review, dev commands, browser, prompts) on the right. Every agent has a role with a fixed colour and avatar, its own terminal session that keeps running and keeps its scrollback while you work elsewhere, and a live status dot: pulsing yellow while thinking, green when done, pulsing red when it waits for you, grey when idle. Each project row aggregates how many agents are working, done or waiting, and takes the colour of the agent currently thinking, so activity is visible from the corner of your eye.

## Where to find it

- The projects home (no project selected) shows every project as a card; the sidebar shows them grouped by zone with live counters. Filters there sort by machine (**All machines**, **This machine**) and a **Duplicates** filter shows only projects with a duplicate name.
- Click a project to enter its room. The project row keeps its counters and colour while you are in another room.
- Title bar: since 2026-09-28 the **Recent agents** row lists the open agents of every open project, most recently opened first, grouped by project, to jump back in one click (see [Recent Agents](https://agentsroom.dev/docs/recent-agents.md)), next to the needs-input pill (see [Needs Input Inbox](https://agentsroom.dev/docs/needs-input-inbox.md)).

## How to use it

1. Open a project from the sidebar, add agents with **Add agent** (role, provider, model) or the **Quick agent** lightning button.
2. Give each agent a task in its composer. Switch project or agent at any time: sessions stay alive in the background.
3. Watch the sidebar: red pulse means an agent is waiting for you, the coloured left border and shimmer mean an agent is working.
4. Move a project to another zone by dragging its row; drop it on a new zone name to create one.

Keyboard navigation (Settings > Keyboard shortcuts > Project and agent navigation): Up / Down move between agents of the open project, Left / Right and Tab / Shift+Tab move between open projects, Cmd (or Ctrl) + Option + arrow does the same from inside a focused terminal, which otherwise keeps its arrows and Tab for the CLI. Only projects already open are cycled.

## Settings

- `projectAgentCycleShortcut` (global, Settings > Keyboard shortcuts, "Custom agent shortcut"): the chord that jumps to the next active agent; default Tab, add Shift for the previous one.
- `notificationSound` and `needsInputSound` (global, Settings > Notifications): play a sound when an agent finishes a turn or needs input.
- `sendNotificationsToPhone` (global, Settings > Notifications): mirror desktop notifications to the paired phone.

## Agent tools (MCP)

- `projects_list`: every project of the account, so an agent can read a sibling project's backlog, memory, skills or prompts with the `project` argument.
- `agents_list` / `agents_get`: the saved agents of a project and their configuration.
- `agents_list_live`: which agents currently have a live console, their status and what they are working on.
- `agents_spawn` / `agents_resume` / `agents_close`: open a new throwaway agent, bring a saved one back on its previous conversation, or end a console, in this project or in another open project.
- `usage_overview`: anonymous census of running consoles by status and provider, plus provider quotas.

## Providers

All providers, no difference: Claude Code, Codex CLI, GitHub Copilot CLI, Antigravity CLI, OpenCode, Aider, Grok Build, Mistral Vibe, Kimi Code, Amp, oh-my-pi, Freebuff, Devin and Cursor can run side by side in the same project. Colour and avatar follow the role, not the CLI; a provider mark sits on the avatar, and the card shows which CLI account an agent runs on when several are signed in.

## Mobile

Present. The iOS / Android app shows the same projects, agents, colours, statuses and counters through the end-to-end encrypted relay, receives push notifications for finished turns and blocked agents, and can start an agent, type in its terminal and answer its questions; the session itself runs on the desktop.

## Limits

- The number of agents is bounded by your machine and your provider quotas, not by AgentsRoom; 10 to 20 agents in parallel is common on a recent machine.
- Status is inferred from what the CLI prints and from the agent's own end-of-turn report; a CLI update that changes its screen text can occasionally delay a status change until AgentsRoom is updated.
- The project border takes the colour of the first thinking agent only; several simultaneous roles are not blended.
- Cross-project reads by agents are read-only; dev commands never cross projects.
- One folder, one row: a folder can only be opened once, and the list folds any extra row pointing at the same folder onto a single one when it loads. A row with no folder on this computer is not a duplicate, it is a repository of your account opened on another machine, and its badge names that machine ("On" followed by the computer's name).

## Common questions

- **Do my agents keep running when I switch projects?** Yes. Sessions live in memory with their scrollback and reattach when you come back.
- **How many agents can I run?** As many as the machine and your provider quotas allow; each agent is its own CLI process.
- **Can I change a role's colour?** Roles have fixed colours so they stay recognisable everywhere; a Custom agent can carry its own colour.
- **Two agents touch the same file, what then?** Enable a git worktree per agent so each works in its own copy and branch (see [Git Worktrees](https://agentsroom.dev/docs/worktrees.md)).
- **Can an agent look at another project?** Yes, read-only, through `projects_list` and the `project` argument of the read tools.
- **Why did the same project show up twice, or three times, in my sidebar?** Because the same folder had been registered under more than one identity on your account, usually after a folder was re-added or a project split, and deleting the extra rows brought them back at the next launch. The list now folds the rows of one folder onto a single one by itself, on the desktop and on the phone, and deleting a duplicate no longer removes the surviving project from your account. Update, and the extra rows go on the next launch.
- **My project only exists on another computer, is that a duplicate?** No. A project of your account whose folder is not on this machine is listed once with a badge naming the computer it lives on, and cannot be launched from here.

## Related

- [Split View](https://agentsroom.dev/docs/split-view.md): several agents on screen at once inside one project.
- [Open Space](https://agentsroom.dev/docs/open-space.md): every project and agent on one screen, with one composer.
- [Needs Input Inbox](https://agentsroom.dev/docs/needs-input-inbox.md): the red surfaces and the inbox for agents waiting on you.
- [Agent Status Tracking](https://agentsroom.dev/docs/agent-status-tracking.md): how the live status is detected.
- [Multi-Provider Support](https://agentsroom.dev/docs/multi-provider.md): mixing CLIs in the same room.
- [Git Worktrees](https://agentsroom.dev/docs/worktrees.md): conflict-free parallel work on one repository.
- [Mobile Companion](https://agentsroom.dev/docs/mobile-companion.md): the same grid on the phone.