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.

9

Good question. There isn’t currently a built-in way to share an existing terminal session with the agent.

That said, there are a few approaches that work reasonably well for Nix-based workflows.

1. Use Rules to allow longer terminal timeouts (quick win)
The agent sends terminal commands to the background when they exceed a timeout (roughly ~1 minute). With commands like nix develop -c, that delay can make the agent think the command is stuck.

You can add a project rule (for example: .cursor/rules/nix.mdc) to guide the agent:

  • When running Nix-related commands (nix develop, nix build, nix shell), allow a long maximum block time (at least ~120 seconds).

  • Do not treat slow output as a failure.

  • Always prefix commands that need the Nix environment with nix develop -c.

2. Use direnv + nix-direnv for near-instant environments
The standard solution in the Nix ecosystem is nix-direnv, which caches the nix develop environment so it loads almost instantly after the first build.

To make this work with the agent’s non-interactive shell:

  • Install direnv (e.g., brew install direnv)

  • Set up nix-direnv

  • Add a .envrc with use flake in your project root

  • Then add this to ~/.zshenv:

# ~/.zshenv
if [[ -n "$CURSOR_AGENT" ]]; then
  eval "$(direnv export zsh)"
fi

Note: this uses direnv export zsh, which directly sets environment variables. The usual direnv hook zsh relies on interactive shell hooks that don’t run in the agent’s non-interactive environment.

After the first nix develop build, the cached environment loads in milliseconds.

3. TMUX session (advanced)
If you want the agent to run commands inside an already-active nix develop shell, you can:

  • Start a tmux session with the Nix environment preloaded

  • Add a rule instructing the agent to send commands using tmux send-keys

This avoids paying the startup cost entirely, but it’s a more hands-on setup.

The core limitation is that each agent terminal command runs in a fresh shell, so there’s no persistent session to “enter” Nix once. In practice, the direnv approach tends to be the smoothest workaround — the environment is simply present for every command without the agent needing to manage it explicitly.