Run Programmatic Workflows with Hermes Code Execution

Hermes uses execute_code when a task needs several tool calls plus logic between them. A generated Python script imports approved RPC helpers from hermes_tools, calls those tools inside a child process, and prints only the reduced result back to the agent. That keeps bulky intermediate search results, file contents, and loop output out of the conversation context.

Choose the right execution path

Use execute_code for three or more tool calls with filtering, branching, retries, or aggregation. Use the normal terminal tool for one shell command, builds, interactive programs, background processes, or anything requiring a PTY. Inside code execution, terminal() is foreground-only.

The script can call web_search, web_extract, read_file, write_file, search_files, patch, and foreground terminal. It cannot recursively invoke execute_code, spawn subagents, or call MCP tools. The normal tool authorization and error-handling path still applies through the RPC socket.

Configure the execution boundary

code_execution.mode: project runs from the session working directory with the active virtual environment when possible. strict uses a temporary working directory and Hermes's interpreter for a more reproducible quarantine. Both modes scrub credentials, enforce the same tool whitelist, and apply resource limits.

code_execution:
  mode: project
  timeout: 300
  max_tool_calls: 50

Default limits are five minutes, 50 tool calls, 50 KB of stdout, and 10 KB of diagnostic stderr. Required skill environment variables or explicitly allowlisted variables can pass through; provider credentials remain protected.

Workflow checklist

• Confirm the task really needs a loop, reduction, or conditional branch.
• Import only the Hermes tools the script needs.
• Keep writes narrowly scoped and count successful changes.
• Print one compact, structured result rather than raw intermediate data.
• Check status, tool_calls_made, duration, and any nonzero exit details.

Pitfalls

Do not use code execution merely to hide a single shell command. Do not assume arbitrary environment variables are visible: secret-like names are stripped, and only a small fixed set of operational HERMES_* variables passes by default. On Windows, Hermes falls back to sequential tools because this feature relies on Unix-domain sockets.

Verification steps

1. Start with a read-only script that makes two harmless calls and prints JSON.
2. Confirm the working directory and interpreter match the selected mode.
3. Force one controlled failure and verify structured error output appears.
4. Inspect the final result for truncation before trusting a large reduction.

See the official Code Execution guide for the current tool list, limits, and security model.