# 🛠️ Guide: Fix Cursor Agent Terminal Hangs Caused by .zshrc

**URL:** <https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260>\
**Category:** Guides\
**Created:** [June 21, 2025, 8:23pm UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260 "2025-06-21T20:23:11Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![Llewrys](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/llewrys/32/65347_2.png) [@Llewrys](https://forum.cursor.com/u/Llewrys)\
**Post date:** [June 21, 2025, 8:23pm UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/1 "2025-06-21T20:23:11Z")

</div>

## 🛠 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):

```bash
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:

```bash
env > ~/env_from_this_terminal.txt

```

Compare them:

```bash
diff ~/env_from_interactive.txt ~/env_from_agent.txt

```

In our testing, the Agent shell had:

```bash
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`:

```zsh
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`:

```zsh
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)

---

<div class="post-metadata">

**Author:** ![simplenotezy](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/simplenotezy/32/64763_2.png) [@simplenotezy](https://forum.cursor.com/u/simplenotezy)\
**Post date:** [June 23, 2025, 2:32pm UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/2 "2025-06-23T14:32:09Z")

</div>

Thanks for sharing!

---

<div class="post-metadata">

**Author:** ![eldar](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/eldar/32/65967_2.png) [@eldar](https://forum.cursor.com/u/eldar)\
**Post date:** [June 25, 2025, 6:16am UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/3 "2025-06-25T06:16:43Z")

</div>

This resolved my issue for now (MacOS):

> ### 🧼 Optional: Comment block
> 
> You can include this for clarity in `.zshrc`:
> 
> ```auto
> if [["$TERM_PROGRAM" == "vscode" || "$TERM_PROGRAM" == "cursor"]]; then
> return
> fi
> 
> ```

---

<div class="post-metadata">

**Author:** ![Sceptre](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/sceptre/32/66681_2.png) [@Sceptre](https://forum.cursor.com/u/Sceptre)\
**Post date:** [June 26, 2025, 9:02pm UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/4 "2025-06-26T21:02:15Z")

</div>

Epic, thanks so much for the fix!

---

<div class="post-metadata">

**Author:** ![pjl](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/pjl/32/56416_2.png) [@pjl](https://forum.cursor.com/u/pjl)\
**Post date:** [June 26, 2025, 9:43pm UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/5 "2025-06-26T21:43:07Z")

</div>

I observe the issue on bash on Ubuntu. Is there an analogous fix, or is this specific to zsh?

---

<div class="post-metadata">

**Author:** ![roberto-utilityprofi](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/roberto-utilityprofi/32/66684_2.png) [@roberto-utilityprofi](https://forum.cursor.com/u/roberto-utilityprofi)\
**Post date:** [June 27, 2025, 5:14am UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/6 "2025-06-27T05:14:57Z")

</div>

> [@Llewrys](#):
>
> ```auto
> if [["$PAGER" == "head -n 10000 | cat" || "$COMPOSER_NO_INTERACTION" == "1"]]; then
> return
> fi
> 
> ```

thank you!!!

---

<div class="post-metadata">

**Author:** ![Llewrys](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/llewrys/32/65347_2.png) [@Llewrys](https://forum.cursor.com/u/Llewrys)\
**Post date:** [June 27, 2025, 11:50am UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/7 "2025-06-27T11:50:23Z")

</div>

Hey! I’m primarily on `macOS` using `Zsh`, so I haven’t tested this on `Bash/Ubuntu` directly — but the root cause is likely the same:

> The Cursor Agent terminal injects unique environment variables to indicate it’s running in “Agent mode”, and if your shell config (like `.bashrc`) runs interactive-only logic (e.g., prompts, aliases, plugins), it can prevent the Agent from detecting command completion.

* * *

To adapt the fix for Bash, you can try the following:

1. Run these two commands inside Cursor:

2. Then compare:

3. If you find any **env var that only exists in the Agent terminal** , you can use it at the top of your .bashrc to short-circuit:

> This will prevent Bash from loading the rest of .bashrc in the Agent shell — keeping it clean and non-interactive.

* * *

Let me know if you find a reliable flag! Would be happy to update the solution to support Bash officially.

---

<div class="post-metadata">

**Author:** ![Khan.sensei](https://avatars.discourse-cdn.com/v4/letter/k/76d3ee/32.png) [@Khan.sensei](https://forum.cursor.com/u/Khan.sensei)\
**Post date:** [June 29, 2025, 12:10pm UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/8 "2025-06-29T12:10:10Z")

</div>

VS code terminal running commands doesn’t have this issue, i have p10k theme on , and in vs code it works completely fine and doesn’t get stuck, unlike cursor its gets stuck

---

<div class="post-metadata">

**Author:** ![Llewrys](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/llewrys/32/65347_2.png) [@Llewrys](https://forum.cursor.com/u/Llewrys)\
**Post date:** [June 29, 2025, 12:26pm UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/9 "2025-06-29T12:26:38Z")

</div>

You’re absolutely right — the issue doesn’t happen in the **VS Code integrated terminal** , even with full themes like `p10k`, because that terminal is interactive and behaves like a normal user shell.

However, the **Cursor Agent** doesn’t use an interactive terminal. It spawns a headless shell in the background to execute commands — and this non-interactive behavior is **exactly where the problem comes in**.

Tools like `Oh My Zsh`, `p10k`, or custom `.bashrc/.zshrc` configs are designed for interactive shells. When they run in a background, non-interactive context (like the Agent), they can interfere with the process output or hang waiting for terminal input, which causes the Agent to “freeze” or never detect completion.

That’s why the fix we propose only bypasses config **inside the Agent terminal** , but keeps everything fully enabled in VS Code, iTerm, or Cursor’s **Ctrl + `** terminal.

Let me know if you want to verify whether your config loads in non-interactive shells — happy to walk you through it.

---

<div class="post-metadata">

**Author:** ![Khan.sensei](https://avatars.discourse-cdn.com/v4/letter/k/76d3ee/32.png) [@Khan.sensei](https://forum.cursor.com/u/Khan.sensei)\
**Post date:** [June 29, 2025, 1:10pm UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/10 "2025-06-29T13:10:30Z")

</div>

Thank you for this fix; however, I think the cursor team should look into this. I personally like an interactive shell, because I can see the entire output clearly, especially since I’m learning mostly and don’t want just to run the command. At least they should give u the option

---

<div class="post-metadata">

**Author:** ![Llewrys](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/llewrys/32/65347_2.png) [@Llewrys](https://forum.cursor.com/u/Llewrys)\
**Post date:** [June 29, 2025, 2:05pm UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/11 "2025-06-29T14:05:09Z")

</div>

Totally fair — and I 100% agree this should be addressed at the core level by the Cursor team.

Our workaround just keeps the Agent functional for now, but long-term, this really should be a built-in option.

Appreciate you sharing your perspective 🙌

---

<div class="post-metadata">

**Author:** ![jinuk](https://avatars.discourse-cdn.com/v4/letter/j/b5ac83/32.png) [@jinuk](https://forum.cursor.com/u/jinuk)\
**Post date:** [June 29, 2025, 5:22pm UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/12 "2025-06-29T17:22:09Z")

</div>

The AI agent should get a new ability to send inputs to the shell and interpret interactive outputs, like scrolling the content with the `less` pager with hjkl 😐

---

<div class="post-metadata">

**Author:** ![Llewrys](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/llewrys/32/65347_2.png) [@Llewrys](https://forum.cursor.com/u/Llewrys)\
**Post date:** [June 29, 2025, 10:23pm UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/13 "2025-06-29T22:23:31Z")

</div>

Haha yep — interpreting interactive outputs like `less`, `vim`, or even `top` would be next-level 🤯

Right now, the Agent operates in a non-interactive shell and doesn’t have input control after launch — so it can’t respond to `--More--` prompts or scrollable output yet.

But you’re spot on: long-term, giving the Agent actual terminal input/output control would unlock much richer workflows. Definitely hope the team explores this kind of interactivity someday 👀

---

<div class="post-metadata">

**Author:** ![Laris](https://avatars.discourse-cdn.com/v4/letter/l/db5fbb/32.png) [@Laris](https://forum.cursor.com/u/Laris)\
**Post date:** [July 1, 2025, 8:45am UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/14 "2025-07-01T08:45:58Z")

</div>

it does not work in my `fish shell` env

```auto
# if test "$PAGER" = "head -n 10000 | cat"; or test "$COMPOSER_NO_INTERACTION" = "1"
# return
# end

```

---

<div class="post-metadata">

**Author:** ![Llewrys](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/llewrys/32/65347_2.png) [@Llewrys](https://forum.cursor.com/u/Llewrys)\
**Post date:** [July 1, 2025, 3:44pm UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/15 "2025-07-01T15:44:36Z")

</div>

Thanks for testing this in `fish` — you’re almost there!

Your syntax looks valid for Fish shell, but the environment variables used by Cursor Agent might not match exactly in your setup — especially if you’re on Linux or Windows/WSL. It’s worth confirming whether variables like `PAGER` or `COMPOSER_NO_INTERACTION` are actually being set inside the Agent terminal.

* * *

### ✅ Recommended steps:

1. **Compare the environment variables** between:
  - Cursor interactive terminal ( **Ctrl+`** )
  - Cursor Agent terminal (e.g. “Run this terminal command: `env > ~/env_fish_agent_terminal.txt`”)

Run this in each one:

- Cursor interactive terminal ( **Ctrl+`** ):

- 

```bash
env > ~/env_fish_ctrl_terminal.txt

```

- Cursor Agent terminal:

- 

```bash
env > ~/env_fish_agent_terminal.txt

```

Then compare:

```bash
diff ~/env_fish_ctrl_terminal.txt ~/env_fish_agent_terminal.txt

```

* * *

1. **Look for a unique variable** , like:

- `PAGER = head -n 10000 | cat`
- `COMPOSER_NO_INTERACTION = 1`
- Or anything specific to Agent (e.g. `PIP_NO_INPUT = 1`, etc.)

* * *

1. **Apply the condition at the top of your `~/.config/fish/config.fish`:**

```bash
if test "$PAGER" = "head -n 10000 | cat"; or test "$COMPOSER_NO_INTERACTION" = "1"
  return
end

```

> ✅ This will skip the rest of your config only inside the Cursor Agent terminal, but will still fully load your Fish shell config in your interactive terminals.

* * *

Let me know if you find a different variable — happy to update the solution for other fish users too!

---

<div class="post-metadata">

**Author:** ![hoblin](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/hoblin/32/69508_2.png) [@hoblin](https://forum.cursor.com/u/hoblin)\
**Post date:** [July 9, 2025, 3:07am UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/16 "2025-07-09T03:07:35Z")

</div>

I had the same issue with oh-my-zsh + antigen, and your hack helped. But then I found the `source $ZSH/oh-my-zsh.sh` at the end of the file after the `antigen apply`. So, in my case, the problem was caused by double omz initialization. Removing the `source $ZSH/oh-my-zsh.sh` fixed the issue with the Cursor terminal without the guard clause.

---

<div class="post-metadata">

**Author:** ![dephy](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/dephy/32/18455_2.png) [@dephy](https://forum.cursor.com/u/dephy)\
**Post date:** [July 16, 2025, 4:26pm UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/17 "2025-07-16T16:26:34Z")

</div>

FWIW, the same thing is happening on windows default cmd and most other profiles… Doesn’t appear specific to zsh.

So for the cursor team, please consider this post as a _possible_ workaround for certain zsh users, but it’s NOT a fix, as the issue plagues every terminal scenario i’ve used.

In the grand scheme, this seems like a silly thing to get frustrated with, given the efficiency gains immediately before the agent getting stuck 😆 - Keep up the good work!

---

<div class="post-metadata">

**Author:** ![kylie-bee](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/kylie-bee/32/71416_2.png) [@kylie-bee](https://forum.cursor.com/u/kylie-bee)\
**Post date:** [July 17, 2025, 3:17pm UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/18 "2025-07-17T15:17:27Z")

</div>

I’ve implemented this fix and continue to see terminal hangs on every terminal spawned within Ubuntu on WSL2. I use zsh but I have the fix and I can tell my `.zshrc` is being bypassed in the Agent’s terminal because none of my profile is loaded in that terminal. So it seems to be returning immediately but yet it still hangs. I reset my `oh-my-zsh` repo and restarted WSL2 and it works occasionally and then starts to hang again. This pretty much kills the usefulness for me.

---

<div class="post-metadata">

**Author:** ![Llewrys](https://sea3.discourse-cdn.com/cursor1/user_avatar/forum.cursor.com/llewrys/32/65347_2.png) [@Llewrys](https://forum.cursor.com/u/Llewrys)\
**Post date:** [July 17, 2025, 9:35pm UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/20 "2025-07-17T21:35:38Z")

</div>

Hey! So sorry it’s still giving you trouble — that sounds super frustrating.

From what you described, it seems like the fix isn’t being picked up because your `.zshrc` might not be loaded inside the agent’s terminal on WSL2.

**One quick thing you could try:**

> Move the fix into `~/.zprofile` instead — some login shells (especially under WSL) skip `.zshrc`, but still source `.zprofile`.

Also, if you’re using `oh-my-zsh`, make sure nothing overrides the `$PAGER` variable further down the config.

If you’re up for it, we can walk through this together and try to get it working step by step 🙌

---

<div class="post-metadata">

**Author:** ![Laris](https://avatars.discourse-cdn.com/v4/letter/l/db5fbb/32.png) [@Laris](https://forum.cursor.com/u/Laris)\
**Post date:** [July 26, 2025, 9:23am UTC](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260/22 "2025-07-26T09:23:58Z")

</div>

I found interesting test result.

Below is the diff env:

```auto
diff /tmp/env_fish_ctrl_terminal.txt.1 /tmp/env_fish_agent_terminal.txt.1

9a10
> COMPOSER_NO_INTERACTION=1

39c42
< PAGER=less -R
---
> PAGER=head -n 10000 | cat

40a44
> PIP_NO_INPUT=true

70,71c74
< VSCODE_INJECTION=1

```

it looks like a additional VSCODE\_INJECTION env in agent terminal.

And in current version, if I set below option true, it also works, from [[BUG] Terminal tool gets stuck after exit code - Bug Reports - Cursor - Community Forum](https://forum.cursor.com/t/bug-terminal-tool-gets-stuck-after-exit-code/57651/69)

```auto
"terminal.integrated.shellIntegration.enabled": true

```

But, when I use `remote-ssh` to ssh to another macos, it looks like not work in remote cursor’s terminal. the remote cursor cannot detect the finish status.

[Next page](https://forum.cursor.com/t/guide-fix-cursor-agent-terminal-hangs-caused-by-zshrc/107260.md?page=2)