switchroom-architecture

name	switchroom-architecture
description	Explains how switchroom works internally — config cascade, profiles, settings resolution, agent lifecycle, plugin system. Use when the user asks 'how does switchroom work internally', 'how does the cascade decide', 'which settings apply', architecture, design, or internals. Do NOT use for onboarding or getting-started questions ('how do I get started', 'I'm new to switchroom', 'bootstrap from scratch', 'set up for the first time') — those belong to switchroom-install.
user-invocable	false

Switchroom Architecture Overview

Switchroom is a multi-agent orchestrator built on Claude Code. It manages multiple Claude agents, each running as a persistent process with its own Telegram bot, memory collection, and configuration.

Key concepts

One switchroom.yaml to rule them all. All agents are configured from a single file using a three-layer cascade. See cascade.md for full merge semantics.

Agents as Docker containers. Each agent runs as a long-lived claude process inside its own container (switchroom-<name>), supervised by Docker Compose with restart: unless-stopped and a healthcheck. The start.sh script sets environment variables and execs into claude. Claude Code handles session persistence and tool execution.

Telegram as the primary interface. The switchroom-telegram MCP plugin connects Claude Code to Telegram, providing 10 tools for message handling. See telegram.md for details.

Hindsight for memory. Cross-session memory uses the Hindsight MCP server — a semantic vector store with knowledge graphs, mental models, and directives. Each agent has its own named collection.

Skills as reusable behavior. Shared skills live in ~/.switchroom/skills/ (or switchroom.skills_dir). Scaffold symlinks selected skills into each agent's skills/ directory. Claude Code loads them at session start.

Directory layout

~/.switchroom/
├── switchroom.yaml              # master config
├── vault.enc               # encrypted secrets
├── skills/                 # global skills pool (symlinked per agent)
│   └── <skill-name>/
│       └── SKILL.md
└── agents/
    └── <name>/
        ├── start.sh        # launcher (sets env, execs claude)
        ├── settings.json   # Claude Code settings
        ├── .mcp.json       # MCP server config
        ├── CLAUDE.md       # agent identity (never overwritten by reconcile)
        ├── skills/         # symlinks to ~/.switchroom/skills/<name>/
        ├── .claude/
        │   └── agents/     # sub-agent definition files
        └── telegram/
            ├── history.db  # SQLite message buffer
            └── access.json # per-agent access control

Lifecycle

1. switchroom agent create <name> — scaffold agent from switchroom.yaml
2. switchroom apply — write ~/.switchroom/compose/docker-compose.yml
3. docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d — start the container
4. Claude Code boots, loads CLAUDE.md + skills + .mcp.json
5. MCP servers connect (Hindsight, switchroom-telegram, others)
6. Telegram plugin polls for messages
7. User sends message → plugin fires UserPromptSubmit hook → Claude responds
8. switchroom agent reconcile <name> — re-apply switchroom.yaml (no CLAUDE.md touch)

Deep dives

• cascade.md — three-layer config cascade semantics
• sub-agents.md — delegation patterns and model routing
• telegram.md — enhanced Telegram plugin features