main.js · part 234

60 text occurrences from desktop/Cursor.app/Contents/Resources/app/extensions/cursor-agent-exec/dist/main.js, part 234. Every entry preserves the shipped literal and its saved verdict or selection reason.

File contents and all parts · All files

Use ';' only when you need to run commands sequentially but don't care if earlier commands fail

DO NOT use newlines to separate commands (newlines are ok in quoted strings)

When adding new dependencies, prefer using the package manager (e.g. npm, pip) to add the latest version. Do not make up dependency versions.

Managing long-running commands

Commands that don't complete within `block_until_ms` (default

 ${Xge(c)}

) are moved to background. The command keeps running and output streams to a terminal file. Set `block_until_ms: 0` to immediately background (use for dev servers, watchers, or any long-running process).

You do not need to use '&' at the end of commands.

Make sure to set `block_until_ms` to higher than the command's expected runtime. Add some buffer since block_until_ms includes shell startup time; increase buffer next time based on `elapsed_ms` if you chose too low. E.g. if you sleep for 40s, recommended `block_until_ms` is 45s.

Monitoring backgrounded commands:

When command moves to background, check status immediately by reading the terminal file.

Header has `pid` and `running_for_ms` (updated every 5000ms)

When finished, footer with `exit_code` and `elapsed_ms` appears.

Poll repeatedly to monitor by sleeping between checks. If the file gets large, read from the end of the file to capture the latest content.

Pick your sleep intervals using best guess/judgment based on any knowledge you have about the command and its expected runtime, and any output from monitoring the command. When no new output, exponential backoff is a good strategy (e.g. sleep 2000ms, 4000ms, 8000ms, 16000ms...), using educated guess for min and max wait.

If it's longer than expected and the command seems like it is hung, kill the process if safe to do so using the pid that appears in the header. If possible, try to fix the hang and proceed.

Don't stop polling until: (a) `exit_code` footer appears (terminating command), (b) the command reaches a healthy steady state (only for non-terminating command, e.g. dev server/watcher), or (c) command is hung - follow guidance above.

You'll be notified when the backgrounded command completes.

You can monitor commands by configuring `notify_on_output`. You will be notified at the end of your turn whenever stdout/stderr output matches the regex `pattern` (do not match all outputs). Output redirected only to a file will not trigger it. You will only receive notifications after ending your turn. Configure a 5 or less words `reason` which explains what you are watching for. The UI will prefix it as "Monitored `reason`". Configure `debounce_ms` to control how many milliseconds must elapse between notifications; the harness treats values less than 5000ms as 5000ms. Configure shell commands to emit stable sentinel lines and simple anchored regexes; pipe noisy output through jq/awk/scripts if needed. The system will terminate the watcher if the notifications are overly noisy, and you will be informed in this case.

Completion notifications are delivered separately from output-match notifications and do not require `notify_on_output` to be set.

Only poll with 

 later if you have been asked to work on something that requires the result of a previous shell command. Using the

 is very disruptive because it prevents you from being able to multitask.

You'll be notified when the backgrounded command completes. Only poll with

 when the command requires close monitoring — long-running jobs that can silently hang or degrade before completing (training runs, eval runs, deployments, long builds, datagen pipelines, DB migrations, large data transfers). For fire-and-forget commands (tests, installs, dev servers/watchers, short scripts), start them and keep working — you can always poll with 

later if you end up blocked on the result. If under your control, prefer commands that print periodic status updates so close monitoring is effective.

Use the 

 tool to monitor the background command. If under your control, prefer commands that print periodic status updates so you can monitor effectively.

Scheduling notifications

You can schedule notifications for yourself by starting a background shell that sleeps and echos a reminder message. This can be very useful for reminding yourself to check on another shell or task and verify it is making progress. Always think about how long you expect something to take before scheduling a notification.

tmux-backed shell sessions

Other common operations

View comments on a Github PR: gh api repos/foo/bar/pulls/123/comments

The command to execute

The absolute path to the working directory to execute the command in (defaults to current directory)

${e}ms / ${Number.isInteger(t)?"":"~"}${r} second${1===r?"":"s"}

${e}ms / ${Number.isInteger(r)?"":"~"}${t} minute${1===t?"":"s"}

How long to block and wait for the command to complete before moving it to background (in milliseconds). Defaults to ${function(e){const t=e/1e3;if(Number.isInteger(t)&&t>0&&t<=120)return`${e}ms (${t} second${1===t?"":"s"})`;const r=e/6e4;return Number.isInteger(r)&&r>=1?`${e}ms (${r} minute${1===r?"":"s"})`:`${e}ms`}(e)}. Set to 0 to immediately run the command in the background. The timer includes the shell startup time.

${e}ms (${t} second${1===t?"":"s"})

${e}ms (${r} minute${1===r?"":"s"})

Clear, concise description of what this command does in 5-10 words

Whether the command should be run in the background

Regex pattern matched against stdout/stderr output. Output redirected only to a file will not trigger it. Do not match all outputs.

5 or less words describing why you are watching for this output. The UI (only visible to user) will prefix it as 'Monitored `reason`'.

Milliseconds that must elapse between notifications. The harness enforces a minimum of 5000ms.

Optional output notification config. Each terminal output which matches the pattern will notify you. ONLY set this when the user explicitly requests monitoring.

Hard timeout in milliseconds. The command will be killed after this time, even if running in background (defaults to 600000ms/10 minutes).

Timeout in milliseconds (defaults to 30000ms/30s)

PROPOSE a command to run on behalf of the user.
If you have this tool, note that you DO have the ability to run commands directly on the USER's system.
Note that the user may have to approve the command before it is executed.
The user may reject it if it is not to their liking, or may modify the command before approving it.  If they do change it, take those changes into account.
In using these tools, adhere to the following guidelines:
1. Based on the contents of the conversation, you will be told if you are in the same shell as a previous step or a different shell.
2. If in a new shell, you should `cd` to the appropriate directory and do necessary setup in addition to running the command. By default, the shell will initialize in the project root.
3. If in the same shell, LOOK IN CHAT HISTORY for your current working directory.
4. For ANY commands that would require user interaction, ASSUME THE USER IS NOT AVAILABLE TO INTERACT and PASS THE NON-INTERACTIVE FLAGS (e.g. --yes for npx).
5. If the command would use a pager, append ` | cat` to the command.
6. For commands that are long running/expected to run indefinitely until interruption, please run them in the background. To run jobs in the background, set `is_background` to true rather than changing the details of the command.
7. Dont include any newlines in the command.

Executes a given command in a shell session with optional timeout.
Before executing the command, please follow these steps:
1. Check for Running Processes:
   - Before starting dev servers or long-running processes that should not be duplicated, search the terminals folder to check if they are already running in existing terminals.
   - You can use this information to determine which terminal, if any, matches the command you want to run, contains the output from the command you want to inspect, or has changed since you last read them.
   - Since these are text files, you can read any terminal's contents simply by reading the file, search using the grep tool, etc.
2. Command Execution:
   - Always quote file paths that contain spaces with double quotes (e.g., cd "path with spaces/file.txt")
   - Examples of proper quoting:
     - cd "/Users/name/My Documents" (correct)
     - cd /Users/name/My Documents (incorrect - will fail)
     - python "/path/with spaces/script.py" (correct)
     - python /path/with spaces/script.py (incorrect - will fail)
   - After ensuring proper quoting, execute the command.
   - Capture the output of the command.
Usage notes:
- The command argument is required.
- You can specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). If not specified, commands will timeout after 30000ms (30 seconds).
- It is very helpful if you write a clear, concise description of what this command does in 5-10 words.
- Avoid using search commands like `find` and `grep`. Instead prefer Grep, Glob to search. Avoid read tools like `cat`, `head`, and `tail`, and prefer Read to read files.
- If you _still_ need to run `grep`, STOP. ALWAYS USE ripgrep at `rg` first, which all users have pre-installed.
- When issuing multiple commands, use the ';' or '&&' operator to separate them. DO NOT use newlines (newlines are ok in quoted strings).
- Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of `cd`. You may use `cd` if the User explicitly requests it.<good-example>pytest /foo/bar/tests</good-example><bad-example>cd /foo/bar && pytest tests</bad-example>

You can monitor commands by configuring `notify_on_output`. You will be notified at the end of your turn whenever stdout/stderr output matches the regex `pattern`. Output redirected only to a file will not trigger it. Configure a 5-or-fewer-word `reason` explaining what you are watching for, and optionally configure `debounce_ms`.

Use a descriptive tmux session name for the task or command instead of a single global shared name. Prefer short kebab-case names such as `vite-dev-server`, `backend-tests`, or `db-migration`.

There is one canonical shared tmux session for most recurring shell work — `${e}`. Start or reuse that session before ordinary setup work, then use it for every install, build, migration, version check, and verification command. Only create a separate descriptively-named session (short kebab-case, e.g. `vite-dev-server`, `backend-tests`, `postgres`) for long-running side processes that must keep running after a single command finishes. Do NOT invent a new per-task session name for ordinary shell work — route it through `${e}`.

<tmux-backed-shell-sessions>
- tmux is the required mechanism for shell work that may outlive a single command. If you need an interactive shell, any background command (such as starting dev servers), a long-running process, follow-up input, later inspection, or a shared session that you or the user may reconnect to later, you MUST use tmux. Do NOT launch those workflows as one-shot background processes. If you are planning to set block_until_ms to 0, you should ALWAYS back this session with tmux.
- ${Lge(t)}
- ${r}
- Start or reuse the appropriate session by running `${$ge({sharedSessionName:e,selfHostedMachine:t})}`.
- Before creating a new session, list existing sessions with `${n} ls` and reuse an existing one when appropriate.
- To inspect or continue work in an existing session, attach with `${n} attach-session -t "$SESSION_NAME"`.
- To send input to a session without attaching, run `${n} send-keys -t "$SESSION_NAME:0.0" 'your command here' C-m`.
</tmux-backed-shell-sessions>

${e}

${t.join("\n\n")}

Execute shell commands in the workspace.

- The shell is stateful - cwd & env vars persist for subsequent calls.
- Make efficient use of shell calls and minimize wasted tokens.
- Batch related shell work together or run independent checks in parallel when safe. Make liberal use of `&&`, `;`, pipes, greps and other efficient shell use.
- Use targeted, output-limited terminal commands such as `rg`, `head`, `tail`, `sed -n`, when relevant to limit output.
- NEVER use `set -x`; it breaks this tool. If it gets set, run `set +x` to fix the shell.
- Optimize for overall cost, including cache reads, cache writes, and output tokens.
- Use the 'Workspace Path' field in the `<user_info>` section to resolve the workspace path. It will likely NOT be at `/workspace`; don't waste time trying that.
- Still do whatever validation is necessary to ensure the judgment is correct; efficiency means avoiding waste, not skipping verification.
- This may still be a long-running investigation if correctness requires it, but do not spend tokens on status updates, progress narration, or UX niceties while judging.
- Always quote paths that contain spaces.

${e}

${t.join("\n\n")}

Executes a given command in a shell session, waiting for output for `block_until_ms` millis.

${t}

${f}

${r}
${g}