Why Claude Code Hangs and How to Stop It

If you've left a Claude Code task running overnight expecting it to finish by morning, only to find it still waiting for input the next day—you've hit a hang.

It's one of the most common surprises developers encounter when they move from manual Claude Code sessions (where you're there to respond to prompts) to unattended automation (where the tool runs without you watching). The job doesn't fail spectacularly. It doesn't time out with a clear error. It just sits there, consuming API credits, waiting for input that's never coming.

This post covers what causes Claude Code hangs, why they happen specifically with background execution, and the techniques that prevent them.

What Is a Hang vs. a Failure?

Before we dig into causes, let's define the problem clearly.

A failure is when a Claude Code session encounters an error, reports it, and stops. The process exits. You see the error message. It's clear what went wrong.

A hang is when Claude Code reaches a state where it can't proceed, but it doesn't exit. It stays alive, waiting. This typically happens when the process expects user input—a confirmation prompt, a response to a question, a request to choose between options—and there's no one there to provide it.

The worst case is the silent hang. The process sits there for hours, the terminal appears frozen, API calls are still going out (Claude is thinking, retrying, backtracking), and from the outside it looks like it's still working. It's not. It's stuck.

The Three Root Causes of Hangs

1. The Input Loop

The most common cause of Claude Code hangs is the interactive input loop. Claude Code is designed to be collaborative—you can type instructions, and Claude Code responds with questions, asks for clarification, or requests permission to proceed.

When you're running Claude Code interactively, this is a feature. You can say "build a login form" and Claude Code asks "Should I use React or plain HTML?" and waits for your answer.

But when Claude Code runs in the background with no terminal attached, that question has nowhere to go. Claude Code waits. And waits. And waits.

This is especially common with:

• Multi-step prompts that require confirmation at each step
• File operations where Claude Code asks "Should I overwrite the existing file?"
• Git operations where the system expects you to confirm before force-pushing
• Dependency installations that prompt for permission

The solution isn't just to avoid interactive patterns—it's to run Claude Code in a way that automatically rejects input requests before they can block the process.

2. API Timeouts and Network Stalls

Claude Code connects to the Anthropic API. Most of the time this is instantaneous. But network conditions can cause delays or temporary disconnections.

When a network issue occurs:

• The API request hangs waiting for a response
• Claude Code's internal retry logic kicks in
• If the retry logic doesn't have a maximum attempt count or timeout, it can retry indefinitely
• The job never exits; it just keeps trying

This is less obvious than the input loop problem because the job isn't waiting for human input—it's genuinely trying to make progress. But the outcome is the same: a hung process consuming resources and API quota.

3. Subprocess Zombies

Claude Code often spawns subprocesses—running tests, building projects, executing shell commands. If a subprocess gets stuck or the parent process loses track of it, that zombie process can cause the entire job to hang.

Common scenarios:

• A build process (npm run build) hangs indefinitely
• A test suite gets stuck waiting for a database connection
• A shell command runs in the background and the parent doesn't wait for it to finish
• A background server (like a dev server) launches and never exits

The parent process either waits for the subprocess to finish (but it never does), or it exits leaving the subprocess orphaned.

How Silence Detection Prevents Hangs

This is where tools like OpenHelm come in. OpenHelm's silence detection is specifically designed to catch hangs before they become a problem.

Silence detection works like this:

1. OpenHelm monitors Claude Code's output stream continuously
2. If no output appears for a configured duration (10 minutes by default), OpenHelm considers the process "silent"
3. When silence is detected, OpenHelm stops the job immediately
4. The run is logged as failed, so you know it didn't complete successfully

This prevents the silent failure scenario: a job that looks like it's running but isn't actually making progress.

The 10-minute timeout is tuned for typical development tasks. Most Claude Code operations (file edits, API calls, test runs) produce output within a few minutes. If there's no output for 10 minutes, something has stalled.

You can adjust the silence threshold in OpenHelm's settings if you need longer timeouts for especially slow tasks.

Preventing Hangs: A Practical Checklist

If you're running Claude Code unattended, apply these preventative measures:

1. Use non-interactive flags and environment variables

When running Claude Code via CLI, pass --no-interaction or similar flags if available. Set environment variables that force non-interactive mode in your tools.

2. Add explicit timeouts to long-running operations

Don't let a task run indefinitely. Wrap operations in timeout commands:

timeout 300 npm run build  # Kill the build after 5 minutes

3. Avoid operations that prompt for user confirmation

Replace interactive git operations with automation flags:

# Instead of: git push (which might prompt)
git push --force-with-lease  # Explicit, non-interactive

4. Monitor output, not just exit codes

A process that exits with code 0 (success) but produced no output probably didn't do what you intended. Log output and check it.

5. Set explicit max retries on API calls

If your Claude Code task makes API calls, configure max retries and backoff strategies so requests eventually fail rather than retry forever.

6. Use OpenHelm's silence detection

The easiest solution: let OpenHelm handle timeout detection for you. Configure your jobs to run through OpenHelm, and silence detection automatically catches hung processes.

Common Hang Scenarios and Solutions

Scenario: Claude Code waits for file overwrite confirmation

• Cause: Claude is about to modify a file and asks "Should I overwrite?"
• Solution: Use the --force flag or set an environment variable that assumes "yes" to confirmations
• Prevention: Write prompts that avoid ambiguous operations. Instead of "improve the code", say "improve the code—you can overwrite existing files"

Scenario: A build process (`npm run build`) never exits

• Cause: The build tool or one of its dependencies is waiting for something
• Solution: Kill the process if it takes longer than expected. Use timeout wrapper
• Prevention: Test your build locally with the exact commands Claude Code will run

Scenario: API rate limiting causes infinite retries

• Cause: The Anthropic API is rate-limited, and the retry logic keeps trying
• Solution: Configure max retry counts and exponential backoff
• Prevention: Monitor your API usage beforehand. Know your rate limits

The Path Forward

Claude Code hangs aren't a fundamental flaw—they're a consequence of the mismatch between interactive and unattended execution. Interactive sessions are expected to wait for human input. Unattended sessions need to fail fast and report clearly.

Tools like OpenHelm bridge that gap by:

1. Detecting stalls automatically (silence detection)
2. Providing structured run history so you can see what actually happened
3. Supporting self-correction, so a failed run can automatically retry with corrected context

If you're planning to run Claude Code overnight or on a schedule, silence detection isn't optional—it's essential.

FAQ

Q: Will OpenHelm kill my job if it's legitimately taking a long time?

A: No. OpenHelm checks for silence (no output), not elapsed time. A job that's actively running—producing output, making API calls—will never be killed by silence detection, even if it runs for hours.

Q: Can I adjust the silence timeout?

A: Yes. OpenHelm lets you configure the silence threshold per job. If you have a task that legitimately needs longer than 10 minutes between outputs, set a higher threshold.

Q: What if I can't see the output? How will I know if it's silent or just quiet?

A: OpenHelm logs all output. Check the run history in the dashboard. You'll see timestamps of the last output. If the last output is 10+ minutes ago and the job is still running, silence detection kicked in.

Q: Can Claude Code ever be safely run unattended without silence detection?

A: Technically yes, but practically no. The hang scenarios above are common enough that detection is essential for reliable automation.