[BUG] Claude Code Hangs with Next.js Dev Server + `run_in_background`

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Environment

• Claude Code Version: 2.1.15
• Model: claude-opus-4-5-20251101
• OS: Windows 10 (MINGW64_NT-10.0-26100)
• Node.js: v24.13.0
• npm: 11.6.2
• Next.js: 16.1.2
• Shell: Git Bash (MINGW64)

Description

Claude Code hangs indefinitely after running Next.js dev server with run_in_background: true. The UI shows "Cogitated for Xm" followed by "Creating... ↓ 0 tokens" and never progresses. Only recovery is manual cancellation (Esc key).

Root Cause (Narrowed Down Through Testing)

The bug is specific to: Next.js dev server + run_in_background: true parameter

Systematic Test Results

| Command | run_in_background | Duration | Result |
|---------|---------------------|----------|--------|
| sleep 240 | true | Finite | OK |
| npm run lint | true | Short | OK |
| npm run build | true | Medium | OK |
| node -e "setInterval(() => console.log('tick'), 1000)" | true | Infinite | OK |
| while true; do echo tick; sleep 1; done | true | Infinite | OK |
| npm run dev | false (plain &) | Infinite | OK |
| npm run dev | true | Infinite | HANG |
| npx next dev | true | Infinite | HANG |

Key Findings

1. Other infinite/long-running processes work fine with run_in_background: true
2. Next.js dev server works fine with plain bash &
3. Only the combination of Next.js dev server + run_in_background: true causes the hang
4. The hang occurs AFTER the command starts successfully - on the NEXT API request
5. Not related to npm specifically (both npm run dev and npx next dev hang)

Debug Log Evidence

From ~/.claude/debug/<session-id>.txt, the pattern before each hang:

[DEBUG] [API:request] Creating client, ANTHROPIC_CUSTOM_HEADERS present: false, has Authorization header: false
[DEBUG] [API:auth] OAuth token check starting
[DEBUG] [API:auth] OAuth token check complete
[DEBUG] Stream started - received first chunk
[DEBUG] Stream started - received first chunk

Then no more log entries until user manually cancels. The stream starts but no tokens ever arrive.

Hypothesis

Next.js dev server does something unusual with:

• Process spawning (Turbopack workers, file watchers, multiple child processes)
• stdout/stderr handling (possibly unbuffered or special formatting)
• Signal handling

...that conflicts with Claude Code's run_in_background task monitoring/output capture mechanism.

Workaround

Use plain bash & instead of run_in_background: true for Next.js dev server:

# This hangs:
# Bash tool with run_in_background: true
npm run dev

# This works:
# Bash tool without run_in_background
npm run dev &

Steps to Reproduce

1. Open Claude Code in a Next.js project
2. Run: npm run dev with run_in_background: true parameter
3. Wait for command to start (output file created)
4. Claude responds successfully
5. Send any follow-up message
6. Observe: "Cogitated for Xm" completes, then "Creating... ↓ 0 tokens" hangs indefinitely

Additional Context

• Using OAuth authentication (not API key)
• Tested on Windows 10 with Git Bash
• Next.js 16.1.2 with Turbopack
• Issue is 100% reproducible (5/5 attempts)

Additional Information

<img width="910" height="797" alt="Image" src="https://github.com/user-attachments/assets/18076e5c-740d-4dd3-b0f7-41678d0aa07b" />