> ## Documentation Index > Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt > Use this file to discover all available pages before exploring further. # Start chat > Land on the main chat to scaffold a new project or run workspace-level workflows When you launch [BRICKS](https://bricks.tools) CTOR for the first time, you land on the **main chat** — a project-agnostic agent that helps you scaffold a new BRICKS app, list local devices, browse activity logs, recall past chat sessions, or orchestrate other sessions, all without opening a project first. Once you create or open a project, you can switch into a project-scoped chat for code-level work. Until then, the main chat is your starting point. ## When to use the main chat Reach for the main chat when the work is not tied to a single project: * Spinning up a new app from scratch and you do not yet have a directory for it * Asking which devices are on the network or what they have been logging * Searching across past chats to remember a decision made weeks ago * Running ad-hoc `bricks` CLI checks (`bricks doctor`, `bricks device list`, etc.) For edits inside a specific project — code changes, deployment, the [Preview pane](/ctor/reference/preview), MCP servers — open that project and start a [project session](/ctor/guide/agent-usage) instead. ## Where it lives The sidebar splits into two collapsible sections: * **Projects** — your registered BRICKS projects. Click **+** to register a project from disk. * **Chat** — main-chat sessions. Click **+** to start a new main chat. A horizontal divider separates the two sections so you can scan them at a glance. Click either section header to collapse it; CTOR remembers the state between launches. ## Start a main chat 1. Open CTOR. If no session is active, an empty **Main Chat** screen appears with a centered input bar. 2. Type your request — for example, *"Create a hello-world BRICKS app for me"* — and press **Ctrl+Enter**. 3. CTOR creates the main session on first submit and the chat begins. You can also click **+** next to the **Chat** header in the sidebar to start a new main session at any time. ## The main workspace The main agent operates inside `~/bricks-ctor`, a top-level directory you can browse with your normal file manager. Anything the agent writes — for example, projects scaffolded with `bricks app ctor-init` — lands here unless you tell it otherwise. This directory acts as the agent's working root for sandbox, file mentions (`@`), and the [skills](/ctor/reference/skills) scope. Once the agent registers a project (see below), that project's directory is also readable by the main agent even in sandboxed mode. Point the main workspace at a different location — for example, an external volume or a synced folder — from [Settings → Agent → Main chat directory](/ctor/reference/settings#main-chat-directory). Changes apply mid-session without a restart. ## Workspace-level tools In addition to the standard file and shell tools, the main agent has workspace-level tools that are not available in project sessions: | Tool | Purpose | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `open_created_project` | Register a project directory (must contain `application.json`) so it appears in the sidebar. Optionally writes a `CONTEXT.md` hand-off note. | | `list_projects` | List the projects currently registered in the sidebar. | | `query_sessions` | Search saved chat sessions by title (optionally including message bodies) and return ranked matches, or omit the query to list recent sessions. Optionally filtered by project. | | `read_session` | Read a saved session by id and return a compact transcript. Works for both project and main-chat sessions. | | `archive_session` | Archive a saved session so it is hidden from the sidebar but remains recoverable from **Settings → Archive**. | | `new_session` | Create a new main-chat or project-scoped session, send its first message, and receive a completion report back. See [session orchestration](#session-orchestration). | | `send_session_message` | Send a follow-up, steer a running session, or undo-and-resend to an existing session. | | `stop_session` | Stop a running session by id. | The main agent uses the `bricks` CLI for BRICKS-specific operations such as `bricks app ctor-init` (create a project), `bricks device list` and `bricks device monitor` (inspect devices), and `bricks activity-log` (audit history). See the [BRICKS CLI reference](/cli/commands) for the full command set. ## Session orchestration The main chat can spawn and manage other chat sessions without leaving the current conversation. This lets you delegate focused tasks — for example, asking a project session to refactor a module — while keeping the main chat as the coordination hub. ### Spawning a session Call `new_session` with a title and first message. Omit `projectPath` (or pass `MAIN`) to create another main-chat session; pass a project directory path to create a project-scoped session for that project. The tool returns immediately — the target session runs in the background. ### Sending to an existing session Call `send_session_message` to send a follow-up message to a session that has already finished or is still running. Set `steer` to `true` to redirect a currently running session. The optional `undo_messages_index` parameter lets you roll back to a specific user message before sending. ### Stopping a session Call `stop_session` to abort a running session. The session history is preserved. ### Completion reports When a target session finishes (or is stopped), a **Session report** message is automatically queued back into the main chat so the agent can inspect the result and continue. While a report is pending, a **Session report queued** indicator appears above the input bar. You can cancel a pending report by clicking the **Cancel** button on the indicator. ## Clone a shared app from a URL Paste a share URL into the main chat and the agent clones the source app into your workspace. Two URL shapes are recognized: * `https://control.bricks.tools/#/create-share-app?application_id=` — the "Create from share" link copied from a release in [BRICKS Controller](/controller/applications#releases-and-sharing). * `https://share.bricks.tools/app/` — the public share page link. The agent extracts the source app id from the URL, lists the public releases via `bricks app share-info`, asks which one to clone (with optional name and description), and then creates the new app with `bricks app share-new`. The new app belongs to the workspace of your active profile — switch profiles first if you want it created elsewhere. After the new app is created, the agent offers to scaffold a local project for it — either by re-running `share-new --init -y` or by calling `bricks app ctor-init ` in the main workspace, then registering the project so it appears in the sidebar. ## Created projects banner Whenever the main agent registers a project on disk via `open_created_project`, a **Created projects** card appears at the bottom of the chat. Each card shows the project name, app id, and stage. Click **Start session** to open that project and begin a project-scoped chat — CTOR opens the project, selects it in the sidebar, and creates a fresh session in one step. ## Hand-off context If the main chat scaffolded the project, the agent can persist a summary of the conversation as `CONTEXT.md` at the project root and add a `@CONTEXT.md` reference to the project's `AGENTS.md` (or `CLAUDE.md`). The first project-scoped session then loads that context automatically, so you do not have to re-explain what was decided in the main chat. The marker is idempotent — running the tool twice does not duplicate the link. ## Skills, sub-agents, and MCP The main chat uses a reduced surface compared with project sessions: * **Skills** and **sub-agents** are available, but only the bundled and global tiers — project-local skills and agents are intentionally hidden because no single project is in scope. * **MCP servers** are not exposed in the main chat. * The **Preview** button is hidden because preview is project-only. Everything else — model selector, thinking level, sandbox mode, file mentions, image attachments, the **Local Devices** dialog, and the **Messages** button — works the same as in a project chat. The workspace profile pill behaves differently: see [Switch workspace profile](#switch-workspace-profile) below. ## Switch workspace profile The pill next to the sandbox-mode selector shows your active [profile](/ctor/guide/authentication#multi-profile-support). Unlike a project chat — where the pill is read-only — the main chat turns it into a dropdown when you have more than one authenticated profile. Click it to pick the workspace the main agent should operate against. Switching the profile updates the `BRICKS_PROFILE` env var that CTOR passes to the bundled `bricks` CLI and tool environment, so the next turn's system prompt and command output reflect the selected workspace. If the chat already has messages, the dropdown requires a two-step confirmation — the first click flags your target profile (the row turns orange and the helper text reminds you that switching rebuilds the agent context), the second click within 3 seconds confirms the switch. This keeps an in-flight session from silently swapping its profile mid-turn. ## Next steps Open or create a project to dive into project-scoped work. Learn the chat surface, shared by project and main sessions.