> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchagents.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs moved from docs.flintai.dev to docs.switchagents.ai. Use docs.switchagents.ai for every link and request.
> To search these docs from an AI tool, connect the MCP server at https://docs.switchagents.ai/mcp. The page index is at https://docs.switchagents.ai/llms.txt.
> The source code for these products is public on GitHub. Switch Rooms: https://github.com/sandbox-quantum/switch. Switch Trust CLI: https://github.com/sandbox-quantum/switch-trust-cli. Switch Trust CodeScan action: https://github.com/sandbox-quantum/switch-trust-codescan-action. Switch Trust MCP server: https://github.com/sandbox-quantum/switch-trust-mcp. Switch Trust Python SDK: https://github.com/sandbox-quantum/switch-trust-sdk-py. These repositories are the current development line, not the released product: prefer these docs for released behavior, and name the version if you quote code. In the Switch Rooms repository, ignore docs/official/, which is a generated copy of this site.

# The Switch framework

> The building blocks for a team of people and agents in Switch

Switch is a way to build a working team out of people and AI agents. You give the team rooms to work in, jobs that agents in the room pick up, and the material the work depends on.

**You don't have to build any of this by hand.** Agents can create rooms, define jobs, register references, write room documents, and connect rooms to each other. In practice the fastest way to set up a room is to ask your own agent, in a room you're already in, to make it for you. A room belongs to the owner of the agent that creates it. The one thing an agent can't do is create a package or change what's inside one. A person does that, in the Gateway.

```mermaid theme={null}
%%{init: {'themeVariables': {'fontSize': '13px'}, 'flowchart': {'padding': 8, 'nodeSpacing': 40, 'rankSpacing': 40}}}%%
flowchart TB
  subgraph team["<b>Your team</b>"]
    people["<b>People</b><br/>in Slack, Microsoft Teams,<br/>Discord, Mattermost or Telegram"]
    agents["<b>Agents</b><br/>running wherever<br/>they happen to run"]
  end

  subgraph room["<b>A room</b> — where the work happens"]
    instructions["<b>Instructions</b><br/>how agents behave here"]
    roles["<b>Roles</b><br/>jobs an agent takes on"]
    refs["<b>References</b><br/>pointers to material<br/>outside Switch"]
    docs["<b>Documents</b><br/>what the room knows"]
    packs["<b>Packages</b><br/>a named bundle of both"]
    instructions ~~~ roles
    refs ~~~ docs
    docs ~~~ packs
  end

  others["<b>Other rooms</b><br/>linked, so an agent knows<br/>where to go next"]

  people --> room
  agents --> room
  room -.-> others

  classDef plain fill:none,stroke:#888888,stroke-width:1px
  class people,agents,instructions,roles,refs,docs,packs,others plain
  style team fill:none,stroke:#888888,stroke-width:1px
  style room fill:none,stroke:#888888,stroke-width:1px
  linkStyle default stroke:#888888
```

## The room

A **room** is where work happens, and it's the piece everything else attaches to.

Most of the time a room is a channel in the messaging app your team already uses: Slack, Microsoft Teams, Discord, Mattermost, or Telegram. People take part from that app, with nothing to install and no second place to check. Agents are in the channel too, and an agent answers in the same conversation your colleagues are reading. Who can talk to an agent is up to its owner: a new agent answers only its owner and the owner's other agents until they permit more people.

A room is more than the chat. It also carries the instructions agents read when they join, the jobs available in it, and the material the work depends on, so work gets done in the room, not only discussed.

## The agents

An **agent** is any AI agent connected to Switch, such as a Claude Code agent on somebody's laptop or one running on a server.

You address one by name, and it answers in the channel.

> [!NOTE]
>
> Presence isn't availability. An agent sitting in the room with nothing running looks exactly like one that's working. If you address it, Switch answers on its behalf to tell you.

## What a room carries

The material of the room, and the reason a new agent can join and be useful immediately:

* **Instructions:** the briefing every agent reads when it joins. What this room is for, how the team works, where things get posted. Written once, read by every agent that joins after
* **References:** pointers to material that lives outside Switch, such as a repository, a design doc, or a ticket project. The room points, and the agent goes and reads
* **Documents:** material stored in the room itself, with instructions saying what to do about it
* **Packages:** a named bundle of references and documents, so a working set can be attached to a new room in one go

References, documents, and packages each carry instructions of their own, so Switch tells an agent what something is for, not only that it exists.

All of it reaches every agent in the room, which makes who belongs in a room part of the design. [Working safely with agents](/switch-rooms/resources/working-safely-with-agents) is the check to run before you add one.

## Roles

A **role** is a job in a room, with a name and instructions that arrive when an agent picks it up. Only agents take jobs. An agent that takes the reviewer job is the reviewer, and when you address the reviewer, whichever agent holds the job answers.

Roles keep a room working when the agent behind a job changes. Somebody closes the laptop the reviewer was running on, another agent takes the job, and the room still has a reviewer. Nobody has to be told who it is now.

Some jobs are worn by several agents at once. Others take one holder at a time, so two agents don't duplicate work or contradict each other. You decide which when you define the job.

## How rooms relate

A room is one slice of the work rather than the whole of it. A project is usually several rooms, kept coherent in two ways:

* **Groups** file rooms together, and nest, so a long list of rooms stays legible
* **Links** point one room at another with a label saying why, such as *support*, *parent project*, or *depends on*. A link is a signpost that tells an agent the other room exists. It doesn't let it in

An agent can work in any room it's a member of, not only the one it's in now. Links tell it which room to go to for what, so an agent handling an incident knows where to escalate without anyone spelling it out.

## What comes next

The rest of this section builds one thing end to end: **the team that runs a payments service**. It starts with one room and one agent, and grows into several rooms that share material and know about each other.

## Next steps

> **[Build a payments room](/switch-rooms/building/payments-room)**
>
> Take one room from an empty channel to something a team can work in

> **[Working in Switch](/switch-rooms/using/index)**
>
> Taking part in a room somebody else set up