> ## 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.
# Using the AI agent
> Chat with AI to build your BRICKS application
The AI agent is the core of CTOR. It can read and write files, edit code, run shell commands, and search your project — all through a chat interface.
This page covers **project sessions**, scoped to a single BRICKS app. For workspace-level workflows like creating a new project, see [Start chat](/ctor/guide/main-chat).
## Create a session
1. Select an app in the sidebar
2. Click **New Session**
Sessions are stored persistently and auto-titled based on your first message. Each session maintains its own conversation history and model selection.
## Choose a model
Click the **model selector** in the input bar to pick an AI model. Models are grouped by provider:
* **Anthropic** — Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5
* **OpenAI** — GPT-5.3 Codex, GPT-5.2 Codex, GPT-5.2, GPT-5.1 Codex Mini
* **OpenAI Codex** — GPT-5.3 Codex, GPT-5.2 Codex
* **Google** — Gemini 3 Flash, Gemini 3 Pro
* **GitHub Copilot** — Multiple models from various providers
* **OpenAI Compatible endpoints** — Custom endpoints with per-endpoint model lists (Ollama, vLLM, LM Studio, etc.)
Only providers with configured API keys appear in the list. See [settings](/ctor/reference/settings) to configure your API keys.
## Set thinking level
Click the **thinking selector** next to the model selector to control the agent's reasoning depth:
| Level | Budget | Use case |
| ----- | ------------ | ------------------------------------------- |
| Off | — | Fast responses, simple tasks |
| High | \~16k tokens | Most tasks, good balance of speed and depth |
| Max | \~32k tokens | Complex reasoning, architecture decisions |
**Max** thinking is only available on models that support extended thinking: Claude Opus 4.6, GPT-5.3 Codex, GPT-5.2 Codex, and GPT-5.2.
## Send a message
Type your message in the input bar and press **Ctrl+Enter** (or click the send button). Use **Shift+Enter** for a new line.
The agent streams its response in real-time. You can see:
* **Text responses** with full markdown rendering and syntax highlighting
* **Thinking blocks** showing the model's reasoning process (expandable, requires [Show Thinking Content](/ctor/reference/settings#advanced))
* **Tool calls** displayed as expandable blocks with the tool name and arguments
* **Tool results** showing the output of each tool execution
Click **Abort** to stop a running response at any time.
## Mention files
Type `@` in the input bar to search for files in your project. Select a file to include its path in your message, giving the agent context about which files to work with.
* Browse directories by typing `/` after a folder name
* Navigate with arrow keys and select with **Enter** or **Tab**
* Up to 20 results are displayed
## Use skills
Type `/` in the input bar to trigger skill command autocomplete. Selecting a skill inserts a `/skill-name` reference into your message.
The selected skill appears as a removable pill in the input bar. The reference is sent as ordinary text; the agent decides whether to load the skill based on its description and what your request needs.
See the [skills reference](/ctor/reference/skills) for more details on creating and managing skills.
## Attach images
Click the image attachment button or paste an image from your clipboard. Supported formats: PNG, JPG, JPEG, WebP, GIF.
Images are sent to the model as base64-encoded content alongside your text message.
If your model has no image support, set a [fallback vision model](/ctor/reference/settings#fallback-vision-model) in settings. CTOR then uses it to describe each attachment as text, so the attachment button stays available even on a non-vision model.
## Voice input
Dictate messages instead of typing them. Turn on **Voice Input** in [**Settings** > **Advanced** > **Experimental features**](/ctor/reference/settings#experimental-features) first. It uses Apple Speech, so it needs macOS 26 or newer and microphone access — the toggle and button only appear on supported Macs.
Once enabled, a microphone button appears in the input bar:
* **Click** the button to start dictating, then click it again to stop.
* Or **press and hold** the button to dictate, and release to stop.
Your speech is transcribed into the input bar in real time. Review and edit the text, then send the message as usual. Pick the recognition language with **Voice Language** in settings; it defaults to the app language.
## Inspect the messages
Turn on **Show Messages Button** in [**Settings** > **Advanced**](/ctor/reference/settings#advanced) to add a **Messages** button to the input bar. Click it to open the **Messages Detail** panel, which shows the messages exchanged with the model for the current session, split into a **Main Agent** tab and one tab per active [sub-agent](#sub-agents).
Export the messages with the **Markdown** or **JSON** button in the panel header — CTOR opens a native save dialog to choose where to write the file.
## Tool calls and approval
The agent has six built-in tools: `read_file`, `write_file`, `edit_file`, `bash`, `glob`, and `grep`.
When the agent runs a `bash` command, you see an approval prompt:
* Click **Run** to execute the command
* Click **Reject** to deny execution
Enable **auto-approve bash commands** in **Settings** > **Agent** to skip the approval prompt for all bash commands.
Commands that match [dangerous patterns](/ctor/reference/sandbox#dangerous-command-detection) — `sudo`, `rm -rf`, history-rewriting `git`, `curl ... | sh`, and more — always show the prompt with a red border and a **Dangerous** label, even when auto-approve is on or the project is sandboxed.
If you have [MCP servers](/ctor/reference/mcp) configured, their tools are also available to the agent alongside the built-in tools.
## TypeScript language server tools
Turn on **Language Server Tools** in [**Settings** > **Advanced** > **Experimental features**](/ctor/reference/settings#experimental-features) to give the agent an in-process TypeScript language service per project. The toggle is off by default; when it is on, the agent can get type and syntax diagnostics for a file or the whole project, jump to where a symbol is defined, and list every reference to it.
After every `edit_file` or `write_file` on a `.ts`, `.tsx`, `.cts`, or `.mts` source, CTOR also runs diagnostics on the touched file automatically and surfaces the result in the tool block:
* An **error / warning count chip** in the collapsed header (e.g. `2 errors`) so you can spot problems without expanding the block
* A **per-line list** under the diff when expanded, showing `L:`, severity, the `TS`, and the message
The agent reads the same diagnostics in the tool result text and is instructed to fix them before declaring the task done. The language service is project-scoped, lazily created on first use, and rebuilds when `tsconfig.json` changes. With the toggle off, edit and write results are byte-identical to before.
## Workspace profile
A pill next to the [sandbox-mode](/ctor/reference/sandbox) selector shows which BRICKS workspace the agent is operating against. In a project chat the pill is read-only — CTOR matches the project's `workspaceId` to one of your authenticated [profiles](/ctor/guide/authentication#multi-profile-support) and falls back to the active profile when no match exists.
To run the agent against a different workspace, switch profiles from **Settings → Account** or from the [main chat](/ctor/guide/main-chat#switch-workspace-profile) input bar before opening the project.
## Fork a session
Click **Fork** at the bottom of the last assistant message to duplicate the current session into a new one. CTOR copies the full conversation history, appends " (fork)" to the title, and switches to the new session immediately.
A **Forked from {title}** divider marks the boundary between copied history and new messages so you can see where the fork started, even with the sidebar collapsed.
The button is hidden while the agent is streaming or waiting for tool approval — a fork must not capture a half-finished turn.
Forking is available in both project sessions and main chat sessions.
## Sub-agents
The agent can delegate tasks to specialized sub-agents. Sub-agents run with a focused set of tools and instructions, making them ideal for scoped tasks like codebase exploration or code review.
You can manage sub-agents from the sidebar. See the [sub-agents reference](/ctor/reference/sub-agents) for details on creating and configuring them.
## Local devices
Click the **Local Devices** button in the input bar to scan for [BRICKS Foundation](/foundation) devices and [BRICKS Buttress](/buttress) servers on your local network. The dialog runs both scans in parallel — a failure on one side doesn't blank the other's list.
Foundation device rows show address, version, and badges:
* **This workspace** — the device is bound to the same workspace as the current project
* **CDP** — the device supports the Chrome DevTools Protocol
CDP-capable rows also have a **DevTools** button. Click it to open that device's Chrome DevTools inspector as a tab in the [right panel](/ctor/reference/right-panel#devtools) — enter the device passcode first if prompted. For the foreground project's running preview, DevTools docks into the [Preview tab](/ctor/reference/preview#dock-the-previews-devtools) instead.
Buttress server rows use a distinct violet accent and their own badges:
* **JWT required** / **open** — whether the server is bound to a workspace and requires a workspace JWT
* **verified** / **UDP only** — whether the HTTP `/buttress/info` probe succeeded, or only the UDP announcement was seen
* **This workspace** — the server is bound to the same workspace as the current project
Click any card to toggle its selection — multi-select is supported, but selection is mutually exclusive across kinds (picking a Buttress server clears any Foundation selection, and vice versa).
The footer button changes based on what's selected:
* **Foundation devices** → **Inspect** or **Bind** inserts a `/bricks-cli` prompt that the [bricks-cli skill](/ctor/reference/skills#bricks-cli) runs. **Bind** associates the app with the selected device(s) and fast-ships the latest compiled config — no new release.
* **Buttress servers** → **Ask Agent to integrate** inserts a `/bricks-ctor` prompt with each selected server's identity, workspace match status, and announced generator caps. The [bricks-ctor skill](/ctor-pkg/skills) carries the integration rules — model recommendations per generator type, the canonical auto-discovery `buttressConnectionSettings`, and the iOS Simulator caveat (UDP discovery only works on real devices).
## Next steps
Ship your application to the BRICKS server.