Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.enconvo.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

EnConvo’s Code Runner lets AI agents execute shell commands and code directly on your Mac. When you ask an AI agent to perform tasks like running scripts, installing packages, or managing files through the terminal, Code Runner handles the execution in a controlled environment with automatic timeout handling and output optimization.

​
How It Works

Code Runner is primarily used as a tool by AI agents. When you chat with an AI agent that has code execution capabilities, it can invoke the Code Runner to:
  • Run shell commands (bash/zsh)
  • Execute Python scripts
  • Install packages via npm, pip, or other package managers
  • Perform git operations
  • Run build tools and development servers
  • Execute any command-line operation
You: "Create a new Python virtual environment and install pandas"

Agent: I'll create a virtual environment and install pandas for you.
> python3 -m venv myenv
> source myenv/bin/activate && pip install pandas

Done! Created virtual environment 'myenv' and installed pandas successfully.

​
Supported Operations

​
Shell Commands

Code Runner executes commands through /bin/zsh, inheriting your shell profile (.zshrc or .bashrc). This means all your PATH settings, aliases, and environment variables are available.
CategoryExamples
Package Managementnpm install, pip install, brew install, cargo add
Version Controlgit status, git commit, git push, git log
File Operationsmkdir, cp, mv, chmod, tar
Developmentnpm run build, python script.py, cargo build
Systemls, pwd, which, env, ps
Dockerdocker run, docker-compose up, docker build
Networkcurl, wget, ssh, scp

​
Python

Code Runner automatically activates Python virtual environments when available:
  1. If a venv or .venv directory exists in the working directory, it is activated automatically
  2. uv is preferred over pip for Python package management when available
  3. All standard Python tooling works: pytest, mypy, black, ruff, etc.

​
Node.js / JavaScript

Full support for the Node.js ecosystem:
  • node, npm, npx, pnpm, yarn
  • Direct execution of .js and .ts files (via ts-node or tsx)
  • Package scripts via npm run

​
Other Languages

Any language with a command-line compiler or interpreter works:
LanguageRun Command
Pythonpython3 script.py
Node.jsnode script.js
Rubyruby script.rb
Gogo run main.go
Rustcargo run
Swiftswift script.swift
Shellbash script.sh
C/C++gcc -o app main.c && ./app

​
Configuration

​
Working Directory

Code Runner uses a configurable working directory that persists between commands. The AI agent can specify the working directory for each command, or it defaults to the current workspace directory.
The working directory persists between commands within the same session, but shell state (variables, aliases defined in-session) does not. Each command starts a fresh shell process.

​
Timeout Settings

SettingValue
Default timeout2 minutes (120,000 ms)
Maximum timeout10 minutes (600,000 ms)
Commands that exceed the timeout are automatically terminated. The AI agent can specify custom timeouts for long-running operations.

​
RTK Token Optimization

Code Runner includes RTK (Rust Token Killer) — a token compression system that reduces command output size before sending it back to the AI agent.
  • Enabled by default — reduces token usage and costs
  • Compresses verbose command output while preserving essential information
  • Particularly useful for commands that produce large outputs (e.g., npm install, build logs)
You can toggle this in the Code Runner preferences:
SettingDescription
Enable RTKUse RTK to compress command output and reduce token usage (default: on)

​
Background Execution

Long-running commands can be executed in the background:
  • The AI agent marks a command as background when it does not need the result immediately
  • You are notified when the background command completes
  • Useful for builds, installations, and server startups

​
Security

Code Runner executes real commands on your system. While AI agents follow safety guidelines, always review what the agent proposes to do before confirming execution of destructive operations.

​
Safety Measures

EnConvo implements several safety measures for code execution:
  1. Non-interactive execution: Commands run non-interactively (execFileSync), so they cannot prompt for input. Commands requiring -y or --yes flags must include them explicitly.
  2. Timeout protection: All commands have enforced timeouts to prevent runaway processes.
  3. Output limits: Command output exceeding 30,000 characters is automatically truncated.
  4. Agent guidelines: AI agents follow strict safety protocols:
    • Prefer non-destructive operations
    • Use absolute paths to avoid accidental directory changes
    • Quote file paths with spaces
    • Verify directories exist before creating files

​
Sandboxing

Code Runner supports an optional sandbox mode. When sandbox mode is enabled, commands run in a restricted environment. The AI agent can request to disable sandboxing for specific commands when necessary, but this is done with explicit intent.

​
Usage in AI Chat

Code Runner is automatically available to AI agents with tool-use capabilities. You do not need to configure anything — simply ask the agent to perform tasks that require command execution.

​
Example Interactions

Running a build: 
You: Build my React project and tell me if there are any errors.

Agent: I'll run the build command for you.
> npm run build
Build completed successfully with 0 errors and 2 warnings.
Git operations: 
You: Show me what files have changed since my last commit.

Agent: Let me check the git status.
> git diff --stat HEAD
3 files changed, 45 insertions(+), 12 deletions(-)
System information: 
You: How much disk space do I have left?

Agent: Let me check your disk usage.
> df -h /
Filesystem  Size  Used  Avail  Use%
/dev/disk3  460G  287G   173G   63%

You have 173 GB of free space on your main drive.
Python scripting: 
You: Create a Python script that converts all PNG files in my
Downloads folder to JPEG.

Agent: I'll create and run the script for you.
> python3 convert_images.py
Converted 12 PNG files to JPEG in ~/Downloads

​
Output Handling

​
Output Format

Command output is captured from both stdout and stderr and returned to the AI agent for analysis. The agent then presents relevant information in a human-readable format.

​
Large Output

For commands with verbose output:
  1. RTK compression reduces token usage automatically
  2. Truncation at 30,000 characters prevents excessive token consumption
  3. The AI agent summarizes key information from the output

​
Error Handling

When a command fails:
  1. The exit code and error message are captured
  2. The AI agent analyzes the error and suggests fixes
  3. The agent may retry with a corrected command

​
Troubleshooting

  1. The command may not be installed or not in your PATH
  2. Check that your shell profile (.zshrc) properly exports the PATH
  3. Some tools installed via Homebrew need eval "$(/opt/homebrew/bin/brew shellenv)" in your profile
  4. Try using the full path to the command (e.g., /usr/local/bin/python3)
  1. The file may not have execute permissions — the agent can run chmod +x file
  2. Some system directories require sudo which is not supported in non-interactive mode
  3. Check file ownership with ls -la
  1. The default timeout is 2 minutes — long builds or downloads may need more
  2. The AI agent can specify a longer timeout (up to 10 minutes)
  3. Consider running long tasks in background mode
  4. Break complex operations into smaller steps
  1. RTK compression may be too aggressive for certain output — try disabling it
  2. Very long outputs are truncated at 30,000 characters by design
  3. Ask the agent to redirect output to a file for full access

AI Agents

Agents that use Code Runner as a tool

AI Chat

Chat interface for code execution

SmartBar

Quick command execution

Workflows

Automate code execution in workflows