everything-claude-code/TROUBLESHOOTING.md

Troubleshooting Guide

Common issues and solutions for Everything Claude Code (ECC) plugin.

Table of Contents

• Memory & Context Issues
• Agent Harness Failures
• Hook & Workflow Errors
• Installation & Setup
• Performance Issues

---

Memory & Context Issues

Context Window Overflow

Symptom: "Context too long" errors or incomplete responses

Causes:

• Large file uploads exceeding token limits
• Accumulated conversation history
• Multiple large tool outputs in single session

Solutions:

# 1. Clear conversation history and start fresh
# Use Claude Code: "New Chat" or Cmd/Ctrl+Shift+N

# 2. Reduce file size before analysis
head -n 100 large-file.log > sample.log

# 3. Use streaming for large outputs
cat large-file.txt | head -50

# 4. Split tasks into smaller chunks
# Instead of: "Analyze all 50 files"
# Use: "Analyze files in src/components/ directory"

Memory Persistence Failures

Symptom: Agent doesn't remember previous context or observations

Causes:

• Disabled continuous-learning hooks
• Corrupted observation files
• Project detection failures

Solutions:

# Check if observations are being recorded
ls ~/.claude/homunculus/*/observations.jsonl

# View recent observations
tail -20 ~/.claude/homunculus/$(basename $PWD)/observations.jsonl

# Reset observations if corrupted
rm ~/.claude/homunculus/$(basename $PWD)/observations.jsonl

# Verify hooks are enabled
grep -r "observe" ~/.claude/settings.json

---

Agent Harness Failures

Agent Not Found

Symptom: "Agent not loaded" or "Unknown agent" errors

Causes:

• Plugin not installed correctly
• Agent path misconfiguration
• Marketplace vs manual install mismatch

Solutions:

# Check plugin installation
ls ~/.claude/plugins/cache/

# Verify agent exists (marketplace install)
ls ~/.claude/plugins/cache/*/agents/

# For manual install, agents should be in:
ls ~/.claude/agents/  # Custom agents only

# Reload plugin
# Claude Code → Settings → Extensions → Reload

Workflow Execution Hangs

Symptom: Agent starts but never completes

Causes:

• Infinite loops in agent logic
• Blocked on user input
• Network timeout waiting for API

Solutions:

# 1. Check for stuck processes
ps aux | grep claude

# 2. Enable debug mode
export CLAUDE_DEBUG=1

# 3. Set shorter timeouts
export CLAUDE_TIMEOUT=30

# 4. Check network connectivity
curl -I https://api.anthropic.com

Tool Use Errors

Symptom: "Tool execution failed" or permission denied

Causes:

• Missing dependencies (npm, python, etc.)
• Insufficient file permissions
• Path not found

Solutions:

# Verify required tools are installed
which node python3 npm git

# Fix permissions on hook scripts
chmod +x ~/.claude/plugins/cache/*/hooks/*.sh
chmod +x ~/.claude/plugins/cache/*/skills/*/hooks/*.sh

# Check PATH includes necessary binaries
echo $PATH

---

Hook & Workflow Errors

Hooks Not Firing

Symptom: Pre/post hooks don't execute

Causes:

• Hooks not registered in settings.json
• Invalid hook syntax
• Hook script not executable

Solutions:

# Check hooks are registered
cat ~/.claude/settings.json | grep -A 10 '"hooks"'

# Verify hook files exist and are executable
ls -la ~/.claude/plugins/cache/*/hooks/

# Test hook manually
bash ~/.claude/plugins/cache/*/hooks/pre-bash.sh <<< '{"command":"echo test"}'

# Re-register hooks (if using plugin)
# Disable and re-enable plugin in Claude Code settings

Python/Node Version Mismatches

Symptom: "python3 not found" or "node: command not found"

Causes:

• Missing Python/Node installation
• PATH not configured
• Wrong Python version (Windows)

Solutions:

# Install Python 3 (if missing)
# macOS: brew install python3
# Ubuntu: sudo apt install python3
# Windows: Download from python.org

# Install Node.js (if missing)
# macOS: brew install node
# Ubuntu: sudo apt install nodejs npm
# Windows: Download from nodejs.org

# Verify installations
python3 --version
node --version
npm --version

# Windows: Ensure python (not python3) works
python --version

Dev Server Blocker False Positives

Symptom: Hook blocks legitimate commands mentioning "dev"

Causes:

• Heredoc content triggering pattern match
• Non-dev commands with "dev" in arguments

Solutions:

# This is fixed in v1.8.0+ (PR #371)
# Upgrade plugin to latest version

# Workaround: Wrap dev servers in tmux
tmux new-session -d -s dev "npm run dev"
tmux attach -t dev

# Disable hook temporarily if needed
# Edit ~/.claude/settings.json and remove pre-bash hook

---

Installation & Setup

Plugin Not Loading

Symptom: Plugin features unavailable after install

Causes:

• Marketplace cache not updated
• Claude Code version incompatibility
• Corrupted plugin files

Solutions:

# Clear plugin cache
rm -rf ~/.claude/plugins/cache/*

# Reinstall from marketplace
# Claude Code → Extensions → Everything Claude Code → Uninstall
# Then reinstall from marketplace

# Check Claude Code version
claude --version
# Requires Claude Code 2.0+

# Manual install (if marketplace fails)
git clone https://github.com/affaan-m/everything-claude-code.git
cp -r everything-claude-code ~/.claude/plugins/ecc

Package Manager Detection Fails

Symptom: Wrong package manager used (npm instead of pnpm)

Causes:

• No lock file present
• CLAUDE_PACKAGE_MANAGER not set
• Multiple lock files confusing detection

Solutions:

# Set preferred package manager globally
export CLAUDE_PACKAGE_MANAGER=pnpm
# Add to ~/.bashrc or ~/.zshrc

# Or set per-project
echo '{"packageManager": "pnpm"}' > .claude/package-manager.json

# Or use package.json field
npm pkg set packageManager="pnpm@8.15.0"

# Remove conflicting lock files
rm package-lock.json  # If using pnpm/yarn/bun

---

Performance Issues

Slow Response Times

Symptom: Agent takes 30+ seconds to respond

Causes:

• Large observation files
• Too many active hooks
• Network latency to API

Solutions:

# Archive old observations
find ~/.claude/homunculus -name "observations.jsonl" -size +10M -delete

# Disable unused hooks temporarily
# Edit ~/.claude/settings.json

# Use local caching
# Enable Redis for semantic search caching

High CPU Usage

Symptom: Claude Code consuming 100% CPU

Causes:

• Infinite observation loops
• File watching on large directories
• Memory leaks in hooks

Solutions:

# Check for runaway processes
top -o cpu | grep claude

# Disable continuous learning temporarily
touch ~/.claude/homunculus/disabled

# Restart Claude Code
# Cmd/Ctrl+Q then reopen

# Check observation file size
du -sh ~/.claude/homunculus/*/

---

Common Error Messages

"EACCES: permission denied"

# Fix hook permissions
find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;

# Fix observation directory permissions
chmod -R 755 ~/.claude/homunculus

"MODULE_NOT_FOUND"

# Install plugin dependencies
cd ~/.claude/plugins/cache/everything-claude-code
npm install

# Or for manual install
cd ~/.claude/plugins/ecc
npm install

"spawn UNKNOWN"

# Windows-specific: Ensure scripts use correct line endings
# Convert CRLF to LF
find ~/.claude/plugins -name "*.sh" -exec dos2unix {} \;

# Or install dos2unix
# macOS: brew install dos2unix
# Ubuntu: sudo apt install dos2unix

---

Getting Help

If you're still experiencing issues:

1. Check GitHub Issues: github.com/affaan-m/everything-claude-code/issues
2. Enable Debug Logging:

   export CLAUDE_DEBUG=1
   export CLAUDE_LOG_LEVEL=debug
   

3. Collect Diagnostic Info:

   claude --version
   node --version
   python3 --version
   echo $CLAUDE_PACKAGE_MANAGER
   ls -la ~/.claude/plugins/cache/
   

4. Open an Issue: Include debug logs, error messages, and diagnostic info

---

Related Documentation

• README.md - Installation and features
• CONTRIBUTING.md - Development guidelines
• docs/ - Detailed documentation
• examples/ - Usage examples