Composer agent runs npm test, sees “3 passing,” declares “all tests pass ✅.” You open your terminal, run the same command, get 10 failing. Or it cd packages/web && npm install, says done a few seconds later, and ls node_modules shows nothing installed. Cursor’s agent terminal isn’t a perfect mirror of your daily zsh: independent cwd state, may not source your .zshrc, truncates long output, and shell state across commands isn’t always sticky.
Fix: replace “I assume it knows” with “I tell it explicitly in the prompt.”
Common causes
1. Working directory isn’t what you think
The agent’s terminal session defaults to the workspace root. You think it’s in packages/web/; it’s actually at the monorepo root running npm test against the wrong package.
How to judge: have the agent run pwd and report; compare with your expected dir.
2. Agent used npm but project is pnpm / yarn / bun
Training prior is npm. Even with pnpm-lock.yaml present, the agent may ignore it and run npm install, scrambling the lockfile.
How to judge:
ls *-lock.* 2>/dev/null
# is it pnpm-lock.yaml / yarn.lock / bun.lockb / package-lock.json?Agent didn’t acknowledge the tool = prior won.
3. .envrc / direnv / .env didn’t load in the agent shell
direnv depends on shell hooks; the subprocess Cursor spawns may not get them. process.env.DATABASE_URL is undefined for the agent.
How to judge: have the agent run env | grep MY_VAR; empty = not loaded.
4. Long output truncated; agent sees only the start
Cursor caps stdout at a few hundred lines before handing to the model. With 5000-line test output, the agent might only see the first 500 — the “Running tests…” prelude with no signal.
How to judge: have it echo last 50 lines; compare to your real tail.
5. Background process pollutes the terminal
Earlier the agent started npm run dev and never killed it; new command output mixes with the dev log, confusing the agent.
How to judge: lsof -i :3000 or ps aux | grep node for leftovers.
6. Exit code 0 ≠ correct outcome
npm install exits 0 with stale lockfile; git push says “Everything up-to-date” — agent treats exit code as truth without checking the actual outcome.
How to judge: after “success,” verify manually (curl the endpoint, view the page, query the DB). Mismatch = agent didn’t verify.
Before you start
- Distinguish Composer agent auto-run vs you manually running in Cursor terminal — the former often misses shell init.
- Commit or branch before reproducing so bad commands don’t pollute the repo.
- Note Cursor version, active model, agent vs chat.
Info to collect
- The exact command the agent ran + its observed output + its conclusion.
- Your real output running the same command manually.
- Repo’s lockfile type (pnpm-lock.yaml etc.).
- Whether you use direnv /
.envrc. - Any leftover background processes.
Shortest fix path
“Verify state → correct usage.”
Step 1: Make the agent self-verify
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 -- --run--run-style flags avoid hanging watch mode. Always cd; never rely on inherited cwd.
Step 3: Source env explicitly
direnv projects:
Before running any code that needs env vars, source .envrc explicitly:
source .envrc && env | grep DATABASE_URL
Verify the var is set, then run the actual command.Or list required env in .cursorrules so the model knows up-front:
# .cursorrules
This project requires the following env vars:
- DATABASE_URL
- REDIS_URL
- STRIPE_SECRET_KEY
To load them: `source .envrc` (uses direnv) or `set -a && . .env && set +a` (uses dotenv).
You MUST verify these are set before any database / API command.Step 4: Make the agent grab the tail of test output
After running `pnpm test`, run:
tail -100 <(pnpm test 2>&1)
Or pipe to a file:
pnpm test > /tmp/test-output.log 2>&1; tail -200 /tmp/test-output.logStops truncation from hiding the failure.
Step 5: Clean up background processes
# find port hog
lsof -i :3000
# kill it
kill -9 <PID>
# or wipe all node
pkill -f nodeBefore agent restarts a dev server, have it lsof -i :3000 to check.
Step 6: Make the agent verify outcomes, not exit codes
After `npm 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: package.json scripts as the single entry point
Put all common commands in scripts:
"scripts": {
"dev": "...",
"test": "vitest run",
"build": "vite build",
"db:migrate": "prisma migrate deploy"
}Then prompts say “run pnpm test” not “run vitest run.” Script changes propagate automatically.
How to verify the fix
- Restart Cursor and reproduce — not transient session state.
- Open a different repo or machine to separate Cursor config from project state.
- Have a teammate retry on the same repo — confirms it isn’t only your local cache.
If it still fails
- Reduce repro to one command preceded by
pwd. - Roll back the most recent
.cursorrules/ settings.json change. - Search forum.cursor.com for “agent terminal wrong dir” / “agent didn’t see env”; include prompt + output.
- Grab View → Output → Cursor agent logs and post to Bug Reports.
Prevention
.cursorrulesmandates “Always pwd before any command” + names the package manager + env loading recipe.- One package manager per repo; delete stale lockfiles.
- Funnel complex commands through
package.jsonscripts; don’t let the agent assemble underlying commands. - Run long-lived dev servers in
tmux/screen/ a separate VS Code task, not in the agent terminal. - After the agent says “done,” prompt it to verify at the business layer (endpoint / data / file existence) — not just exit code.