Code Mode
Code Mode lets a Session write a short JavaScript program that calls its own tools. The program can loop, filter, and combine results before returning them to the model. For example, it can read forty files and return only the paths that still use an old API.
Configure new Sessions in Settings → All projects → Agents, using Code Mode’s Default and Exceptions sections.
When a Session uses it
Section titled “When a Session uses it”A Session with Code Mode has a codemode tool. The model chooses when to use
it, such as for a loop of file reads, repeated page checks, or several
Sessions handled alike. One call can still use the tool directly when that
route is available.
In chat, a program appears as one tool call. Its nested calls appear beneath it as activity rows.
What a program can and cannot do
Section titled “What a program can and cannot do”Each program runs in a fresh sandbox and can call only tools its Session already holds.
- It has no filesystem, network, process, environment, timers, or modules.
It reads files through
read. Shell commands use a directbashcall outside the program. - Every nested call uses the same Session’s authority and limits as a direct call. An existing confirmation can pause the program for your answer.
- Questions, secret requests, todos, and background shells are direct-only.
A program cannot call
codemodeitself. Browser tools, Session controls, Automations, and MCP management are callable when the Session holds them. - A run allows up to 200 nested calls, five minutes of active time, and 20 KiB of text output. Waiting for your answer does not count toward active time. Longer output is shortened and saved for the Session to read separately.
- Images stay outside the sandbox as handles. A run can attach up to eight images and 16 MiB of base64 image data. The result names omitted or unavailable pictures.
- Results that include web, Browser, MCP, or another Session’s content carry an untrusted-content notice, as direct calls do.
Stopping the turn cancels the program and its in-flight calls. A failed program does not undo completed calls, including writes.
Images from a program
Section titled “Images from a program”A nested image result contains handles in images. Attach one with image(),
or return the result to attach all its images:
// Use a tab id returned by browser_tabs.const shot = await tools.browser_screenshot({ tabId: "tab-1" });image(shot.images[0]);text(shot) prints the result as text without attaching its images.
In Default → Code Mode, choose how new Sessions receive their tools:
| Mode | What the model gets |
|---|---|
| Direct tools | Normal tools directly. A large MCP server can still add codemode, as described below. |
| Code and direct tools | codemode alongside normal tools. The model chooses per step. |
| Code only | Fully callable tool groups, such as web tools and small MCP servers, through codemode. Groups with a direct-only tool remain direct too. Browser and control groups also retain direct routes for older-build compatibility. |
If you have not set a global choice, the control shows Model defaults. Claude Haiku and Claude Sonnet default to Code and direct tools; other models default to Direct tools.
Use Exceptions → Add model exception to choose a model and override its mode. Remove an exception to return that model to the global choice or its built-in default.
Large MCP servers
Section titled “Large MCP servers”An MCP server with more than 20 enabled tools, or more than about 3,000 tokens
of tool definitions, uses Code Mode discovery. The model sees the server’s
name and tool count, then uses searchTools() and describeTool() inside a
program to find the tools it needs.
This also applies to Direct tools mode. When a large server gives that
Session codemode, the Session’s other callable tools are available from
programs too. Selecting fewer MCP tools can keep a server below the threshold.
Prefer direct tools
Section titled “Prefer direct tools”Choose Default → Code Mode → Direct tools and remove any exceptions that choose another mode. This changes the defaults for new Sessions; it does not remove Code Mode discovery for large MCP servers.