|
| 1 | +# Troubleshooting Guide |
| 2 | + |
| 3 | +Common issues and solutions for Everything Claude Code (ECC) plugin. |
| 4 | + |
| 5 | +## Table of Contents |
| 6 | + |
| 7 | +- [Memory & Context Issues](#memory--context-issues) |
| 8 | +- [Agent Harness Failures](#agent-harness-failures) |
| 9 | +- [Hook & Workflow Errors](#hook--workflow-errors) |
| 10 | +- [Installation & Setup](#installation--setup) |
| 11 | +- [Performance Issues](#performance-issues) |
| 12 | + |
| 13 | +--- |
| 14 | + |
| 15 | +## Memory & Context Issues |
| 16 | + |
| 17 | +### Context Window Overflow |
| 18 | + |
| 19 | +**Symptom:** "Context too long" errors or incomplete responses |
| 20 | + |
| 21 | +**Causes:** |
| 22 | +- Large file uploads exceeding token limits |
| 23 | +- Accumulated conversation history |
| 24 | +- Multiple large tool outputs in single session |
| 25 | + |
| 26 | +**Solutions:** |
| 27 | +```bash |
| 28 | +# 1. Clear conversation history and start fresh |
| 29 | +# Use Claude Code: "New Chat" or Cmd/Ctrl+Shift+N |
| 30 | + |
| 31 | +# 2. Reduce file size before analysis |
| 32 | +head -n 100 large-file.log > sample.log |
| 33 | + |
| 34 | +# 3. Use streaming for large outputs |
| 35 | +cat large-file.txt | head -50 |
| 36 | + |
| 37 | +# 4. Split tasks into smaller chunks |
| 38 | +# Instead of: "Analyze all 50 files" |
| 39 | +# Use: "Analyze files in src/components/ directory" |
| 40 | +``` |
| 41 | + |
| 42 | +### Memory Persistence Failures |
| 43 | + |
| 44 | +**Symptom:** Agent doesn't remember previous context or observations |
| 45 | + |
| 46 | +**Causes:** |
| 47 | +- Disabled continuous-learning hooks |
| 48 | +- Corrupted observation files |
| 49 | +- Project detection failures |
| 50 | + |
| 51 | +**Solutions:** |
| 52 | +```bash |
| 53 | +# Check if observations are being recorded |
| 54 | +ls ~/.claude/homunculus/*/observations.jsonl |
| 55 | + |
| 56 | +# View recent observations |
| 57 | +tail -20 ~/.claude/homunculus/$(basename $PWD)/observations.jsonl |
| 58 | + |
| 59 | +# Reset observations if corrupted |
| 60 | +rm ~/.claude/homunculus/$(basename $PWD)/observations.jsonl |
| 61 | + |
| 62 | +# Verify hooks are enabled |
| 63 | +grep -r "observe" ~/.claude/settings.json |
| 64 | +``` |
| 65 | + |
| 66 | +--- |
| 67 | + |
| 68 | +## Agent Harness Failures |
| 69 | + |
| 70 | +### Agent Not Found |
| 71 | + |
| 72 | +**Symptom:** "Agent not loaded" or "Unknown agent" errors |
| 73 | + |
| 74 | +**Causes:** |
| 75 | +- Plugin not installed correctly |
| 76 | +- Agent path misconfiguration |
| 77 | +- Marketplace vs manual install mismatch |
| 78 | + |
| 79 | +**Solutions:** |
| 80 | +```bash |
| 81 | +# Check plugin installation |
| 82 | +ls ~/.claude/plugins/cache/ |
| 83 | + |
| 84 | +# Verify agent exists (marketplace install) |
| 85 | +ls ~/.claude/plugins/cache/*/agents/ |
| 86 | + |
| 87 | +# For manual install, agents should be in: |
| 88 | +ls ~/.claude/agents/ # Custom agents only |
| 89 | + |
| 90 | +# Reload plugin |
| 91 | +# Claude Code → Settings → Extensions → Reload |
| 92 | +``` |
| 93 | + |
| 94 | +### Workflow Execution Hangs |
| 95 | + |
| 96 | +**Symptom:** Agent starts but never completes |
| 97 | + |
| 98 | +**Causes:** |
| 99 | +- Infinite loops in agent logic |
| 100 | +- Blocked on user input |
| 101 | +- Network timeout waiting for API |
| 102 | + |
| 103 | +**Solutions:** |
| 104 | +```bash |
| 105 | +# 1. Check for stuck processes |
| 106 | +ps aux | grep claude |
| 107 | + |
| 108 | +# 2. Enable debug mode |
| 109 | +export CLAUDE_DEBUG=1 |
| 110 | + |
| 111 | +# 3. Set shorter timeouts |
| 112 | +export CLAUDE_TIMEOUT=30 |
| 113 | + |
| 114 | +# 4. Check network connectivity |
| 115 | +curl -I https://api.anthropic.com |
| 116 | +``` |
| 117 | + |
| 118 | +### Tool Use Errors |
| 119 | + |
| 120 | +**Symptom:** "Tool execution failed" or permission denied |
| 121 | + |
| 122 | +**Causes:** |
| 123 | +- Missing dependencies (npm, python, etc.) |
| 124 | +- Insufficient file permissions |
| 125 | +- Path not found |
| 126 | + |
| 127 | +**Solutions:** |
| 128 | +```bash |
| 129 | +# Verify required tools are installed |
| 130 | +which node python3 npm git |
| 131 | + |
| 132 | +# Fix permissions on hook scripts |
| 133 | +chmod +x ~/.claude/plugins/cache/*/hooks/*.sh |
| 134 | +chmod +x ~/.claude/plugins/cache/*/skills/*/hooks/*.sh |
| 135 | + |
| 136 | +# Check PATH includes necessary binaries |
| 137 | +echo $PATH |
| 138 | +``` |
| 139 | + |
| 140 | +--- |
| 141 | + |
| 142 | +## Hook & Workflow Errors |
| 143 | + |
| 144 | +### Hooks Not Firing |
| 145 | + |
| 146 | +**Symptom:** Pre/post hooks don't execute |
| 147 | + |
| 148 | +**Causes:** |
| 149 | +- Hooks not registered in settings.json |
| 150 | +- Invalid hook syntax |
| 151 | +- Hook script not executable |
| 152 | + |
| 153 | +**Solutions:** |
| 154 | +```bash |
| 155 | +# Check hooks are registered |
| 156 | +cat ~/.claude/settings.json | grep -A 10 '"hooks"' |
| 157 | + |
| 158 | +# Verify hook files exist and are executable |
| 159 | +ls -la ~/.claude/plugins/cache/*/hooks/ |
| 160 | + |
| 161 | +# Test hook manually |
| 162 | +bash ~/.claude/plugins/cache/*/hooks/pre-bash.sh <<< '{"command":"echo test"}' |
| 163 | + |
| 164 | +# Re-register hooks (if using plugin) |
| 165 | +# Disable and re-enable plugin in Claude Code settings |
| 166 | +``` |
| 167 | + |
| 168 | +### Python/Node Version Mismatches |
| 169 | + |
| 170 | +**Symptom:** "python3 not found" or "node: command not found" |
| 171 | + |
| 172 | +**Causes:** |
| 173 | +- Missing Python/Node installation |
| 174 | +- PATH not configured |
| 175 | +- Wrong Python version (Windows) |
| 176 | + |
| 177 | +**Solutions:** |
| 178 | +```bash |
| 179 | +# Install Python 3 (if missing) |
| 180 | +# macOS: brew install python3 |
| 181 | +# Ubuntu: sudo apt install python3 |
| 182 | +# Windows: Download from python.org |
| 183 | + |
| 184 | +# Install Node.js (if missing) |
| 185 | +# macOS: brew install node |
| 186 | +# Ubuntu: sudo apt install nodejs npm |
| 187 | +# Windows: Download from nodejs.org |
| 188 | + |
| 189 | +# Verify installations |
| 190 | +python3 --version |
| 191 | +node --version |
| 192 | +npm --version |
| 193 | + |
| 194 | +# Windows: Ensure python (not python3) works |
| 195 | +python --version |
| 196 | +``` |
| 197 | + |
| 198 | +### Dev Server Blocker False Positives |
| 199 | + |
| 200 | +**Symptom:** Hook blocks legitimate commands mentioning "dev" |
| 201 | + |
| 202 | +**Causes:** |
| 203 | +- Heredoc content triggering pattern match |
| 204 | +- Non-dev commands with "dev" in arguments |
| 205 | + |
| 206 | +**Solutions:** |
| 207 | +```bash |
| 208 | +# This is fixed in v1.8.0+ (PR #371) |
| 209 | +# Upgrade plugin to latest version |
| 210 | + |
| 211 | +# Workaround: Wrap dev servers in tmux |
| 212 | +tmux new-session -d -s dev "npm run dev" |
| 213 | +tmux attach -t dev |
| 214 | + |
| 215 | +# Disable hook temporarily if needed |
| 216 | +# Edit ~/.claude/settings.json and remove pre-bash hook |
| 217 | +``` |
| 218 | + |
| 219 | +--- |
| 220 | + |
| 221 | +## Installation & Setup |
| 222 | + |
| 223 | +### Plugin Not Loading |
| 224 | + |
| 225 | +**Symptom:** Plugin features unavailable after install |
| 226 | + |
| 227 | +**Causes:** |
| 228 | +- Marketplace cache not updated |
| 229 | +- Claude Code version incompatibility |
| 230 | +- Corrupted plugin files |
| 231 | + |
| 232 | +**Solutions:** |
| 233 | +```bash |
| 234 | +# Clear plugin cache |
| 235 | +rm -rf ~/.claude/plugins/cache/* |
| 236 | + |
| 237 | +# Reinstall from marketplace |
| 238 | +# Claude Code → Extensions → Everything Claude Code → Uninstall |
| 239 | +# Then reinstall from marketplace |
| 240 | + |
| 241 | +# Check Claude Code version |
| 242 | +claude --version |
| 243 | +# Requires Claude Code 2.0+ |
| 244 | + |
| 245 | +# Manual install (if marketplace fails) |
| 246 | +git clone https://github.com/affaan-m/everything-claude-code.git |
| 247 | +cp -r everything-claude-code ~/.claude/plugins/ecc |
| 248 | +``` |
| 249 | + |
| 250 | +### Package Manager Detection Fails |
| 251 | + |
| 252 | +**Symptom:** Wrong package manager used (npm instead of pnpm) |
| 253 | + |
| 254 | +**Causes:** |
| 255 | +- No lock file present |
| 256 | +- CLAUDE_PACKAGE_MANAGER not set |
| 257 | +- Multiple lock files confusing detection |
| 258 | + |
| 259 | +**Solutions:** |
| 260 | +```bash |
| 261 | +# Set preferred package manager globally |
| 262 | +export CLAUDE_PACKAGE_MANAGER=pnpm |
| 263 | +# Add to ~/.bashrc or ~/.zshrc |
| 264 | + |
| 265 | +# Or set per-project |
| 266 | +echo '{"packageManager": "pnpm"}' > .claude/package-manager.json |
| 267 | + |
| 268 | +# Or use package.json field |
| 269 | +npm pkg set packageManager= "[email protected]" |
| 270 | + |
| 271 | +# Remove conflicting lock files |
| 272 | +rm package-lock.json # If using pnpm/yarn/bun |
| 273 | +``` |
| 274 | + |
| 275 | +--- |
| 276 | + |
| 277 | +## Performance Issues |
| 278 | + |
| 279 | +### Slow Response Times |
| 280 | + |
| 281 | +**Symptom:** Agent takes 30+ seconds to respond |
| 282 | + |
| 283 | +**Causes:** |
| 284 | +- Large observation files |
| 285 | +- Too many active hooks |
| 286 | +- Network latency to API |
| 287 | + |
| 288 | +**Solutions:** |
| 289 | +```bash |
| 290 | +# Archive old observations |
| 291 | +find ~/.claude/homunculus -name "observations.jsonl" -size +10M -delete |
| 292 | + |
| 293 | +# Disable unused hooks temporarily |
| 294 | +# Edit ~/.claude/settings.json |
| 295 | + |
| 296 | +# Use local caching |
| 297 | +# Enable Redis for semantic search caching |
| 298 | +``` |
| 299 | + |
| 300 | +### High CPU Usage |
| 301 | + |
| 302 | +**Symptom:** Claude Code consuming 100% CPU |
| 303 | + |
| 304 | +**Causes:** |
| 305 | +- Infinite observation loops |
| 306 | +- File watching on large directories |
| 307 | +- Memory leaks in hooks |
| 308 | + |
| 309 | +**Solutions:** |
| 310 | +```bash |
| 311 | +# Check for runaway processes |
| 312 | +top -o cpu | grep claude |
| 313 | + |
| 314 | +# Disable continuous learning temporarily |
| 315 | +touch ~/.claude/homunculus/disabled |
| 316 | + |
| 317 | +# Restart Claude Code |
| 318 | +# Cmd/Ctrl+Q then reopen |
| 319 | + |
| 320 | +# Check observation file size |
| 321 | +du -sh ~/.claude/homunculus/*/ |
| 322 | +``` |
| 323 | + |
| 324 | +--- |
| 325 | + |
| 326 | +## Common Error Messages |
| 327 | + |
| 328 | +### "EACCES: permission denied" |
| 329 | + |
| 330 | +```bash |
| 331 | +# Fix hook permissions |
| 332 | +find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \; |
| 333 | + |
| 334 | +# Fix observation directory permissions |
| 335 | +chmod -R 755 ~/.claude/homunculus |
| 336 | +``` |
| 337 | + |
| 338 | +### "MODULE_NOT_FOUND" |
| 339 | + |
| 340 | +```bash |
| 341 | +# Install plugin dependencies |
| 342 | +cd ~/.claude/plugins/cache/everything-claude-code |
| 343 | +npm install |
| 344 | + |
| 345 | +# Or for manual install |
| 346 | +cd ~/.claude/plugins/ecc |
| 347 | +npm install |
| 348 | +``` |
| 349 | + |
| 350 | +### "spawn UNKNOWN" |
| 351 | + |
| 352 | +```bash |
| 353 | +# Windows-specific: Ensure scripts use correct line endings |
| 354 | +# Convert CRLF to LF |
| 355 | +find ~/.claude/plugins -name "*.sh" -exec dos2unix {} \; |
| 356 | + |
| 357 | +# Or install dos2unix |
| 358 | +# macOS: brew install dos2unix |
| 359 | +# Ubuntu: sudo apt install dos2unix |
| 360 | +``` |
| 361 | + |
| 362 | +--- |
| 363 | + |
| 364 | +## Getting Help |
| 365 | + |
| 366 | + If you're still experiencing issues: |
| 367 | + |
| 368 | +1. **Check GitHub Issues**: [github.com/affaan-m/everything-claude-code/issues](https://github.com/affaan-m/everything-claude-code/issues) |
| 369 | +2. **Enable Debug Logging**: |
| 370 | + ```bash |
| 371 | + export CLAUDE_DEBUG=1 |
| 372 | + export CLAUDE_LOG_LEVEL=debug |
| 373 | + ``` |
| 374 | +3. **Collect Diagnostic Info**: |
| 375 | + ```bash |
| 376 | + claude --version |
| 377 | + node --version |
| 378 | + python3 --version |
| 379 | + echo $CLAUDE_PACKAGE_MANAGER |
| 380 | + ls -la ~/.claude/plugins/cache/ |
| 381 | + ``` |
| 382 | +4. **Open an Issue**: Include debug logs, error messages, and diagnostic info |
| 383 | + |
| 384 | +--- |
| 385 | + |
| 386 | +## Related Documentation |
| 387 | + |
| 388 | +- [README.md](./README.md) - Installation and features |
| 389 | +- [CONTRIBUTING.md](./CONTRIBUTING.md) - Development guidelines |
| 390 | +- [docs/](./docs/) - Detailed documentation |
| 391 | +- [examples/](./examples/) - Usage examples |
0 commit comments