# Layouts

> A layout is a named arrangement of the screen for one kind of task: which buttons, tabs, chips and blocks of the interface are shown, and which buttons the input box keeps.

- Area: Desktop app
- Plans: All plans
- Last checked against the product: 2026-10-26
- Web page: https://agentsroom.dev/docs/ui-layouts

## What it does

A layout is a named arrangement of the screen for one kind of task: which buttons, tabs, chips and blocks of the interface are shown, and which buttons the input box keeps. Put a project on **Research** and the code review tabs, the dev servers and the databases step back while files, notes, prompts and the terminal stay; put it back on **Default** and your usual screen returns. Each project remembers its own layout: opening a project brings back the arrangement it was left on.

Layouts are saved on your account and follow you on every computer, and so does **Default**, your global arrangement: every project without a layout inherits it. Hiding something never turns the feature off, it only leaves the screen, exactly like [Interface Elements](https://agentsroom.dev/docs/interface-elements.md).

## Where to find it

- Project settings > **Layout** (the Project settings gear of the title bar, then **Layout** in the Workspace group): the place to pick the project's layout, create, rename or delete layouts. The **Configure** button at the end of each row, Default included, opens the window where you tick what that layout shows.
- In the title bar, right after the project name: a pill with the layout's name, only while the project uses a layout. Its menu switches layout, creates one (**New layout…**) and opens the Configure window of the layout in use (**Configure layout…**). On Default there is nothing in the title bar. A project opened in its own window has the same pill.
- Settings > **Interface elements**: a note above the surface cards says whether they change the layout of the project on screen or Default, with a **Project layout…** link to that project's Layout tab.
- The **Interface mode** window (the mode chip of the footer): the note at the bottom says the mode applies to all your projects, on all your computers, with the same **Project layout…** link for a finer, per-project arrangement.

## How to use it

1. Open Project settings (the gear of the title bar) and choose the **Layout** tab.
2. Under **Layout of this project**, pick a layout, or **Default** (tagged **Global**) for your global arrangement. The screen changes at once, for this project only.
3. To create one, choose **New layout…**, type a name and pick what it starts from: **Current screen** (what this project shows right now) or **Research** (hides code changes, tests and dev tools; files, notes, prompts and the terminal stay). **Create** saves it on your account and puts the project on it.
4. Choose **Configure** on a layout's row (a new layout opens there by itself). The **Configure “Research”** window lists the seven surface cards (**Title bar**, **Agents column**, **Dock**…) and the **Composer** buttons: open a card and tick or untick what the screen shows. A tick is saved at once, **Done** only closes the window. The line under the title says where a tick lands: **The boxes below change the “Research” layout, on all your computers and for every project that uses it.** or, on Default, **On Default, the boxes below change your global arrangement: every project without a layout, on all your computers.**

Each layout row has **Rename** and **Delete** buttons, the number of projects using it and **Configure**. Deleting a layout sends its projects back to Default, on every computer.

The usual places still edit the layout of the project on screen: right-clicking the footer, the right panel header or the dev command bar (the menu shows **Layout: Research** under its title), Settings > Interface elements and Settings > Composer. Once a project uses a layout, its pill in the title bar switches it in one click.

## Settings

- `uiLayouts` (global, Project settings > **Layout**, or the layout pill of the title bar): `{ layouts: { [layoutId]: { name, elements, composerHidden, createdAt } }, projects: { [repoProjectId]: layoutId } }`. `elements` has the shape of `uiElements`, `composerHidden` the ids of `composerHiddenActions`. A project missing from `projects` uses Default. Saved on the account and merged entry by entry: two computers changing different layouts or different projects never overwrite each other.
- `uiElements` and `composerHiddenActions` (global, saved on the account): the Default arrangement, inherited by every project without a layout, on every computer. A project on a layout ignores them until it goes back to Default.
- `uiMode` (Simple, Balanced, Full) is not part of a layout: saved on the account too, the same for every project and computer, it still folds its preset over whatever layout is on screen. See [Interface Modes](https://agentsroom.dev/docs/ui-modes.md).

## Agent tools (MCP)

- `settings_get` / `settings_set` on `uiLayouts`: list the layouts, create or edit one, put a project on a layout (`projects.<repoProjectId>`) or back on Default (remove its entry). Write a layout whole, every element true or false: the account merges entry by entry, so an element left out keeps its previous value.

## Providers

All providers, no difference: a layout only arranges the AgentsRoom window.

## Mobile

Not on the mobile companion: the phone has its own fixed layout, and the layouts saved from the desktop do not change it.

## Limits

- Up to 30 layouts per account. A name has 1 to 60 characters and must be unique, ignoring case.
- One starter, **Research**. Any other layout starts from the current screen.
- Default and the mode follow the account since 2026-10-26. After that update, the first computer that syncs hands its own arrangement and mode to the others; change them from any computer if you preferred another one.
- Two computers changing the same layout at the same moment: the last change wins for that layout. Same for Default, which is one arrangement.
- A layout holds the interface elements and the input box buttons only. Skills, MCP servers and connections stay in [Toolkits and memory mode](https://agentsroom.dev/docs/toolkits.md); theme, accent and fonts stay in Settings > Appearance.
- The layout belongs to the repository: several local copies of one repository share it. The Open space keeps the layout of the project named in the title bar.
- Same on macOS, Windows and Linux.

## Common questions

- **Can AgentsRoom switch to a research mode for some tasks?** Yes: open Project settings > **Layout**, choose **New layout…** and start from **Research**. The project switches at once and keeps it until you pick another layout.
- **Where do I choose what a layout shows?** Project settings > **Layout**, then **Configure** on the layout's row, or **Configure layout…** in the menu of the layout pill in the title bar. Open a card and tick what stays on screen.
- **Where did the Layout button go?** It only shows while a project uses a layout: the pill with the layout's name, next to the project name. On Default the choice lives in Project settings > **Layout**.
- **I unticked an element and another project changed too.** Both projects are on the same layout, and a change to a layout applies to every project on it, on every computer. Put one of them back on **Default** or give it a layout of its own.
- **Does a layout turn features off?** No. It only removes buttons, tabs and blocks from the screen. The search (⌘K), the menus and the shortcuts still reach everything.
- **What is the difference with Simple / Balanced / Full?** The mode sets how much of the cockpit you see, in every project; the layout sets what a project's task needs. They add up: Simple over Research shows only what both keep.
- **Can one project have a different layout on my laptop and on my desktop?** No. The layout of each project, Default and the mode are all saved on the account, so every computer shows the same screen.
- **Can I set one arrangement for all my projects and change only a few?** Yes. Default is your global arrangement: every project without a layout inherits it, on every computer. Give a layout only to the projects that need another screen; the others follow Default.
- **Does the Research layout add research tools?** No, a layout chooses what is shown, it adds no tool. Research skills and MCP servers are installed through [Toolkits and memory mode](https://agentsroom.dev/docs/toolkits.md).

## Related

- [Interface Elements](https://agentsroom.dev/docs/interface-elements.md): the per-element checkboxes a layout saves.
- [Interface Modes](https://agentsroom.dev/docs/ui-modes.md): Simple, Balanced and Full, folded over any layout.
- [Toolkits and memory mode](https://agentsroom.dev/docs/toolkits.md): skills, MCP servers and connections, which layouts do not carry.
- [Project Window](https://agentsroom.dev/docs/project-window.md): a project in its own window keeps its layout, its pill and its Project settings.
- [Appearance Customization](https://agentsroom.dev/docs/appearance-customization.md): theme, accent, fonts and zoom.
