Using the AI agent

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.

​

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 to configure your API keys.

​

Set thinking level

Click the thinking selector next to the model selector to control the agent’s reasoning depth:

​

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)
• 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 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 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 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 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. 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

If you have MCP servers 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 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<line>:<col>, severity, the TS<code>, 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 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 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 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 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 for details on creating and configuring them.

​

Local devices

Click the Local Devices button in the input bar to scan for BRICKS Foundation devices and BRICKS 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 — enter the device passcode first if prompted. For the foreground project’s running preview, DevTools docks into the Preview tab 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 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 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