Fix Claude Code Not Responding: Terminal Hangs

When Claude Code freezes mid-conversation or your terminal stops responding, productivity comes to a halt. This guide covers practical solutions for diagnosing and fixing these issues, whether you are running a simple query or working on a complex project.

Identifying the Problem

Terminal hangs with Claude Code typically manifest in three ways. First, you might see a spinner that never completes, the cursor spins indefinitely with no response. Second, output may truncate mid-stream, leaving you with partial results and no way to continue. Third, the entire terminal session becomes unresponsive, accepting no keyboard input.

Before applying fixes, identify which scenario matches your situation. Different symptoms require different solutions.

Quick Recovery Commands

The fastest way to recover from a frozen Claude Code session depends on your terminal and operating system.

For most users, pressing Ctrl+C once sends an interrupt signal. This tells Claude Code to stop the current operation and return control to your shell. In many cases, you will see an "Interrupted" message and can continue your session.

If Ctrl+C fails, try Ctrl+Z to background the process:

^Z
[1]+ Stopped
claude

Then kill the background process:

kill %1

For macOS users with iTerm2, you can send a SIGKILL directly through the terminal menu: press Cmd+. to send an interrupt, or use Cmd+Shift+K to close the pane.

On Linux, find the process ID and use kill -9:

ps aux | grep claude
kill -9 <PID>

Diagnosing Root Causes

If hangs recur frequently, diagnose the underlying cause. Common culprits include network connectivity issues, configuration problems, and resource constraints.

Network Issues

Claude Code communicates with Anthropic's API servers. Network problems manifest as hangs during the "Thinking..." phase. Test your connection:

curl -s https://api.anthropic.com/health | head

If this fails, check your firewall settings, VPN connection, or proxy configuration. Corporate networks often block API endpoints.

Resource Constraints

Low memory or CPU throttling can cause Claude Code to appear frozen. Monitor system resources:

# macOS
top -l 1 | head -20

# Linux
free -h && uptime

If memory is exhausted, close other applications or restart your terminal entirely.

Preventing Future Hangs

Prevention strategies reduce the frequency of frozen sessions.

Use Explicit Context Boundaries

When working with large codebases or long conversations, explicitly set context boundaries. Instead of letting a session run indefinitely, break work into smaller chunks:

/clear

This clears conversation history and starts fresh, reducing memory usage and the chance of hangs.

Configure Timeouts

Add timeout configurations to your ~/.claude/settings.json:

{
  "timeout": 30,
  "maxRetries": 2
}

Optimize Prompt Complexity

Complex prompts with multiple instructions can trigger hangs. Break complex requests into sequential steps. Instead of:

Create a full-stack application with authentication, database models, and API endpoints

Use:

First, create the database models for user authentication

Then follow up with subsequent requests for each component.

Recovery Workflow

When you encounter a hang, follow this systematic recovery workflow:

1. Wait 30 seconds: Sometimes Claude Code is processing a complex request. A 30-second wait eliminates false positives.
2. Press Ctrl+C once: A single interrupt signal often resolves the issue.
3. Check process status: If the terminal remains frozen, open a new terminal window and check for running Claude processes.
4. Kill stubborn processes: Use process termination as a last resort before restarting your terminal entirely.
5. Restart Claude Code: After recovery, verify functionality with a simple query like "Hello, respond with OK."

Advanced Techniques

Container Environments

When running Claude Code inside Docker containers, ensure proper signal handling. Add an ENTRYPOINT that properly forwards signals:

ENTRYPOINT ["sh", "-c"]
CMD ["exec claude"]

tmux and Screen Sessions

If you use tmux or screen, configure proper pane management. Add to your .tmux.conf:

bind-key C-c send-keys C-c
bind-key C-z send-keys C-z

This ensures interrupt signals reach Claude Code even when running in detached sessions.

Log Analysis

Enable debug logging to diagnose recurring issues. Set the CLAUDE_DEBUG environment variable:

export CLAUDE_DEBUG=1
claude

Debug logs reveal where Claude Code stalls, helping identify whether the issue is network-related or a code execution problem.

When to Reinstall

If issues persist despite troubleshooting, a clean reinstallation often resolves underlying corruption:

# Uninstall Claude Code
brew uninstall claude

# Clear configuration
rm -rf ~/.claude

# Fresh installation
brew install claude

Reinstallation takes minutes and eliminates configuration conflicts that troubleshooting cannot fix.

Conclusion

Terminal hangs with Claude Code frustrate developers, but most hangs resolve with simple interrupt signals. Persistent issues often stem from network connectivity, configuration, or system resource constraints. By understanding the symptoms, applying quick recovery commands, and implementing prevention strategies, you minimize downtime and maintain productivity.