Claude Code Not Responding: Terminal Hangs Fix

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’re running a simple query or using advanced skills like the tdd skill for test-driven development.

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’ll see a “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, the equivalent is Alt+. or finding the process ID and using 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, skill 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.

Skill Configuration Problems

Skills like pdf, xlsx, or frontend-design load additional instructions that can occasionally cause conflicts. Check your skill files for syntax errors:

ls -la ~/.claude/skills/

Review recent modifications to your skill files. A malformed skill can cause Claude to enter an infinite reasoning loop.

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 Skill Timeouts

If you use skills that perform file operations—such as the tdd skill for test-driven development or the xlsx skill for spreadsheet manipulation—add timeout configurations to your ~/.claude/settings.json:

{
  "skills": {
    "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

For power users running Claude Code in specialized environments, additional techniques apply.

Container Environments

When running Claude Code inside Docker containers, ensure proper signal handling. Add a 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, skill-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, especially when using powerful skills like tdd for test-driven development or pdf for document processing. Most hangs resolve with simple interrupt signals, while persistent issues often stem from network connectivity, skill configuration, or system resource constraints.

By understanding the symptoms, applying quick recovery commands, and implementing prevention strategies, you minimize downtime and maintain productivity. For most users, Ctrl+C followed by a simple query test handles the situation. For recurring problems, the diagnostic and prevention techniques in this guide provide lasting solutions.

Related Reading

• Claude Code Error Connection Timeout During Task Fix — Related: timeout vs hang distinction
• Claude Code Slow Response How to Fix Latency Issues — Performance issues that precede hangs
• Claude Code Stuck in Infinite Loop How to Interrupt — Another “Claude is stuck” scenario
• Claude Skills Troubleshooting Hub — All Claude Code hang and responsiveness fixes

Built by theluckystrike — More at zovo.one