mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-03-30 13:43:26 +08:00
docs: add comprehensive troubleshooting guide (fixes #326)
Added a comprehensive troubleshooting guide for the Everything Claude Code (ECC) plugin, covering common issues, symptoms, causes, and solutions.
This commit is contained in:
Pangerkumzuk Longkumer
committed by
Affaan Mustafa
Affaan Mustafa
parent
4de776341e
commit
b7bafb40cb
391
TROUBLESHOOTING.md
Normal file
391
TROUBLESHOOTING.md
Normal file
@@ -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="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:**
|
||||||
|
```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
|
||||||
Reference in New Issue
Block a user