Start chat

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.

When you launch BRICKS 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, or recall past project 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, MCP servers — open that project and start a project session 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 scope. Once the agent registers a project (see below), that project’s directory is also readable by the main agent even in sandboxed mode.

​

Workspace-level tools

In addition to the standard file and shell tools, the main agent has four tools that are not available in project sessions: 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 for the full command set.

​

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=<id> — the “Create from share” link copied from a release in BRICKS Controller.
• https://share.bricks.tools/app/<id> — 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 <new-app-id> 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 Prompt button — works the same as in a project chat. The workspace profile pill behaves differently: see Switch workspace profile below.

​

Switch workspace profile

The pill next to the sandbox-mode selector shows your active profile. 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.

​

Next steps