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
• Common Error Messages
• Getting Help

---

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
head -n 50 large-file.txt

# 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/projects/*/observations.jsonl

# Find the current project's hash id
python3 - <<'PY'
import json, os
registry_path = os.path.expanduser("~/.claude/homunculus/projects.json")
with open(registry_path) as f:
    registry = json.load(f)
for project_id, meta in registry.items():
    if meta.get("root") == os.getcwd():
        print(project_id)
        break
else:
    raise SystemExit("Project hash not found in ~/.claude/homunculus/projects.json")
PY

# View recent observations for that project