The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs: add comprehensive troubleshooting guide (fixes #326)
Pangerkumzuk Longkumerb7bafb40cbfd
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.mdnew file mode 100644index 000000000..d80e00c67--- /dev/null+++ b/TROUBLESHOOTING.md@@ -0,0 +1,391 @@+# Troubleshooting Guide++Common issues and solutions for Everything Claude Code (ECC) plugin.++## Table of Contents++- [Memory & Context Issues](#memory--context-issues)+- [Agent Harness Failures](#agent-harness-failures)+- [Hook & Workflow Errors](#hook--workflow-errors)+- [Installation & Setup](#installation--setup)+- [Performance Issues](#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:**+```bash+# 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:**+```bash+# 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:**+```bash+# 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:**+```bash+# 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:**+```bash+# 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:**+```bash+# 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:**+```bash+# 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:**+```bash+# 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:**+```bash+# 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:**+```bash+# 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="[email protected]"++# 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:**+```bash+# 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:**+```bash+# 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"++```bash+# Fix hook permissions+find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;++# Fix observation directory permissions+chmod -R 755 ~/.claude/homunculus+```++### "MODULE_NOT_FOUND"++```bash+# Install plugin dependencies+cd ~/.claude/plugins/cache/everything-claude-code+npm install++# Or for manual install+cd ~/.claude/plugins/ecc+npm install+```++### "spawn UNKNOWN"++```bash+# 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](https://github.com/affaan-m/everything-claude-code/issues)+2. **Enable Debug Logging**:+ ```bash+ export CLAUDE_DEBUG=1+ export CLAUDE_LOG_LEVEL=debug+ ```+3. **Collect Diagnostic Info**:+ ```bash+ 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](./README.md) - Installation and features+- [CONTRIBUTING.md](./CONTRIBUTING.md) - Development guidelines+- [docs/](./docs/) - Detailed documentation+- [examples/](./examples/) - Usage examples