Code mode is an experimental Apus agent-runtime feature. When enabled, the model no longer sees every enabled tool schema. Instead, it sees exec, wait, and any direct-only tool whose structured result cannot cross the JSON-only guest bridge. The model writes a small JavaScript program that searches, describes, and calls the hidden tool catalog. TypeScript-style signatures describe the available tools; executable cells use plain JavaScript without type annotations.

This page documents Apus Code Mode, not Codex Code Mode. The two features share a name and the same control-tool names (exec, wait), but they are separate implementations:

• Codex Code Mode runs inside the Codex coding harness. Its exec tool is a freeform-grammar tool: the model writes raw JavaScript source (optionally prefixed by a // @exec: {...} pragma line for execution options), executed in Codex's in-process V8 Code Mode runtime.
• Apus Code Mode runs in the generic Apus agent runtime and is enabled through global, agent, or model activation settings. Its exec tool takes a JSON { title, code } payload, executed by the selected Node or QuickJS executor.

Both are JavaScript execution surfaces, not shell-command surfaces. Treat them as independent, differently-implemented features that happen to expose identically-named exec/wait tools.

In Apus Code Mode, command is a JavaScript alias for code, not a shell command. For shell or file operations, call the appropriate async tool global from guest JavaScript. Recognizable shell commands are rejected before guest execution with actionable invalid_input guidance.

JavaScript executes outside the Gateway's main event loop. Node is the default executor and uses node:vm in a worker thread for trusted execution; it is not a security boundary. The bundled QuickJS executor provides hardened guest isolation. Both use the same tool bridge, where permissions, approvals, and session ownership remain with the Gateway. See Code Mode executors before enabling it.

This page is an index. Code Mode is documented on nine pages, one per reader job. Open the page that matches your task.

What it does

• The model-visible tool list becomes exec, wait, plus any direct-only tool such as computer or the native-vision view_image loader whose image result cannot survive the guest bridge.
• exec evaluates model-generated JavaScript in the selected executor's worker thread.
• Every catalog-eligible enabled non-MCP tool (Apus core, plugin, client) is hidden as a standalone model tool and exposed inside the guest program as an async global function. MCP stays under the MCP namespace.
• The exec description carries a bounded quick index of final callable names, compact input hints, and compact declared output hints when a trusted tool provides an output schema. It omits descriptions, full schemas, MCP entries, and overflow entries. Callable catalog.search(...) results are the fallback. Input hints retain integer and numeric bounds as comments, such as offset?: number /* integer, >= 1 */. Other validation details remain in the full schema available through describe(). These hints do not change tool validation or output contracts. Core file and shell tool signatures stay first in the bounded index, followed by tools with declared output hints, so catalog growth does not hide their input argument names.
• Guest code calls globals directly or searches the hidden catalog for callable handles. A handle exposes bounded metadata and describe(), but never the exact internal catalog id. Calls use the same execution path as normal agent turns (policy, approvals, hooks, telemetry all still apply).
• MCP tools are grouped under the MCP namespace and discoverable by task through catalog.search(...). MCP search handles call the same namespace path and point to its exact declarations.
• wait resumes a suspended Code Mode run when nested tool calls are still pending.

Call wait only when the outer Code Mode result has status: "waiting", using its top-level runId. A completed cell can return a background shell operation with its own sessionId inside value. Use the enabled process-control tool inside a new exec to poll that operation. Its sessionId is not a Code Mode run ID.

Code mode changes the model-facing orchestration surface only. It does not replace tools, plugin tools, MCP tools, auth, approval policy, channel behavior, or model selection.

Why use it

• Smaller prompt surface: providers get two control tools, a bounded native-tool index, and only the few required direct tools instead of dozens or hundreds of full tool schemas.
• Better orchestration: the model can use loops, joins, small transforms, conditional logic, and parallel nested tool calls inside one code cell.
• Fewer model round trips: a declared output contract lets the model call and transform a tool result in one exec. Unknown outputs remain raw-first.
• Provider neutral: works for Apus, plugin, MCP, and client tools without depending on provider-native code execution.
• Fails closed: if Code Mode is enabled but the selected executor is unavailable, the run fails instead of silently falling back to broad direct tool exposure.

Most useful for agents with a large enabled tool catalog, or workflows where the model needs to search, combine, and call several tools before answering.

Keep direct tool exposure for a small catalog or a model that does not reliably write short programs. Use Tool Search when you want a compact catalog but prefer structured search/describe/call controls instead of JavaScript cells.

Technical tour

These pages cover the runtime contract and implementation details, for maintainers, plugin authors debugging tool exposure, and operators validating high-risk deployments.

Where each section moved

Every section heading from the previous single-page version keeps its anchor here, so an existing link such as /tools/code-mode#guest-runtime-api still resolves. Each entry points at the page that now holds the content.

• Quickstart
• Enable code mode
• Override one model
• What the model does
• Recover from tool errors
• Verify the active surface
• Use Swarm for agent fan-out
• Configuration
• Automatic per-model activation
• The compat catalog flag
• Shipped preferred models
• Models shipped by more than one provider
• Choosing when to enable
• Activation
• Model-visible tools
• The exec tool
• Source in session history
• The wait tool
• Tool catalog
• Tool Search interaction
• Tool names and collisions
• Guest runtime API
• Reading paginated file data
• Declared output contracts
• Output API
• Runtime status
• Scope
• Terms
• Nested tool execution
• Run and snapshot lifecycle
• QuickJS-WASI runtime
• TypeScript
• Security boundary
• Error codes
• Telemetry
• Debugging
• Implementation layout
• Validation checklist
• E2E test plan

Related

• Swarm for fan-out agent orchestration from Code Mode scripts
• Tool Search
• Agent runtimes
• Exec tool
• Code execution