Skip to content

Commit b7bafb4

Browse files
pangerlkraffaan-m
authored andcommitted
docs: add comprehensive troubleshooting guide (fixes anomalyco#326)
Added a comprehensive troubleshooting guide for the Everything Claude Code (ECC) plugin, covering common issues, symptoms, causes, and solutions.
1 parent 4de7763 commit b7bafb4

1 file changed

Lines changed: 391 additions & 0 deletions

File tree

‎TROUBLESHOOTING.md‎

Lines changed: 391 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,391 @@
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

Comments
 (0)