Cursor terminal documentation missing non-interactive agent shell configuration guidance

Ideas Feedback
,
1

Hi! I was reviewing the latest terminal docs for troubleshooting shell initialization (Terminal | Cursor Docs) and found they were outdated. The latest Cursor agent terminal spawns non-interactive shells that do not load profile dot files like the ~/.zshrc or ~/.zprofile. Instead, only the ~/.zshenv is loaded.

Therefore, Cursor Agent-specific initialization like fnm ( GitHub - Schniz/fnm: 🚀 Fast and simple Node.js version manager, built in Rust · GitHub ) must now be declared in the ~/.zshenv:
if [[ -n “$CURSOR_AGENT” ]]; then
eval “$(fnm env)”
fi

It would be great if the doc page were updated to include instructions for customizing the non-interactive shell environment, along with an updated troubleshooting section, since the current section refers to themes that mostly apply to the legacy integrated terminal: Terminal | Cursor Docs .

3

Thanks for the feedback, I’ve passed it on to the team.

1 Like
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

7

Thank you, Mohit! I will explore that further because I didn’t realize the ~/.zshrc was executed at all. My testing mostly involved adding print statements to my various ZSH config files to see what the agent shell would trigger.

Do you have any suggestions for a more complex shell integration? One that I’ve been struggling with is the Nix shell (nix develop - Nix Reference Manual). This has a much longer initialization time than an env variable export from direnv or pointing to the current Node.js version with FNM.

One workaround is to have the agent run nix commands via “nix develop -c ”, which works, but then you pay the start-up cost of a fresh Nix shell every time. It can often lead the agent to interpret the delay as a broken state, leading to various workarounds. Sometimes I’ll have to include custom instructions or prompts, like “Keep trying X for at least 10 minutes” or “The command Y might be slow, don’t give up.” I’ve also tried some workarounds with custom Cursor hooks that pre-pend various scripts to the agent shell commands, but they haven’t been very effective so far.

I was curious if there’s a better or more consistent way to share an existing terminal session or otherwise configure a lengthier “bootstrap” task, like entering a Nix shell, that would propagate to all non-interactive command shells from the IDE.