Skip to main content

CodeAct & /codeact

V2 and above. Part of the invite-only hosted editions, not the free self-hosted V1. See the editions.

What CodeAct is​

CodeAct is an execution mode where the agent's action space is code, not a fixed list of tools. Instead of picking from ~94 MCP tools and emitting a JSON envelope per step, the model writes a code block, it runs in a sandbox, and the result feeds the next step. This removes two failure modes for code-heavy work: the per-turn tool-schema context tax, and JSON-envelope truncation of large files.

The agent picks CodeAct automatically for code-build and analysis goals. The /codeact command lets you invoke it explicitly and point it at a source — ideal for migrating or refactoring a real, multi-file codebase.

Use /codeact when you want deterministic CodeAct on a specific codebase. For ad-hoc "build me X" goals, normal goal execution already auto-selects CodeAct when it fits.

The command​

/codeact <query> [path:<workspace-dir>] [integration:<id>]
path:

A workspace-relative directory holding the source codebase (e.g. an uploaded repo under uploads/). The agent reads it file-by-file.

integration:

A connected database integration. Its schema + a read-only data sample are exported into your workspace for the agent to use.

Examples:

/codeact migrate this TypeScript app to Python path:uploads/myrepo
/codeact refactor these modules to use async/await path:src/services
/codeact build a Python data-access layer for this schema integration:oracle

The query is whatever you want done — migrate, port, refactor, modernise, add type hints, document, analyse. When the request names a target language (e.g. "to Python"), output files get the new extension; otherwise the transform stays in the original language.

How a large codebase is handled​

A real repo blows past a model's context window and the sandbox's per-turn output limit. /codeact solves this with a manifest-driven, file-by-file loop rather than trying to hold the whole repo at once.

  1. 1
    Preflight — build a file manifest

    The code is read once, skipping the parts that aren’t yours — installed packages, version-control internals, build output, caches and binaries. What’s left is sorted so the simplest, least-dependent files are read first, which is the order that makes a codebase comprehensible rather than overwhelming. Large codebases are capped at a sensible number of files.

  2. 2
    Transform — one file per turn

    For each file, the full source is injected directly into the prompt (bypassing the sandbox's small per-turn output limit). Files too large for one turn are split on top-level boundaries (class/function/etc.) and reassembled.

  3. 3
    Verify — syntax-check each output

    Each transformed file is written into the output tree (mirroring the source structure) and syntax-checked. A file that fails is retried once with the error fed back.

  4. 4
    Track — resumable progress

    The manifest records done / pending / failed per file and is saved after every file. Progress shows live in the Goal panel (X/N files).

Resumable. If a run is interrupted (timeout, cancel, error), re-issue the same /codeact … path:<dir> command and it continues from where it left off — completed files are skipped, failed ones retried.

Watching progress​

/codeact runs through the standard goal pipeline, so the Goal Progress panel lights up automatically — each file appears as an action, and the validation score tracks done/total. See Goal Execution and Goal Timeline.

Using a database integration​

integration:<id> exports a read-only snapshot of a connected database — schema.md plus a CSV sample per table — into .codeact_sources/<id>/ in your workspace. Every read goes through the read-only query layer, so the snapshot can never write back to your database, and the raw connection string never enters the sandbox.

Supported today: databases — Oracle, Postgres, MySQL or a local file, wherever you’ve configured a connection under Integrations. Other connected services (Drive, Notion, Gmail, a code repository) can’t be pointed at directly: export what you need into your workspace and use path: instead. Point it at an unsupported service and it tells you so plainly.

Choosing the model​

The transformation is driven by your active model — you choose the trade-off between speed/cost and how large a file it can handle in one pass. For a big or complex migration, select a strong long-context model before running. See Model Routing.

Limits​

Up to ~150 files

Processing is sequential and capped at 150 files per run. Larger repos: split into sub-directories and run /codeact per folder.

Very large single files

Files bigger than one turn are chunked on top-level boundaries — best-effort reassembly.

Database integrations only

integration: materialises DB sources only; everything else routes through path:.

Quality follows the model

Output fidelity is bounded by the model you select for the run.