Code Mode runs small programs over tools supplied by the host. OpenCode's agent-facing execute tool runs Lua. The package also supports its existing JavaScript interpreter: CodeMode.make and CodeMode.execute default to JavaScript for compatibility. Set language: "lua" for Lua or language: "javascript" to pin JavaScript. Neither parser retries a failed program in the other language. Stored schedule checks remain JavaScript.

Rather than trying to sandbox arbitrary JavaScript, CodeMode only runs the language features we implement. Programs cannot directly access the network, filesystem, processes, or application APIs. They can interact with the outside world only through tools provided by the host, which can also limit execution time, tool calls, output size, and data.

The idea of code mode was originally introduced by Cloudflare. See their post to learn more about the concept and their isolate-based approach.

Writing a Lua program

local matches = search({ query = "order lookup" })
local order = tools.orders["lookup-by-id"]({ id = "order_42" })
return { id = order.id, needsAttention = order.status ~= "complete" }

Use the exact path returned by search; the input is a Lua table, not a JavaScript object literal. Calls wait for the tool's Effect in the execution's environment, so the next statement sees the result. Calls within one Lua program are sequential: there is no await, Promise.all, detached work, or parallel Lua task API. Independent executions still have separate state and can run concurrently.

Use an explicit return: only the first value is exported. Falling off the end or returning nil yields JSON null.
Tables with contiguous integer keys starting at 1 are arrays; tables with string keys are objects. {} makes an empty object; json.array() makes an empty array. Arrays and objects received from a tool keep their shape even when empty. Mixed-key, sparse, cyclic and non-data results cannot cross to the host.
nil removes a table field. Use json.null to keep a JSON null in a field or array slot.
Use local ok, result = pcall(tools.ns.lookup, { id = id }) to recover from an ordinary failed call. On failure the program sees a message, not a host exception. Interruption and resource exhaustion cannot be caught this way.
Only explicit capabilities can enter host code. Tools, search, bindings and extension results cross as plain data, never a host object, function, Promise or proxy. Declare Lua globals with Extension.lua({ name, globals }): each function returns an Effect producing JSON (or undefined), not an object with callable methods. In OpenCode fetch(url, init) returns data (body is text), not a JavaScript Response.

JavaScript compatibility

Only supported APIs are available. Programs can use the provided tools, supported JavaScript built-ins, and the globals the host adds through extensions. Timers, process, filesystem access, packages, and export are unavailable.
Unfinished work is interrupted. Tool calls and async functions start when called. When the program finishes, anything still running is interrupted. Unhandled rejections from un-awaited promises are returned as warnings.
REPL-style results. Without an explicit return, the final top-level expression becomes the result. undefined becomes null.

Unsupported syntax returns an UnsupportedSyntax diagnostic with a source location. Current gaps are tracked in the interpreter support checklist.

Quick Start (host API)

import { CodeMode, Namespace, Tool } from "@opencode/codemode"
import { Effect, Schema } from "effect"

const lookupOrder = Tool.make({
  description: "Look up an order by ID",
  input: Schema.Struct({ id: Schema.String }),
  output: Schema.Struct({ id: Schema.String, status: Schema.String }),
  execute: ({ id }) => Effect.succeed({ id, status: "open" }),
})

const runtime = CodeMode.make({
  language: "lua",
  tools: { orders: { lookup: lookupOrder } },
})

const result = await Effect.runPromise(
  runtime.execute(`
    local order = tools.orders.lookup({ id = "order_42" })
    return { id = order.id, needsAttention = order.status ~= "complete" }
  `),
)

result is always a CodeMode.Result.

API

`Tool.make`

input and output accept either an Effect Schema or a render-only JSON Schema document. Effect Schema input is decoded before execute; Effect Schema output is decoded and safely copied before the program sees it. JSON Schemas only shape the model-visible signature. Without output, the signature uses Promise<void>.

Descriptions and schemas are model-visible contracts. Authorization belongs in execute.

Nested records are the shorthand for ordinary namespaces. Use Namespace.make when a namespace needs a description:

const runtime = CodeMode.make({
  tools: {
    orders: Namespace.make({
      description: "Purchases, fulfillment, and shipment tracking",
      tools: { lookup: lookupOrder },
    }),
  },
})

Namespace descriptions are optional and participate in search matching for every descendant tool. Names still come from record keys, so the wrapper does not repeat orders. Dots in keys create nested paths; other characters use bracket notation, such as tools.context7["resolve-library-id"](...).

`CodeMode.execute` and `CodeMode.make`

CodeMode.execute({ ...options, code }) runs once. CodeMode.make(options) creates a reusable runtime:

const runtime = CodeMode.make({ tools, limits: { timeoutMs: 30_000 } })

runtime.catalog // structured tool descriptions
runtime.execute(source) // Effect<CodeMode.Result, never, ToolServices>

The Effect environment is inferred from the supplied tools. hooks surround every call the program makes into the host: tool.before/tool.after receive { name, input } with decoded input, extension.before/extension.after receive { extension, name, args }. An after hook also receives how the call ended (success with its value, failure with its error, or interrupted). A before hook runs before the call reaches the host, and a failing one denies it: the host function is never called, and the program catches the failure as a thrown error. A denied call fails the way the call itself would: a tool call or asynchronous global rejects its promise, and a synchronous global throws.

`Extension.make`

Extensions are host functions a program calls directly as globals, such as fetch. Unlike tools they are not in the catalog, not counted against maxToolCalls, and not described to the model; the host decides what they mean.

const web = Extension.make({ name: "web", globals: { fetch: async (url: string) => globalThis.fetch(url) } })
const runtime = CodeMode.make({ tools, extensions: [web] })

In the JavaScript interpreter, a global is synchronous unless it is an async function or is marked with Extension.async. Mark a plain function that returns a Promise or an Effect, so a denied call rejects its promise like any other failure:

Extension.make({ name: "web", globals: { fetch: Extension.async((url: string) => globalThis.fetch(url)) } })

A global may return a value, a Promise, or an Effect. An Effect's requirements join the runtime's environment the same way a tool's do, so the host can provide per-execution services such as the calling session:

const web = Extension.make({
  name: "web",
  globals: {
    fetch: Extension.async((url: string) =>
      Effect.gen(function* () {
        const session = yield* Session
        yield* session.authorize(url)
        return yield* Effect.promise(() => globalThis.fetch(url))
      }),
    ),
  },
})
const result =
  yield *
  CodeMode.make({ extensions: [web] })
    .execute(code)
    .pipe(Effect.provideService(Session, session))

Every value crossing in either direction is converted, never shared: arguments come in as copies, results go out as copies, and a function inside a result is callable the same way. A global that shadows a built-in or another extension throws at CodeMode.make.

A global can also be an object of functions, such as fs. Every function reachable from it is an entry point like a global, so calls fire the extension hooks with their path as the name (fs.readFile, fs.promises.readFile).

Programs load globals the way Node code loads modules. import and require take a global by its Node module name, with or without node:; fs/promises, url, util, and buffer resolve to the globals that provide them. There are no packages, so anything else throws.

import fs, { readFile } from "node:fs" // the `fs` global, if the host provides one
import { URL } from "url"
const crypto = require("crypto")
const { default: same } = await import("fs")

OpenAPI tools

OpenAPI.fromSpec converts an OpenAPI 3.x document into one tool per supported operation. Dotted operationId values create namespaces:

const api = OpenAPI.fromSpec({ spec, auth: { resolve } })
const runtime = CodeMode.make({ language: "lua", tools: { opencode: api.tools } })

The synchronous result is { tools, skipped }. Operations with unsupported parameter encodings, request bodies without JSON content, WebSocket or SSE semantics, or binary responses are reported in skipped.

Authentication is resolved by the host and never shown to the model. Generated tools require HttpClient.HttpClient. Request signatures omit readOnly properties; response signatures omit writeOnly properties. These JSON Schemas shape model-visible signatures but do not filter runtime values: nested JSON body properties and decoded server responses pass through unchanged. See src/openapi/types.ts for option details.

Results

Every execution returns:

type Result =
  | {
      readonly ok: true
      readonly value: CodeMode.DataValue
      readonly warnings?: ReadonlyArray<CodeMode.Diagnostic>
      readonly logs?: ReadonlyArray<string>
      readonly truncated?: boolean
      readonly toolCalls: ReadonlyArray<CodeMode.ToolCall>
    }
  | {
      readonly ok: false
      readonly error: CodeMode.Diagnostic
      readonly logs?: ReadonlyArray<string>
      readonly truncated?: boolean
      readonly toolCalls: ReadonlyArray<CodeMode.ToolCall>
    }

value is JSON-safe. warnings are non-fatal diagnostics, logs contain program console output, and truncated indicates that retained output was cut by maxOutputBytes. toolCalls retains admitted calls in order, including after failure.

Diagnostic kinds:

Kind	Meaning
`ParseError`	Source is empty or cannot be parsed.
`UnsupportedSyntax`	Parsed JavaScript is outside the supported subset.
`UnknownTool`	The program referenced an unavailable tool.
`InvalidToolInput`	Tool input failed schema decoding or safe-data copying.
`InvalidToolOutput`	Tool output failed schema decoding or safe-data copying.
`InvalidDataValue`	Program data violated the plain-data contract.
`ToolCallLimitExceeded`	The program exceeded `maxToolCalls`.
`TimeoutExceeded`	Execution timed out; as a warning, background work was interrupted after the program returned.
`ToolFailure`	A tool refused or failed.
`ExecutionFailure`	The program threw or another execution error occurred.
`Truncated`	Warning only: additional warnings were omitted by `maxOutputBytes`.

Host failures and defects report their messages and underlying causes. Invalid outputs include the validation or copying error. Interruption propagates without becoming an error diagnostic.

Discovery

runtime.catalog returns structured descriptors for every visible tool (path, description and signature in the selected language). For Lua instructions use CodeMode.luaSearchSignature and CodeMode.toolExpression(path, "lua"); CodeMode.searchSignature and CodeMode.toolExpression(path) retain their JavaScript meanings.

The synchronous search(...) built-in is always available. It supports exact-path lookup, namespace-scoped search, empty-query browsing, and pagination, and returns callable paths with full signatures. Lua sees the result directly. In JavaScript it can also be awaited or chained with then, catch, and finally. Search counts toward maxToolCalls. Search also matches descriptions from enclosing Namespace values.

Execution Limits

Limit	Lua default	JavaScript default	Controls
`timeoutMs`	120,000	unlimited	Total execution time.
`maxToolCalls`	128	unlimited	Lua host call attempts (tools, search and extensions); JavaScript admitted tools.
`maxOutputBytes`	65,536	unlimited	Retained result value and logs.

Lua also enforces non-configurable bounds on source and syntax depth, interpreter work and call frames, string and table growth, and expanded data copies. These bounds apply even when the host raises its configured limits. The production evaluator shares the Lua interpreter's frames and call loop but installs only metered operations: no prototype libraries, dynamic loading, I/O, metatables, regex/pattern engine or coroutines. Lua strings are byte strings; strings crossing JSON boundaries must be valid UTF-8.

Invalid limit configuration throws RangeError. Warnings receive a separate budget equal to maxOutputBytes. Truncation does not fail execution; an oversized value becomes a string with an in-band marker. Timeouts interrupt tool calls and busy loops. In JavaScript a result returned before cleanup times out remains successful with a TimeoutExceeded warning; JavaScript tool calls may run concurrently.

README.md

@opencode/codemode