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, and grant microphone access. 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.

​

Choose a speech engine

CTOR transcribes with one of two engines:

• Apple Speech — runs on-device with nothing to download, and needs macOS 26 or newer.
• Whisper — runs on macOS, Windows, and Linux. It transcribes on-device too, but you download a runtime and a model first.

On macOS 26 or newer both are available, and a Speech Engine row in settings lets you choose; Apple Speech is the default there. Every other platform uses Whisper.

​

Set up Whisper

Whisper needs two downloads, each with its own row in Settings > Advanced > Experimental features:

1. Whisper Runtime — the speech recognition engine. Click Download and watch the progress bar; Cancel stops it. The row shows Installed when it is ready, and offers Update when a newer runtime ships.
2. Model Download — the model file selected under Whisper Model. Pick a size first: Tiny, Base, Small, Medium, or Large v3 Turbo. Bigger models transcribe more accurately but run slower and take more disk space. Base is the default.

Downloads are verified before they are installed. Remove deletes either one when you want the disk space back. On Windows and Linux, an Acceleration row picks which Whisper build to download — Auto, CPU, Vulkan, or CUDA. Auto detects the fastest option your machine supports and names it in the picker; choose CPU if an accelerated build misbehaves. macOS builds always use Metal, so the row does not appear there. If you click the microphone button before the runtime or model is installed, CTOR offers an Open Settings shortcut to finish the setup. With Whisper you can also set Voice Language to Auto (detect), which detects the spoken language as you talk instead of pinning it to one locale. Apple Speech needs a concrete language, so the option only appears while Whisper is active.

​

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.

​

Web research

The agent can search the web and read pages when a question reaches past what it already knows — current documentation, library versions, release notes, APIs, or a page you link in chat. Two capabilities cover this:

• Web search — the agent asks a research question and gets back a synthesized answer with the sources it was drawn from. Each result lists the search queries that were run and a numbered source list with the title and domain of every page cited.
• Reading URLs — the agent reads up to 20 public http(s) pages, including documentation and PDFs, and answers a question from their contents. It uses this to follow up on a source found by a search, or to digest a link you paste into the chat. Pages that are paywalled or that block automated readers are reported per URL instead of failing the whole call.

Research runs as a separate call on a fast model rather than on your conversation’s model, so a session on a premium model does not pay that model’s rates for each search. Results are read-only, so they never wait for approval and stay available in plan mode. Sub-agents inherit both capabilities. Requests are served by BRICKS AI, or by your own Vertex AI project when the conversation is running on the Vertex AI provider — in which case the search is billed to that project. If one route is unavailable, CTOR falls back to the other. When neither is configured, the capabilities are simply absent and the agent works without them. Turn them off with Web Search Tools in Settings > Advanced. The toggle is on by default.

​

Codemode

With codemode, the agent can write a short JavaScript program that calls its other tools, instead of making each call one at a time. It uses this to run independent calls in parallel, chain one result into the next call, or trim a large result down to the part that matters. Only what the script outputs reaches the conversation, so a large tool result doesn’t fill up the context. Scripts run in an isolated sandbox. A script has no file system, network, or timers of its own — everything it does goes through the agent’s tools, so command approvals, plan mode, sandbox rules, and your hooks apply to each call just as they would to a direct one. Scripts can also:

• Call tools from your MCP servers, including ones the agent hasn’t loaded into the conversation yet, after searching for them
• Generate images and run classifiers with the providers and API keys you’ve set up in Settings
• Keep small values from one script for the next. Saved values follow the conversation, so rewinding or forking a session rewinds them too

A few tools stay outside scripts because they need a turn of their own or start other work: asking you questions, plan approval, spawning sub-agents, and managing other sessions and schedules. The tool block shows the script and a live list of the calls it makes, each with its status and duration. Codemode is available to the main agent, project agents, and sub-agents. A sub-agent with a tools list in its agent file only gets it when codemode is listed. Turn it off with Codemode in Settings > Agent. The toggle is on by default.

​

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 Agents tab of the Plugins panel. See the plugins reference and 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
• workspace auth — the device supports workspace authentication

CDP-capable rows also have a DevTools button. Click it to open that device’s Chrome DevTools inspector as a tab in a panel. When you are signed into the device’s workspace, CTOR opens DevTools with workspace authentication automatically. When workspace authentication is unavailable and the device has a passcode set, CTOR falls back to a passcode prompt. When neither is available, CTOR tells you to set a passcode on the device or sign it into the workspace. For the foreground project’s running preview, DevTools docks into the Simulator 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’s left side always has an Open Devices panel button, which opens the Devices tab in the bottom panel — the same workspace device list, browsable without keeping this dialog open or selecting anything. The footer button on the right 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