Cursor terminal documentation missing non-interactive agent shell configuration guidance

Ideas Feedback
,
6

Hey there,

Thanks for the detailed feedback.

The agent terminal has two phases:

  • Initialization phase: captures a shell state snapshot (and does source ~/.zshrc).

  • Command execution phase: runs non-interactively (so only ~/.zshenv is loaded).

That’s why the current docs guidance for disabling heavy prompts via $CURSOR_AGENT in ~/.zshrc works — the init phase reads it. But for tools like fnm, nvm, or direnv that need to be available during command execution, ~/.zshenv is the right place:

# ~/.zshenv
if [[ -n "$CURSOR_AGENT" ]]; then
  eval "$(fnm env)"
fi

This ensures the tool is available regardless of whether the shell is interactive or not.

We’ve passed the documentation feedback to the team. You may also find this community guide helpful for additional context: Guide: Fix Cursor Agent Terminal Hangs Caused by .zshrc.

Best,
Mohit