Code execution

The execute_code tool is a quietly powerful feature: instead of calling tools one at a time, the agent writes a short Python script that calls Hermes tools programmatically, and only the script's print() output comes back. Multi-step pipelines collapse into a single turn, and the intermediate tool results never enter the context window.

On a local model with a modest context budget, this matters a lot, it is the difference between a workflow that fits and one that overflows.

How it works

1. The agent writes a script using from hermes_tools import ....
2. Hermes generates an hermes_tools.py stub with RPC functions and opens a Unix-domain-socket listener.
3. The script runs in a child process; each tool call travels over the socket back to Hermes.
4. Only stdout returns to the model. Intermediate results stay out of context.

from hermes_tools import web_search, web_extract

results = web_search("Qwen 3.5 features", limit=5)
for r in results["data"]["web"]:
    page = web_extract([r["url"]])
    # ... filter and summarize ...
print(summary)

Tools available inside scripts: web_search, web_extract, read_file, write_file, search_files, patch, and terminal (foreground only).

When the agent uses it

The agent reaches for execute_code when there are 3+ tool calls with logic between them, bulk filtering, conditional branching, or loops over results. You don't ask for it explicitly; it picks the right tool for the task.

Why it saves context (the key benefit)

Say you search 5 pages and extract each. With normal tool calls, all five full page bodies land in context. With execute_code, the script filters them down and prints a 10-line summary, so only those 10 lines cost tokens. That is exactly the kind of frugality a 64K local window appreciates.

Execution mode

# ~/.hermes/config.yaml
code_execution:
  mode: project   # project (default) | strict
  timeout: 300
  max_tool_calls: 50

• project (default): runs in the session working directory with the active venv's Python, so import pandas and relative paths work like in a normal terminal.
• strict: runs in an isolated temp dir with Hermes's own Python, for maximum reproducibility.

Resource limits

Resource	Limit
Timeout	5 minutes (SIGTERM then SIGKILL)
Stdout	50 KB (truncated with a notice)
Tool calls	50 per execution

Security

The child process runs with a minimal environment: variables whose names contain KEY, TOKEN, SECRET, PASSWORD, CREDENTIAL, PASSWD, or AUTH are stripped. Scripts cannot call execute_code recursively, delegate_task, or MCP tools. If a skill declares required_environment_variables, those are passed through automatically once the skill loads; otherwise allowlist a variable explicitly under terminal.env_passthrough.

Platform support

execute_code requires Unix domain sockets, so it works on Linux and macOS only. On Windows it is automatically disabled and the agent falls back to regular sequential tool calls.

execute_code vs terminal

Use case	Tool
Multi-step workflow with tool calls + logic	execute_code
Single shell command, build, or test run	terminal
Filtering/processing large tool outputs	execute_code
Interactive or background processes	terminal

Rule of thumb: execute_code for programmatic tool orchestration, terminal for plain commands.