Skip to main content
The AI agent has nine built-in tools for interacting with your project and the preview pane. These tools are available in every session. An additional tool, spawn_process, is available when background processes are enabled.

​
read_file

Read the contents of a file. Supports text files and images.
ParameterTypeDescription
pathstringRelative path to the file from the project root
  • Maximum file size: 1 MB for text files, 5 MB for images
  • Supported image formats: JPG, PNG, GIF, WebP
  • Images are returned as inline attachments for the model to view
  • Image files are validated by magic bytes before sending

​
write_file

Create or overwrite a file with new content.
ParameterTypeDescription
pathstringRelative path to the file
contentstringThe content to write
  • Automatically creates parent directories if they don’t exist
  • Scoped to the project directory

​
edit_file

Replace a specific string in a file.
ParameterTypeDescription
pathstringRelative path to the file
old_stringstringThe exact text to find
new_stringstringThe replacement text
  • old_string must match exactly once in the file
  • Fails if zero or multiple matches are found

​
bash

Execute a shell command in the project directory.
ParameterTypeDescription
commandstringThe shell command to run
timeoutnumberTimeout in milliseconds (default: 30000)
  • Default timeout: 30 seconds
  • Maximum output: 1 MB
  • Runs in the project root directory
  • Requires user approval unless auto-approve is enabled in settings

​
glob

Search for files matching a glob pattern.
ParameterTypeDescription
patternstringGlob pattern (e.g., **/*.ts, src/**/*.json)
  • Automatically excludes node_modules, .git, and dist directories
  • Returns a list of matching file paths

​
grep

Search file contents for a regular expression pattern.
ParameterTypeDescription
patternstringRegex pattern to search for
includestringOptional glob filter for file types (e.g., *.ts)
  • Returns the first 50 matching lines with file paths and line numbers
  • Equivalent to grep -rn

​
preview_open

Open the embedded Preview pane for the current project. This tool takes no parameters.
  • Starts compilation (bun typecheck + bun compile.ts) and a CDP server in the background
  • Writes .bricks/devtools.json so bricks devtools can discover the running preview
  • The pane takes UI space away from the chat — the agent should only open it when relevant to the current task

​
preview_close

Close the Preview pane for the current project. This tool takes no parameters.
  • Stops compilation and tears down the CDP server
  • Also hides the Preview UI from the user — the agent should only call this when you’ve indicated you’re done reviewing

​
preview_status

Report whether the Preview pane is currently running for the project. This tool takes no parameters.
  • Returns JSON with running, port, stage, previewUrl, attached, and lastError
  • Used by the agent to check the pane’s state before opening or closing it

​
spawn_process

Spawn a background child process. This tool is only available when Enable Background Processes is turned on in Settings > Advanced.
ParameterTypeDescription
commandstringShell command to execute
typestring"daemon" for persistent processes, "long-run" for processes that complete
Two process types are supported:
  • daemon — persistent processes such as development servers. The process runs in the background until you stop it manually.
  • long-run — processes that eventually finish. When the process exits, its stdout and stderr are injected back into the conversation so the agent can react to the result.
Running processes appear as a status bar above the input area. Each entry shows the process type and command, with a Stop button to terminate it. All processes for a session are automatically cleaned up when the session ends.

​
MCP tools

If you have MCP servers configured, their tools appear alongside the built-in tools. The agent can call MCP tools the same way it calls built-in tools.