How AIClaw's Code Interpreter Turns Scripts Into Downloadable Agent Outputs

AI agents often need a place to do small but real computation: clean a CSV, convert a JSON payload, generate a chart, inspect an API response, or produce a one-off report. The problem is that many agent products either stop at “here is some code you can run yourself” or run code in a way that is hard to inspect afterward.

AIClaw takes a more practical route. Its built-in code_interpreter tool runs Python, JavaScript, or shell snippets inside the agent workspace, returns structured execution results, and can surface generated files back into the chat flow.

This is not a brand-new July 2026 launch. It is an existing AIClaw feature that is worth a closer look because it connects a few product surfaces that matter in day-to-day use: sandboxed execution, structured tool output, downloadable artifacts, and reusable workflow skills.

The problem: agents need computation, not just text

A useful agent should be able to do more than describe a transformation. It should be able to execute it.

Common examples:

• parse a CSV and calculate grouped statistics;
• convert JSON into Markdown or HTML;
• generate a small script to validate API output;
• produce a PNG, CSV, or report file for the user to download.

Without an execution tool, the model either hallucinates results or pushes the work back to the operator. With a raw shell tool alone, the agent can run commands, but the product still needs a consistent way to track stdout, stderr, exit status, duration, and any generated files.

That is the gap AIClaw's code_interpreter fills.

What the tool actually does

In the current repository, AIClaw registers code_interpreter as a built-in tool alongside read, write, exec, browser, cron, memory, and sub_agent.

The tool contract is intentionally small:

• language: python, javascript, or shell
• code: the source to execute
• timeout: optional, with a default of 60 seconds and a hard cap of 120 seconds

The handler then:

1. Validates the input.
2. Resolves the runtime binary with exec.LookPath:
   • python3 for Python
   • node for JavaScript
   • sh for shell
3. Applies lightweight safety checks against obviously dangerous code patterns.
4. Writes the snippet into the agent sandbox as a real file such as exec_ab12cd34.py.
5. Executes that file with the sandbox directory as the working directory.
6. Returns structured JSON with:
   • ok
   • language
   • file
   • exit_code
   • stdout
   • stderr
   • error
   • duration_ms

That structure matters because the result is machine-friendly for the runtime and still readable in logs and chat progress.

Why writing a real file is the important design choice

One subtle but useful implementation detail is that AIClaw does not treat the snippet as an opaque in-memory eval. It writes the code to a real file inside the workspace sandbox and runs that file from there.

That gives the agent a cleaner execution model:

• file-relative reads and writes behave normally;
• generated artifacts land in the same workspace the rest of the agent can inspect;
• operators can reason about what happened from a concrete script filename;
• execution traces line up better with file outputs and follow-up tool calls.

For an agent platform, this is much more practical than a hidden REPL with no durable execution context.

How downloadable outputs are recovered

The interesting part is not only that code runs. It is that AIClaw can turn the result into something a user can actually open.

AIClaw's result parsing layer looks for file outputs in a few ways:

• a direct JSON file result payload;
• an absolute file path printed as the entire output;
• an absolute file path embedded in stdout, such as Saved to /tmp/report.csv.

If the referenced file exists, AIClaw converts it into a normalized file result with MIME type detection by extension. That is what allows generated files to move from “the script said it wrote something” to a proper attachment flow in chat and the UI.

This complements the generated-file work already visible elsewhere in the product. The code interpreter is one of the fastest ways for an agent to produce those artifacts on demand.

Safety and limits

AIClaw is not pretending this tool is a full security boundary, but it does enforce a few useful guardrails in the current implementation.

The handler blocks some obviously dangerous patterns, for example:

• destructive shell commands like rm -rf /;
• Python subprocess or direct system-call patterns;
• JavaScript process and filesystem patterns associated with unsafe execution.

It also:

• requires the runtime binary to exist before execution starts;
• limits output to 10,000 characters;
• caps timeout at 120 seconds;
• fails cleanly when the workspace sandbox is not initialized.

That is a pragmatic posture for a self-hosted platform: useful by default, explicit about constraints, and easy to reason about from code.

Where this fits in real AIClaw workflows

The feature becomes more valuable when combined with the rest of AIClaw.

For example:

• read can inspect a source file;
• code_interpreter can transform or analyze it;
• write can save a cleaned result;
• the result layer can expose generated files back to the user;
• sub_agent can parallelize independent analysis tasks;
• skills can standardize the workflow for repeatable use cases.

The repository already reflects this pattern. AIClaw's built-in data-pipeline skill explicitly tells agents to use code_interpreter for CSV, JSON, and Excel-style processing tasks, including validation and export.

That is the right level of abstraction. The skill captures the workflow, while the interpreter provides the execution primitive.

A concrete example

Suppose a user uploads a CSV and asks:

Group sales by month, calculate totals, and give me a downloadable result.

An AIClaw agent can:

1. inspect the file with read;
2. write a short Python script in code_interpreter;
3. save monthly_sales.csv inside the sandbox;
4. print the absolute output path;
5. return both a summary and the generated file attachment.

The same pattern works for:

• HTML report generation;
• JSON normalization;
• log summarization;
• quick chart creation;
• one-off format conversion.

Why this feature is worth covering now

A lot of agent demos focus on planning, tools, or model routing. Those matter, but the product becomes much more useful when an agent can produce concrete outputs that survive beyond the answer text.

AIClaw's code_interpreter is a good example of that product thinking:

• simple tool contract;
• explicit runtime selection;
• workspace-local execution;
• structured results;
• attachment-friendly file detection;
• natural integration with skills and other tools.

If you are building a self-hosted agent platform, this is a feature worth studying. It is not only about “running code.” It is about making execution auditable, composable, and actually useful to the person operating the system.