The agent runs npm test, sees “3 passing,” declares “all tests pass.” You run the same command yourself and get 10 failing. Or it does cd packages/web && npm install, says done a few seconds later, and ls node_modules shows nothing installed. Cursor’s agent terminal is not a mirror of your daily zsh: it spawns a non-interactive shell with its own working directory, it does not source ~/.zshrc, it truncates long output, and shell state does not reliably carry across separate commands.
Fastest fix: stop assuming the agent knows your setup. Add a .cursor/rules/*.mdc rule that forces it to pwd and name the package manager before any command, and make it verify the outcome instead of trusting the exit code. The single biggest correctness change as of June 2026 is moving rules out of the legacy .cursorrules file (see below) — that file is silently ignored in Agent mode.
Which bucket are you in?
| Symptom | Most likely cause | Jump to |
|---|---|---|
| ”Tests pass” but they don’t / wrong package built | Wrong working directory | Cause 1 |
Lockfile churned, node_modules empty | Used npm on a pnpm/yarn/bun repo | Cause 2 |
process.env.X undefined, DB/API calls fail | .envrc / .env not loaded in agent shell | Cause 3 |
| Agent “can’t see” the failure in a big log | Output truncated from the beginning | Cause 4 |
| Output mixes with a running dev server | Leftover background process | Cause 5 |
| Command “succeeds” but nothing changed | Exit code 0 treated as truth | Cause 6 |
| Every command hangs / output is garbled | .zshrc theme (Powerlevel10k / oh-my-zsh) | Cause 7 |
| Your rules seem ignored entirely | Rules still in legacy .cursorrules | Step 7 |
Common causes
1. Working directory isn’t what you think
The agent’s terminal session defaults to the workspace root. You think it is in packages/web/; it is actually at the monorepo root running npm test against the wrong package. Cursor still has open bug reports (June 2026) where the terminal does not follow the active workspace and where subagent worktree isolation leaves the parent session pointing at a directory that no longer exists.
How to judge: have the agent run pwd and report it; compare with your expected dir.
2. Agent used npm but the project is pnpm / yarn / bun
The model’s training prior is npm. Even with a pnpm-lock.yaml present, the agent may ignore it and run npm install, which rewrites the lockfile and can produce a different dependency tree.
How to judge:
ls *-lock.* package-lock.json 2>/dev/null
# pnpm-lock.yaml / yarn.lock / bun.lock(b) / package-lock.json — which one?If the agent ran a command without acknowledging the matching tool, the prior won.
3. .envrc / direnv / .env didn’t load in the agent shell
This is shell mechanics, not a Cursor bug. Non-interactive shells do not source ~/.zshrc or ~/.zprofile, and direnv hooks itself into those files. So the agent’s subprocess never runs the hook and process.env.DATABASE_URL is undefined for it.
How to judge: have the agent run env | grep MY_VAR; empty output means it never loaded.
4. Long output truncated; agent sees the wrong slice
Cursor caps how much stdout it hands to the model and, as of 2026, truncates from the start — you will see a banner like [Terminal output truncated: ~85KB dropped from beginning]. With a 5000-line test run the model may keep the tail but lose the failing-test summary that scrolled off the top, or vice versa depending on the tool. Either way it is reasoning over a partial log.
How to judge: ask it to print tail -50 (or head -50) of the real output and compare to what you see running the command yourself.
5. Background process pollutes the terminal
Earlier the agent started npm run dev and never killed it; new command output mixes with the still-streaming dev log, and the agent reads the dev server’s lines as the result of the new command.
How to judge: lsof -i :3000 or ps aux | grep node to find leftovers.
6. Exit code 0 ≠ correct outcome
npm install exits 0 with a stale lockfile; git push prints “Everything up-to-date”; a build “succeeds” but emits nothing. The agent treats the exit code as proof of success without checking the real outcome.
How to judge: after “success,” verify the effect manually (curl the endpoint, load the page, query the DB, list the artifact). A mismatch means the agent never verified.
7. .zshrc theme hangs or garbles the agent terminal
This one is widely under-diagnosed. The agent runs commands in a shell that still loads your ~/.zshrc, and heavy interactive setups — Powerlevel10k, oh-my-zsh, async prompts, dynamic icons — emit control sequences and prompt redraws that the agent’s output parser can’t reconcile. The result is commands that appear to hang (the agent never detects completion), garbled output, or a command that “ran” with empty captured output.
How to judge: the same command runs instantly in your normal terminal but stalls or returns junk for the agent. Cursor injects these env vars into the agent shell, so you can detect it: PAGER=head -n 10000 | cat, COMPOSER_NO_INTERACTION=1, PIP_NO_INPUT=true (and TERM_PROGRAM=cursor). See Step 8.
Before you start
- Distinguish the Composer agent auto-running a command from you running it in the Cursor terminal — only the former goes through the non-interactive agent shell.
- Commit or branch before reproducing so a bad command doesn’t pollute the repo.
- Note your Cursor version (Cursor → About), the active model, and whether you’re in agent vs chat.
Info to collect
- The exact command the agent ran, its observed output, and the conclusion it drew.
- Your real output running the same command manually.
- The repo’s lockfile type (
pnpm-lock.yaml, etc.). - Whether you use direnv /
.envrc. - Any leftover background processes.
- Whether your
~/.zshrcloads a heavy theme/plugin manager.
Shortest fix path
Order is: verify state, then correct usage, then harden config.
Step 1: Make the agent self-verify before every command
Standard prefix for any agent-run command:
Before running any command, first run and report:
1. `pwd` — confirm working directory
2. `which pnpm npm yarn bun` — confirm package manager available
3. `cat package.json | grep '"name"'` — confirm correct package
Only proceed if all three match the expected target.Step 2: Spell out package manager + path
Run this exact command, do NOT substitute:
cd packages/web && pnpm test -- --runA --run-style flag avoids hanging in watch mode. Always cd into the target; never rely on an inherited cwd.
Step 3: Source env explicitly
For direnv projects:
Before running anything that needs env vars, source it explicitly:
source .envrc && env | grep DATABASE_URL
Confirm the var is set, then run the actual command.For dotenv projects use set -a && . .env && set +a instead. Or declare the required vars in a rule so the model knows up front (see Step 7).
Step 4: Make the agent grab the real test output
Because Cursor truncates, pipe to a file and read the part you care about:
After running the tests, capture full output and read the summary:
pnpm test > /tmp/test-output.log 2>&1; tail -200 /tmp/test-output.log
# if the failing summary is at the top instead, use: head -200 /tmp/test-output.logThe file always holds the complete log even when the inline view is truncated.
Step 5: Clean up background processes
# find what holds the port
lsof -i :3000
# kill it
kill -9 <PID>
# or wipe stray node processes
pkill -f nodeBefore the agent restarts a dev server, have it run lsof -i :3000 first.
Step 6: Make the agent verify outcomes, not exit codes
After `pnpm install`, verify by:
ls node_modules | wc -l # should be > 100
cat node_modules/.package-lock.json | jq '.packages | length'
After `git push`, verify by:
git log origin/main --oneline | head -3 # should show your commitStep 7: Move rules to .cursor/rules/*.mdc (not .cursorrules)
This is the most important update as of June 2026. The single-file .cursorrules at the repo root is the legacy format and is silently ignored in Agent mode — so the rules you wrote to fix all of the above may never load. Cursor’s current format is per-rule .mdc files in .cursor/rules/, each with YAML frontmatter (description, globs, alwaysApply).
Create .cursor/rules/terminal.mdc:
---
description: Shell command discipline for the agent terminal
alwaysApply: true
---
- Always run `pwd` and confirm the working directory before any command.
- This repo uses pnpm. Never run npm or yarn. Run `cd <pkg> && pnpm ...`.
- Required env vars: DATABASE_URL, REDIS_URL, STRIPE_SECRET_KEY.
Load them with `source .envrc` (direnv) before any DB/API command and verify with `env | grep`.
- After install/build/push, verify the real outcome, not the exit code.
- Capture long output to a file and read head/tail; do not trust the inline preview.With alwaysApply: true the rule is injected into every agent session. Use globs (e.g. packages/web/**) instead if a rule should only apply in part of a monorepo. You can keep an existing .cursorrules during migration (Cursor still reads it in non-agent contexts), but anything you rely on in Agent mode must live in .cursor/rules/.
Step 8: Stop your ~/.zshrc from breaking the agent shell
If commands hang or come back garbled (Cause 7), guard your interactive config so it is skipped inside the agent. Add this near the top of ~/.zshrc:
# Skip heavy interactive setup inside Cursor's agent / VS Code shell
if [[ "$TERM_PROGRAM" == "cursor" || "$TERM_PROGRAM" == "vscode" \
|| "$COMPOSER_NO_INTERACTION" == "1" ]]; then
return
fiThat keeps your full theme in normal terminals while giving the agent a clean shell. If you actually need PATH or env vars in the agent shell, put them in ~/.zshenv instead — that file is sourced by non-interactive shells, which is exactly the gap behind Cause 3.
How to verify the fix
- Ask the agent to re-run the failing command and report
pwd, the package manager, and a real outcome check (not just “done”). - Restart Cursor and reproduce, so you know it isn’t transient session state.
- Open a different repo or machine to separate Cursor config from project state.
- Have a teammate retry on the same repo to confirm it isn’t only your local cache.
If it still fails
- Reduce the repro to one command preceded by
pwd. - Roll back the most recent
.cursor/rulesorsettings.jsonchange. - Search forum.cursor.com for “agent terminal wrong dir” / “agent didn’t see env” / “terminal output truncated”; include your prompt and output.
- Grab View → Output → Cursor (agent logs) and post to Bug Reports.
FAQ
Why does the agent say tests pass when they fail?
Usually wrong working directory (Cause 1) or truncated output (Cause 4): it either ran tests against the wrong package or only read the part of the log without the failures. Force a pwd check and pipe output to a file.
My .cursorrules worked before and now seems ignored — what changed?
As of 2026 the legacy single-file .cursorrules is silently ignored in Agent mode. Move the content into .cursor/rules/*.mdc with alwaysApply: true. See Step 7.
The agent terminal hangs forever on simple commands.
Your ~/.zshrc is loading an interactive theme (Powerlevel10k / oh-my-zsh) that the agent’s parser can’t reconcile, so it never sees the command finish. Add the TERM_PROGRAM/COMPOSER_NO_INTERACTION guard from Step 8.
Why are my env vars undefined only for the agent?
The agent’s shell is non-interactive and doesn’t source ~/.zshrc/~/.zprofile, so direnv and dotenv hooks never run. Source the file explicitly per command, or move PATH/env into ~/.zshenv.
How do I make the agent stop using npm on a pnpm repo?
Put This repo uses pnpm. Never run npm or yarn. in an always-applied .cursor/rules file and route commands through package.json scripts so the agent runs pnpm test, not vitest run.
Prevention
- Keep terminal rules in
.cursor/rules/*.mdc(alwaysApply: true): “alwayspwdfirst,” the package-manager name, and the env-loading recipe. - One package manager per repo; delete stale lockfiles.
- Funnel complex commands through
package.jsonscripts so the agent runspnpm test, not an assembled underlying command. - Run long-lived dev servers in
tmux/screen/ a separate VS Code task, not in the agent terminal. - Guard
~/.zshrcagainst the agent shell and keep PATH/env in~/.zshenv. - After the agent says “done,” prompt it to verify at the business layer (endpoint / data / file existence), not just the exit code.