Guide: Fix Cursor Agent Terminal Hangs Caused by .zshrc
Problem
When using Zsh with custom configs like Oh My Zsh
, you might notice:
- Cursor Agent terminal hangs indefinitely after running a command
- You must click “Move to background” or “Skip” every time
- Meanwhile, Cursor’s interactive terminal (Ctrl+ `) works fine
This is caused by your .zshrc
loading interactive or slow components (e.g., themes, plugins), which interfere with Cursor Agent’s ability to detect command completion.
Step 1 — Confirm the issue
Run this inside Cursor’s Agent terminal (e.g., via a “Run terminal command” block):
zsh -i -c 'pwd'
If it hangs or never completes (despite printing output), the issue is confirmed.
Step 2 — Identify the difference
Run this in both terminals:
env > ~/env_from_this_terminal.txt
Compare them:
diff ~/env_from_interactive.txt ~/env_from_agent.txt
In our testing, the Agent shell had:
PAGER=head -n 10000 | cat
COMPOSER_NO_INTERACTION=1
These do not exist in the interactive terminal.
Step 3 — Patch your .zshrc
To skip loading the rest of your config inside Cursor Agent shell only, add this to the top of your ~/.zshrc
:
if [[ "$PAGER" == "head -n 10000 | cat" || "$COMPOSER_NO_INTERACTION" == "1" ]]; then
return
fi
What this does:
Skips .zshrc only inside Agent
Keeps full
Oh My Zsh
behavior in:- Cursor’s Ctrl+ ` interactive terminal
- iTerm / Terminal
- VSCode terminal
No command overrides, no flags
, no breaking changes.
Optional: Comment block
You can include this for clarity in .zshrc
:
if [[ "$TERM_PROGRAM" == "vscode" || "$TERM_PROGRAM" == "cursor" ]]; then
return
fi
Confirmed working on:
- macOS 26.x / Zsh 5.9+
- Oh My Zsh
- Cursor v1.1.3+
- Apple Silicon (M1/M2)