Code Mode

Code mode is a way of using tools where the model writes code instead of requesting each operation separately. Instead of a catalog of individual tools, it gets one execution tool and a sandbox. What it sends back is a compact, executable plan.

This is the default. crawlio-browser starts in code mode with 7 tools; the same surface exposed one tool at a time is 150.

Code as a plan

A browser task is almost never one operation. To get evidence out of a page you navigate, wait for the network to settle, extract the DOM, capture requests, and take a screenshot. Each step depends on the one before it.

With one tool call per step, every intermediate result travels back through the model. The page title, the network entries, the DOM snapshot: the model reads each one and emits it again. You pay tokens for data that only feeds the next call.

In code mode that intermediate data stays in the sandbox. The model writes the whole sequence once:

await smart.navigate('https://example.com/pricing');
await smart.waitForIdle();
const page = await smart.extractPage();
return page.gaps.length ? { incomplete: page.gaps } : page.capture;

One round trip. The model sees the shaped result, not the six intermediate payloads that produced it. Loops, branching, filtering and error handling all happen where the data already is.

smart.extractPage() runs eight sub-captures in parallel. It returns a typed gaps[] for anything it could not get — evidence about the evidence, in the same call.

Progressive discovery

A large tool catalog is expensive before any work happens: every schema is loaded into context whether the task needs it or not.

Code mode inverts that. search queries the catalog by keyword and returns only the matching definitions, with their parameters:

await search('network');
// -> start_network_capture, stop_network_capture, get_network_requests, …

The model pulls in what the task needs, when it needs it. Cost stays roughly flat as the surface grows, because the surface is no longer something you pay for up front.

Measured on the serialized tools/list payload a client actually receives, code mode is 85 percent smaller than the full catalog.

The seven tools

Tool	What it does
`search`	Find commands by keyword. Returns names, descriptions, and parameter schemas.
`execute`	Run JavaScript against the browser bridge in a sandbox.
`connect_tab`	Pin a tab and start CDP capture. Pass `background: true` to avoid taking focus.
`observe`	Extension-resident observation: training runs, recordings, page monitors.
`get_job_result`	Collect the result of a backgrounded `execute`.
`list_jobs`	List running and finished jobs.
`cancel_job`	Stop a running job.

Work that outlives a single call goes to the background. execute with background: true returns a jobId and keeps running on the server. get_job_result collects it later.

Choose between code mode and direct tool calls

Use code mode when	Use full mode when
Steps depend on each other	The task is one or two known calls
You need loops, branching, or filtering	You want the client's tool picker to list every tool
You want to shape the result before it reaches the model	You are debugging and want to see exact parameters
The context budget is tight or shared with other servers	You want tool annotations (`readOnlyHint`, `destructiveHint`) visible

Full mode is one flag:

{
  "mcpServers": {
    "crawlio-browser": {
      "command": "npx",
      "args": ["-y", "crawlio-browser", "--full"]
    }
  }
}

Without the flag you are in code mode.

What the sandbox allows

bridge.send accepts a command when its type is a known tool name and the action policy allows it. Nothing about page access is withheld: browser_evaluate works. A short or invented name is refused, and the error reads like a permission problem when it is a naming one. search returns the real names.

The boundaries that are deliberate: the action policy, the destinations crawlio.api may reach, and response redaction (get_cookies returns [REDACTED]). The worker itself has no filesystem and no network.

Details, limits and the background-job flow are in the execute sandbox reference.

Next steps

Execute sandbox reference — everything available inside execute, and everything that is not
Method Mode — the higher-order methods you compose inside code mode
Tool Reference — the full surface, one tool at a time

Crawlio App exposes its own search-and-execute pair over its HTTP catalog. Same idea, different surface — see the App MCP overview.

PreviousSetup NextMethod Mode