Code mode

Code mode lets the model compose its tools with JavaScript. It can call several tools, loop over results, run independent work in parallel, and pass one tool’s output into another—all within one code_execute call.

This is useful when a task has a clear procedure: collect records from an MCP service, filter and aggregate them, save a report, or coordinate several jobs. The script handles the intermediate steps and selects what to show the model. That can reduce model round trips and keep large intermediate results out of its conversation context.

Enable code mode

Enable Code mode in a profile or in an idle session’s Session settings. Keep the other capabilities the task needs enabled too: code mode composes the session’s available tools. Ordinary tool calls remain available alongside code_execute, so the model can choose either approach.

For API configuration, the feature can use defaults:

{
  "features": {
    "codeMode": {}
  }
}

Under Customize limits, you can adjust:

Setting	Default	Meaning
Timeout	60,000 ms	Total time for one script, including tool calls and waits.
Max tool calls	128	Total calls the script can make.
Max outstanding calls	16	Pending tool calls allowed at once.

The JSON fields are timeoutMs, maxToolCalls, and maxOutstandingToolCalls. A script call can request a shorter timeout_ms; it cannot exceed the configured timeout. The maximum configurable timeout is 600,000 ms. By default, all otherwise callable session tools are available; advanced configuration can narrow them with allowedTools using logical tool IDs such as vfs.read_file.

Compose tools in a script

The model supplies the body of an async JavaScript function as the code argument to code_execute. It can use await, loops, conditionals, Promise.all, and Promise.allSettled. Each tools.tool_name(arguments) call returns a JavaScript promise for that tool’s result.

For example, suppose an attached workspace contains two JSON reports, each with numeric revenue and cost fields. A script can read both concurrently, calculate profit, and produce a downloadable summary:

const paths = [
  "/workspace/reports/january.json",
  "/workspace/reports/february.json",
];

const reports = await Promise.all(paths.map(async (path) => {
  const result = await tools.vfs_read_file({ path });
  const report = JSON.parse(result.text);
  return { path, profit: report.revenue - report.cost };
}));

const totalProfit = reports.reduce((sum, report) => sum + report.profit, 0);
text({ totalProfit, unprofitable: reports.filter((report) => report.profit < 0) });
await file({ json: reports }, { name: "profit-report.json" });

The model writes these scripts from the tool definitions it sees. Names and arguments follow the selected model’s tool format; for example, Anthropic’s VFS read tool is VfsRead. Available output JSON Schemas are included in tool descriptions to help the model process results correctly.

For MCP, use Lightspeed connects. Scripts can call tools exposed up front, or use mcp_find_tools and mcp_call for search-on-demand servers. Jobs and sub-agents work through the same tools as ordinary calls: job_run and agent_run wait for their results, while submitted work can return handles for later use with tools.await(...).

Select the output

Intermediate tool results are available to the script without automatically becoming output for the model. Use these helpers to select what it receives:

Helper	Purpose
text(value)	Emit a string or JSON value, such as selected records or a summary.
media(source)	Show a supported image or PDF to the model. Await this helper.
file(source, options)	Publish a downloadable file attachment. Await this helper.
return value	Supply a final JSON value separately from emitted output.

media() and file() accept content descriptors, full sha256: references, and recorded media: or file: handles. They also accept inline objects such as { text: "..." }, { json: value }, or { bytes: [...] }. A string means a content reference, so use an explicit { text: "..." } object for literal text. These helpers use the ordinary blob tools and count toward tool limits.

To show an image read from a workspace:

const image = await tools.vfs_read_file({ path: "/workspace/chart.png" });
await media(image.media);

Use workspace tools to save working files across calls, and blob references to pass stored content between tools. JavaScript variables are local to each execution.

Follow execution and failures

Lightspeed runs the script in its own workflow and routes its tool calls back through the session. Those calls use the existing tool execution machinery; individual effects retain their configured retry behavior. The transcript shows Run code, its source line count, and tool activity. Expand the call to inspect the script and result.

A failed tool call rejects its JavaScript promise. The script can handle it with try/catch or Promise.allSettled. If the script fails, the result reports the error and completed tool outcomes, retaining earlier selected output when available. Completed effects are not rolled back, and Lightspeed does not automatically rerun the whole script. The model can inspect the report and decide how to continue. Await work before finishing the script; unawaited calls are cancelled when it ends.