docs: add comprehensive troubleshooting guide (fixes #326)#373
docs: add comprehensive troubleshooting guide (fixes #326)#373affaan-m merged 2 commits intoaffaan-m:mainfrom
Conversation
Added a comprehensive troubleshooting guide for the Everything Claude Code (ECC) plugin, covering common issues, symptoms, causes, and solutions.
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughAdds a new TROUBLESHOOTING.md documentation file for the Everything Claude Code (ECC) plugin containing structured troubleshooting guidance for memory & context, agent harnesses, hooks/workflows, installation, performance, common errors, and getting help (symptoms, causes, and remediation steps). Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 3 | ❌ 2❌ Failed checks (2 warnings)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 issues found across 1 file
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="TROUBLESHOOTING.md">
<violation number="1" location="TROUBLESHOOTING.md:291">
P1: Comment says "Archive old observations" but the command permanently deletes them with `-delete`. This is misleading and risks unintended data loss. Either rename the comment to reflect deletion, or change the command to actually archive (e.g., move/compress the files).</violation>
<violation number="2" location="TROUBLESHOOTING.md:335">
P2: `chmod -R 755` makes all data files (e.g., `.jsonl`) executable, which is a security anti-pattern. Use `chmod -R u+rwX,go+rX` instead — the uppercase `X` only sets execute on directories, not regular files.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (3)
TROUBLESHOOTING.md (3)
156-156: Simplify pipeline (useless use of cat).The command can be simplified:
-cat ~/.claude/settings.json | grep -A 10 '"hooks"' +grep -A 10 '"hooks"' ~/.claude/settings.json🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@TROUBLESHOOTING.md` at line 156, Replace the useless use of cat in the pipeline by running grep directly on the file; change the command `cat ~/.claude/settings.json | grep -A 10 '"hooks"'` to `grep -A 10 '"hooks"' ~/.claude/settings.json` so grep reads the file directly and avoids the unnecessary cat process.
271-272: Consider adding a warning about lock file deletion.Deleting the lock file can lead to different dependency versions being installed. While this is intentional when switching package managers, a brief warning would be helpful.
📝 Suggested addition
# Remove conflicting lock files +# Warning: This may cause different versions to be installed rm package-lock.json # If using pnpm/yarn/bun🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@TROUBLESHOOTING.md` around lines 271 - 272, Update the "Remove conflicting lock files" section to include a brief warning that deleting lockfiles (the existing "rm package-lock.json" instruction) can change installed dependency versions; advise making a backup or committing the lockfile before removal, mention this is typically only needed when switching package managers (pnpm/yarn/bun), and suggest running a fresh install and checking CI/local builds after removal to ensure reproducible results.
35-35: Simplify pipeline (useless use of cat).The command can be simplified by removing the unnecessary
cat:-cat large-file.txt | head -50 +head -50 large-file.txt🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@TROUBLESHOOTING.md` at line 35, Replace the unnecessary pipeline "cat large-file.txt | head -50" with a direct head invocation to simplify the command; change the usage to call head directly (e.g., head -n 50 large-file.txt) so you avoid the useless use of cat.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@TROUBLESHOOTING.md`:
- Around line 296-297: Update the "Use local caching" section that contains the
line "Enable Redis for semantic search caching" to either (A) expand it with
concise, actionable setup steps: list installation commands for common OSes or
Docker, required Redis configuration (host/port/auth), how to set the related
environment variables used by the app (e.g., REDIS_URL or
REDIS_HOST/REDIS_PORT), and an example config snippet and verification command
(redis-cli PING), or (B) remove the Redis mention entirely if Redis support is
not implemented; ensure you update any cross-references in the doc. Target the
heading text "Use local caching" and the specific line "Enable Redis for
semantic search caching" when making the change.
- Around line 234-235: Add a clear warning and backup recommendation above the
destructive command "rm -rf ~/.claude/plugins/cache/*" in TROUBLESHOOTING.md:
state that this will permanently delete plugin cache and advise users to create
a backup (suggest commands such as copying or archiving the
~/.claude/plugins/cache directory) or to inspect contents first, and present an
alternative non-destructive step (e.g., moving the cache to a backup location)
so users can recover if needed.
- Around line 5-12: Add the two missing TOC entries for the sections titled
"Common Error Messages" and "Getting Help" by inserting bullet links "- [Common
Error Messages](`#common-error-messages`)" and "- [Getting Help](`#getting-help`)"
into the existing Table of Contents (the list under "## Table of Contents") so
the TOC includes those two sections (titles "Common Error Messages" and "Getting
Help") that appear later in the document.
- Around line 290-291: The current command 'find ~/.claude/homunculus -name
"observations.jsonl" -size +10M -delete' is destructive; replace it with an
archival workflow that moves matching files to a dated/archive directory and
optionally compresses them instead of deleting; implement a find+mkdir+mv (or
rsync) pattern that creates ~/.claude/homunculus/archive/<YYYYMMDD>/, moves each
observations.jsonl there (preserving path or renaming with a timestamp), and
then gzip or tar the archived files to reclaim space while keeping a backup for
recovery and auditing.
- Around line 57-60: Update the two commands in TROUBLESHOOTING.md that build
observation file paths using $(basename $PWD) — they should reference ECC
project hash IDs stored in ~/.claude/homunculus/projects.json; replace the
incorrect paths in the lines containing "tail -20
~/.claude/homunculus/$(basename $PWD)/observations.jsonl" and "rm
~/.claude/homunculus/$(basename $PWD)/observations.jsonl" with either the
wildcard form "…/homunculus/*/observations.jsonl" or instruct to first look up
the 12-character project hash in ~/.claude/homunculus/projects.json and then
construct the path as
"~/.claude/homunculus/projects/<project-hash>/observations.jsonl".
---
Nitpick comments:
In `@TROUBLESHOOTING.md`:
- Line 156: Replace the useless use of cat in the pipeline by running grep
directly on the file; change the command `cat ~/.claude/settings.json | grep -A
10 '"hooks"'` to `grep -A 10 '"hooks"' ~/.claude/settings.json` so grep reads
the file directly and avoids the unnecessary cat process.
- Around line 271-272: Update the "Remove conflicting lock files" section to
include a brief warning that deleting lockfiles (the existing "rm
package-lock.json" instruction) can change installed dependency versions; advise
making a backup or committing the lockfile before removal, mention this is
typically only needed when switching package managers (pnpm/yarn/bun), and
suggest running a fresh install and checking CI/local builds after removal to
ensure reproducible results.
- Line 35: Replace the unnecessary pipeline "cat large-file.txt | head -50" with
a direct head invocation to simplify the command; change the usage to call head
directly (e.g., head -n 50 large-file.txt) so you avoid the useless use of cat.
There was a problem hiding this comment.
Pull request overview
Adds a new troubleshooting reference for the Everything Claude Code (ECC) plugin to help users diagnose common installation, hook/workflow, memory/context, and performance issues.
Changes:
- Introduces
TROUBLESHOOTING.mdwith symptom/cause/solution sections for frequent ECC failure modes. - Adds command-line diagnostic steps for hooks, plugin installation, and observation storage.
- Documents common error messages and escalation steps (“Getting Help”).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # Manual install (if marketplace fails) | ||
| git clone https://github.com/affaan-m/everything-claude-code.git | ||
| cp -r everything-claude-code ~/.claude/plugins/ecc | ||
| ``` |
There was a problem hiding this comment.
The “Manual install” steps here don’t match the manual installation instructions in README.md (which copy agents/commands/skills/rules into ~/.claude/{agents,commands,skills,rules} rather than copying the repo into ~/.claude/plugins/ecc). Please align this section with the documented manual install flow so users don’t end up with an unsupported directory layout.
TROUBLESHOOTING.md
Outdated
| # Archive old observations | ||
| find ~/.claude/homunculus -name "observations.jsonl" -size +10M -delete | ||
|
|
There was a problem hiding this comment.
This claims to “Archive old observations” but the command permanently deletes any observations.jsonl over 10MB. That’s a destructive operation and can wipe both global and project-scoped histories. Prefer a safer rotation/backup approach (e.g., move to a timestamped file) and explicitly call out the data-loss risk if deletion is intended.
| # Check for runaway processes | ||
| top -o cpu | grep claude |
There was a problem hiding this comment.
top -o cpu | grep claude generally won’t work as written because top is interactive and doesn’t reliably emit grep-able output on many platforms. Use a non-interactive command for this check (e.g., ps filtered by process name, or platform-specific non-interactive top flags) so the troubleshooting step is executable.
| cd ~/.claude/plugins/cache/everything-claude-code | ||
| npm install | ||
|
|
||
| # Or for manual install | ||
| cd ~/.claude/plugins/ecc | ||
| npm install |
There was a problem hiding this comment.
This repeats the ~/.claude/plugins/ecc manual-install path, but the repo’s README manual install instructions don’t place anything under ~/.claude/plugins/. Align the troubleshooting steps with the documented manual install locations so the npm install advice points at a real directory (or clarify when users would have a local plugin checkout under ~/.claude/plugins/).
| ## 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) |
There was a problem hiding this comment.
The Table of Contents omits sections that exist later in the document (e.g., “Common Error Messages”, “Getting Help”, “Related Documentation”), which makes navigation harder. Add these sections to the TOC (or remove the TOC) so anchors stay complete/accurate.
TROUBLESHOOTING.md
Outdated
| # 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 |
There was a problem hiding this comment.
The observation file paths here don’t match the repo’s documented continuous-learning-v2 layout (project-scoped ~/.claude/homunculus/projects/<project-hash>/observations.jsonl with a global fallback at ~/.claude/homunculus/observations.jsonl). Using ~/.claude/homunculus/*/… and $(basename $PWD) will usually point to a non-existent directory. Update the commands to reference the correct projects/<project-hash> path (and consider pointing users to ~/.claude/homunculus/projects.json to map project names to hashes).
| # 3. Set shorter timeouts | ||
| export CLAUDE_TIMEOUT=30 | ||
|
|
There was a problem hiding this comment.
CLAUDE_TIMEOUT isn’t referenced anywhere in this repository (no code/docs mention it besides this line), so readers may assume it’s a supported knob when it isn’t. Either remove this suggestion or replace it with the actual supported way to adjust timeouts (with a link to the relevant upstream Claude Code docs, if this is an external env var).
TROUBLESHOOTING.md
Outdated
| find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \; | ||
|
|
||
| # Fix observation directory permissions | ||
| chmod -R 755 ~/.claude/homunculus |
There was a problem hiding this comment.
The command chmod -R 755 ~/.claude/homunculus weakens filesystem permissions on the homunculus directory, making all observation data and related files readable and traversable by other local users on multi-user systems. Since these observation logs can contain sensitive code, commands, and context, another user on the same machine could access them simply by browsing the directory. Instead, keep this directory restricted to the owning user (e.g., using owner-only permissions and avoiding recursive world/group read/execute) and adjust only the minimal paths necessary.
affaan-m
left a comment
affaan-m
left a comment
There was a problem hiding this comment.
Automated review: doc-only changes look good. Approving.
Added a comprehensive troubleshooting guide for the Everything Claude Code (ECC) plugin, covering common issues, symptoms, causes, and solutions.
Description
Added a comprehensive troubleshooting guide for the Everything Claude Code (ECC) plugin, covering common issues, symptoms, causes, and solutions.
Description
Adds
TROUBLESHOOTING.md- a comprehensive reference guide for resolving common issues with the ECC plugin.Type of Change
docs:DocumentationWhat's Included
The troubleshooting guide covers:
1. Memory & Context Issues
2. Agent Harness Failures
3. Hook & Workflow Errors
4. Installation & Setup
5. Performance Issues
6. Common Error Messages
Resolves
Closes #326
Testing
Additional Notes
This guide will help users:
fix:Bug fixfeat:New featurerefactor:Code refactoringdocs:Documentationtest:Testschore:Maintenance/toolingci:CI/CD changesChecklist
node tests/run-all.js)Summary by cubic
Adds TROUBLESHOOTING.md: a guide to quickly diagnose and fix ECC plugin issues, now with safer steps (backup caches/observations, warn on lock‑file removal) and updated commands covering memory/context limits, agent harness failures, hooks/workflows, install/setup, performance, and common errors; fixes #326.
Written for commit b94fdb6. Summary will update on new commits.
Summary by CodeRabbit