> ## 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.

# Code Runner

> Run shell commands and interact with persistent terminal sessions from an Agent.

Code Runner gives an Agent a real terminal on your Mac. Use it for builds, tests, scripts, package tools, and development servers. Enable the tool for the Agent you are using; installed command-line programs and your account permissions determine what can run.

## Start with a small command

Give the Agent a directory and a specific task:

> In my sample project, run the existing test command and report the result. Do not change files.

The Agent should show command output and distinguish successful completion from a command that is still running. Use [File Tools](/ai/file-tools) for reading, editing, and searching files.

## Terminal sessions

All execution modes use a pseudo-terminal, so a command that asks for input can be answered without starting a new process.

| Mode | Intended use |
| - | - |
| **oneshot** | Commands expected to finish, such as tests, builds, or a script |
| **long\_running** | Servers, watchers, and processes waiting for an external event |
| **interactive** | REPLs, terminal applications, and interactive CLI sessions |

A result with `status: running` and a `session_id` means the process continues. The Agent can **read** output, **write** input, or **stop** that session. Starting another command is not a substitute for answering a prompt in the existing session.

## Working directory and time limits

The tool accepts `workDir` for the command's working directory and uses the user's shell with project and Python virtual-environment setup. Separate command launches do not share temporary shell variables unless they are in the same running session.

The initial wait is separate from the command's hard timeout. Current oneshot commands default to a 30-minute hard deadline; the initial response can arrive much earlier while work continues. Use long-running mode for a server or watcher rather than treating it as a failed oneshot command.

## Output compression

**Enable RTK** in the Code Runner command preferences compresses verbose output for the Agent. If an important detail is missing, ask for a more focused command or the relevant log section. Truncated output is not proof that the command succeeded.

## Troubleshooting

* **Command not found:** verify the program is installed and available in the shell environment.
* **Waiting for input:** continue the existing session and answer its prompt.
* **Permission denied:** check the target path and macOS permissions.
* **Timed out:** inspect the last output; use the appropriate execution mode before retrying.
* **Server still running:** stop its session when it is no longer needed.

Commands execute with real filesystem and network access. Review commands that install software, change files, or affect external services before running them. Code Runner does not make those operations a sandbox simulation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.