The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs: tighten troubleshooting safety guidance
Affaan Mustafa5644415767ee
diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.mdindex d80e00c67..57ffa2e4d 100644--- a/TROUBLESHOOTING.md+++ b/TROUBLESHOOTING.md@@ -9,6 +9,8 @@ Common issues and solutions for Everything Claude Code (ECC) plugin.- [Hook & Workflow Errors](#hook--workflow-errors)- [Installation & Setup](#installation--setup)- [Performance Issues](#performance-issues)+- [Common Error Messages](#common-error-messages)+- [Getting Help](#getting-help)---@@ -32,7 +34,7 @@ Common issues and solutions for Everything Claude Code (ECC) plugin.head -n 100 large-file.log > sample.log# 3. Use streaming for large outputs-cat large-file.txt | head -50+head -n 50 large-file.txt# 4. Split tasks into smaller chunks# Instead of: "Analyze all 50 files"@@ -51,13 +53,28 @@ cat large-file.txt | head -50**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+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+tail -20 ~/.claude/homunculus/projects/<project-hash>/observations.jsonl++# Back up a corrupted observations file before recreating it+mv ~/.claude/homunculus/projects/<project-hash>/observations.jsonl \+ ~/.claude/homunculus/projects/<project-hash>/observations.jsonl.bak.$(date +%Y%m%d-%H%M%S)# Verify hooks are enabledgrep -r "observe" ~/.claude/settings.json@@ -153,7 +170,7 @@ echo $PATH**Solutions:**```bash# Check hooks are registered-cat ~/.claude/settings.json | grep -A 10 '"hooks"'+grep -A 10 '"hooks"' ~/.claude/settings.json# Verify hook files exist and are executablels -la ~/.claude/plugins/cache/*/hooks/@@ -231,8 +248,12 @@ tmux attach -t dev**Solutions:**```bash-# Clear plugin cache-rm -rf ~/.claude/plugins/cache/*+# Inspect the plugin cache before changing it+ls -la ~/.claude/plugins/cache/++# Back up the plugin cache instead of deleting it in place+mv ~/.claude/plugins/cache ~/.claude/plugins/cache.backup.$(date +%Y%m%d-%H%M%S)+mkdir -p ~/.claude/plugins/cache# Reinstall from marketplace# Claude Code → Extensions → Everything Claude Code → Uninstall@@ -268,7 +289,9 @@ echo '{"packageManager": "pnpm"}' > .claude/package-manager.json# Or use package.json fieldnpm pkg set packageManager="[email protected]"-# Remove conflicting lock files+# Warning: removing lock files can change installed dependency versions.+# Commit or back up the lock file first, then run a fresh install and re-run CI.+# Only do this when intentionally switching package managers.rm package-lock.json # If using pnpm/yarn/bun```@@ -287,14 +310,22 @@ rm package-lock.json # If using pnpm/yarn/bun**Solutions:**```bash-# Archive old observations-find ~/.claude/homunculus -name "observations.jsonl" -size +10M -delete+# Archive large observations instead of deleting them+archive_dir="$HOME/.claude/homunculus/archive/$(date +%Y%m%d)"+mkdir -p "$archive_dir"+find ~/.claude/homunculus/projects -name "observations.jsonl" -size +10M -exec sh -c '+ for file do+ base=$(basename "$(dirname "$file")")+ gzip -c "$file" > "'"$archive_dir"'/${base}-observations.jsonl.gz"+ : > "$file"+ done+' sh {} +# Disable unused hooks temporarily# Edit ~/.claude/settings.json-# Use local caching-# Enable Redis for semantic search caching+# Keep active observation files small+# Large archives should live under ~/.claude/homunculus/archive/```### High CPU Usage@@ -332,7 +363,7 @@ du -sh ~/.claude/homunculus/*/find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;# Fix observation directory permissions-chmod -R 755 ~/.claude/homunculus+chmod -R u+rwX,go+rX ~/.claude/homunculus```### "MODULE_NOT_FOUND"