Skip to main content
Code Runner gives an Agent a real terminal on your Mac. Use it for builds, tests, scripts, package tools, and development servers. The programs you have installed and your account’s permissions decide what can run.
Commands run for real, with full access to your files and the network; Code Runner isn’t a sandbox. Review any command that installs software, changes files, or affects an online service before it runs.

​
Before you start

  • Turn on Code Runner for the Agent you’re using.
  • The Permissions chip in the chat decides when the Agent asks first. Ask for approval asks before it runs a command, and Approve for me asks only for actions that look unsafe. See Approve actions.

​
Run a command

Give the Agent a folder and a specific task:
In my sample project, run the existing test command and report the result. Do not change files.
The Agent shows the command’s output and tells you whether it finished or is still running. To read, edit, and search files, the Agent uses file tools instead.

​
How commands run

Every command runs in a pseudo-terminal, so a command that asks for input can be answered without starting a new process. A result with status: running and a session_id means the process keeps going. The Agent can read its output, write input to it, or stop it. To answer a prompt, the Agent writes to that session; starting another command doesn’t answer it.

​
Working folder and time limits

Commands run in workDir when the Agent sets it, and in the chat’s working folder otherwise. They use your shell, with your project and Python virtual environment set up. Separate commands don’t share temporary shell variables unless they run in the same session. The first wait is separate from the command’s hard time limit. A oneshot command waits up to 30 seconds for its result; if it’s still running then, the Agent gets the output so far while the work continues. The command is stopped after 30 minutes by default. For a server or a watcher, use long_running mode instead of treating it as a oneshot command that failed.

​
Settings

Open Settings → Plugins → Code Runner. If a detail you need is missing from compressed output, ask for a more focused command or the relevant part of the log. Cut-off output doesn’t prove the command succeeded.

​
Troubleshooting

Files and Folders

Let an Agent find, read, and edit files.

Agents

Set an Agent’s tools and when it asks first.