P0: spawnCommand() replaces shell:true (cmd-shim routing with /d /s /c, quoted argv, windowsVerbatimArguments); permission.ask no longer auto-approves formatter/test shell prefixes; detached spawns register the error listener before resolving. P1: loadToolModule probes .js then .ts for dist and source layouts; V2 setup() tests via mock ctx; installer recognizes every historical plugin registration (./plugins and plugins/ecc-hooks.*) via shared isOpenCodeHookConfigRegistration(); ecc-universal ./plugins export repointed to the live dist/plugins/ecc-hooks.js; opencode.json drops the file-path plugin entry OpenCode 2.x ignores, docs updated. P2: setup() rolls back registrations and releases the directory guard on mid-setup failure; prettier non-zero exits reported as warn; subscription errors discriminated against abort; disposals awaited without unhandled rejections; windowsHide on all spawns; TROUBLESHOOTING curl passes location[directory]. Tests: opencode-plugin-hooks 22/22 (new T01/T02/T03/T05/T10/T11/T13/T14 coverage), build-opencode 11/11 (new T08 export test), hook-consent 12/12, install-executor 26/26, install-lifecycle 73/73, plugin-manifest 71/71.
16 KiB
Troubleshooting Guide
Common issues and solutions for 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
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 enabled
grep -r "observe" ~/.claude/settings.json
Agent Harness Failures
Agent Not Found
Symptom: "Agent not loaded" or "Unknown agent" errors
Causes:
- Plugin not installed correctly
- Agent path misconfiguration
- Marketplace vs manual install mismatch
Solutions:
# Check plugin installation
ls ~/.claude/plugins/cache/
# Verify agent exists (marketplace install)
ls ~/.claude/plugins/cache/*/agents/
# For manual install, agents should be in:
ls ~/.claude/agents/ # Custom agents only
# Reload plugin
# Claude Code → Settings → Extensions → Reload
Workflow Execution Hangs
Symptom: Agent starts but never completes
Causes:
- Infinite loops in agent logic
- Blocked on user input
- Network timeout waiting for API
Solutions:
# 1. Check for stuck processes
ps aux | grep claude
# 2. Enable debug mode
export CLAUDE_DEBUG=1
# 3. Set shorter timeouts
export CLAUDE_TIMEOUT=30
# 4. Check network connectivity
curl -I https://api.anthropic.com
Tool Use Errors
Symptom: "Tool execution failed" or permission denied
Causes:
- Missing dependencies (npm, python, etc.)
- Insufficient file permissions
- Path not found
Solutions:
# Verify required tools are installed
which node python3 npm git
# Fix permissions on hook scripts
chmod +x ~/.claude/plugins/cache/*/hooks/*.sh
chmod +x ~/.claude/plugins/cache/*/skills/*/hooks/*.sh
# Check PATH includes necessary binaries
echo $PATH
Hook & Workflow Errors
Hooks Not Firing
Symptom: Pre/post hooks don't execute
Causes:
- Hooks not registered in settings.json
- Invalid hook syntax
- Hook script not executable
Solutions:
# Check hooks are registered
grep -A 10 '"hooks"' ~/.claude/settings.json
# Verify hook files exist and are executable
ls -la ~/.claude/plugins/cache/*/hooks/
# Test hook manually
bash ~/.claude/plugins/cache/*/hooks/pre-bash.sh <<< '{"command":"echo test"}'
# Re-register hooks (if using plugin)
# Disable and re-enable plugin in Claude Code settings
Python/Node Version Mismatches
Symptom: "python3 not found" or "node: command not found"
Causes:
- Missing Python/Node installation
- PATH not configured
- Wrong Python version (Windows)
Solutions:
# Install Python 3 (if missing)
# macOS: brew install python3
# Ubuntu: sudo apt install python3
# Windows: Download from python.org
# Install Node.js (if missing)
# macOS: brew install node
# Ubuntu: sudo apt install nodejs npm
# Windows: Download from nodejs.org
# Verify installations
python3 --version
node --version
npm --version
# Windows: Ensure python (not python3) works
python --version
Dev Server Blocker False Positives
Symptom: Hook blocks legitimate commands mentioning "dev"
Causes:
- Heredoc content triggering pattern match
- Non-dev commands with "dev" in arguments
Solutions:
# This is fixed in v1.8.0+ (PR #371)
# Upgrade plugin to latest version
# Workaround: Wrap dev servers in tmux
tmux new-session -d -s dev "npm run dev"
tmux attach -t dev
# Disable hook temporarily if needed
# Edit ~/.claude/settings.json and remove pre-bash hook
Installation & Setup
Plugin Not Loading
Symptom: Plugin features unavailable after install
Causes:
- Marketplace cache not updated
- Claude Code version incompatibility
- Corrupted plugin files
- Local Claude setup was wiped or reset
Solutions:
# First inspect what ECC still knows about this machine
ecc list-installed
ecc doctor
ecc repair
# Only reinstall if doctor/repair cannot restore the missing files
# 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 → ECC → Uninstall
# Then reinstall from marketplace
# If the issue is marketplace/account access, use ECC Tools billing/account recovery separately; do not use reinstall as a proxy for account recovery
# Check Claude Code version
claude --version
# Requires Claude Code 2.0+
# Manual install (if marketplace fails)
git clone https://github.com/affaan-m/ECC.git
cp -r ECC ~/.claude/plugins/ecc
Package Manager Detection Fails
Symptom: Wrong package manager used (npm instead of pnpm)
Causes:
- No lock file present
- CLAUDE_PACKAGE_MANAGER not set
- Multiple lock files confusing detection
Solutions:
# Set preferred package manager globally
export CLAUDE_PACKAGE_MANAGER=pnpm
# Add to ~/.bashrc or ~/.zshrc
# Or set per-project
echo '{"packageManager": "pnpm"}' > .claude/package-manager.json
# Or use package.json field
npm pkg set packageManager="pnpm@8.15.0"
# 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
OpenCode Fails to Start on Termux/Android
Symptom: Changed-files tracking silently stops working (a one-time
[ECC] changed-files tracking disabled warning appears in the OpenCode
logs), or (on older versions) opencode crashes on startup entirely with a
Bun ResolveMessage, e.g.:
ResolveMessage: Cannot find module '../plugins/lib/changed-files-store.js' from '.../.opencode/tools/changed-files.ts'
Causes:
- The
~/.opencodeinstall is missing or incomplete for this machine — usuallytools/andplugins/are present butplugins/lib/never finished copying (an interrupted install, or a storage/permission hiccup that's more common on Android's filesystem). Both thechanged-filestool and theecc-hooksplugin depend onplugins/lib/changed-files-store.js; sinceecc-hooks.tsis OpenCode's plugin entry point (loaded once at session startup, beforetools/index.ts's barrel file), a missing dependency there used to crash the entire OpenCode session before any hooks could load — not just the one tool.
Solutions:
# From the ECC repo, check for and repair missing/incomplete managed files
ecc doctor --target opencode
ecc repair --target opencode
# If that reports no drift but plugins/ is still missing on the device,
# re-run the ECC installer for the opencode target
Note: If you're also seeing ProviderModelNotFoundError: Model not found: openai/gpt-5.5
referencing ~/.config/opencode/oh-my-opencode-slim.json, that file belongs to the
third-party oh-my-opencode-slim
plugin, not ECC — ECC never writes to ~/.config/opencode/. Fix the model prefix
(opencode/... instead of openai/...) there, or file it against that project.
OpenCode 2.x: PluginModule.LoadError and red "Duplicate plugin ID" entries
Symptoms (two distinct failures, often in sequence):
-
Red startup banner / log lines:
PluginModule.LoadError: Plugin must export a default definition with an id and an effect or setup function. (cause: SchemaError(Expected object at ["default"]))reported against
plugins/ecc-hooks.ts(global or project.opencode/plugins/). -
After a first fix attempt, the TUI plugins panel shows
ecc-hooksmultiple times with red entries readingDuplicate plugin ID: ecc-hooks, even though the hooks themselves are working.
Causes:
- V1 plugin on a V2 runtime. OpenCode 1.x plugins default-export an async
function returning a keyed hook map. OpenCode 2.x requires a definition object
{ id, setup(ctx) }and does not run V1 implementations (see migrate-v1). Cause A produces theExpected object at ["default"]schema error. - Duplicate registration. OpenCode 2.x loads plugins by directory
discovery: every root-level file in a plugins directory is a separate
entry. If
index.tsre-exports the same definition asecc-hooks.ts, the idecc-hooksregisters twice; all but the first entry are markedfailed: Duplicate plugin ID. A copy of the same file in both the global config plugins dir and the project.opencode/plugins/compounds it. Note that thepluginconfig array does not accept file paths — an entry like"./plugins/ecc-hooks.ts"logs "configured plugin path must be a directory" and is skipped (verified against OpenCode 2.2.5'sconfig/plugin/source.ts), so it cannot pin or dedupe entries.
Fix layout (current design):
.opencode/plugins/ecc-hooks.tsis the only file carrying hook logic. V1 → V2 registration mapping:tool.execute.before/after→ctx.tool.hook(...),shell.env→ctx.shell.hook("create.before", ...),permission.ask→ctx.permission.hook("evaluate", ...)(mutateevent.effect), keyed event handlers (file.edited,session:*,todo.updated) →ctx.event.subscribe()filtered onevent.type.opencode.jsoncarries nopluginentry for the hooks file. OpenCode 2.x discoversplugins/ecc-hooks.tsfrom the plugins directory; a configured file path would be ignored with a warning anyway.plugins/index.tsis an inert stub with the distinct idecc-hooks-entry. Never make it re-export the real definition: that is exactly what triggers the duplicate-id failures. It must keep a default export with an id + setup (a plain non-plugin module in a loaded directory would throw the schema error again), and it must remain present on disk for the install/uninstall plans. Module consumers of the published package get the live plugin through theecc-universal/pluginsexport, which maps todist/plugins/ecc-hooks.js.
Diagnosing (do this before editing anything):
-
Read the server log, and check the
run=id and timestamp of every error line — TUI banners survive from a process that predates your fix, so match errors against the current run only:~/.local/share/opencode/log/opencode.log # Windows, Linux, Termux -
Ignore unrelated network noise when triaging plugins:
Failed to fetch models.dev,failed to sync GitHub Copilot models: 403, andupdate check failedare connectivity/auth issues, not hook failures. -
Query the live plugin table — this is the ground truth behind the TUI panel. The server port comes from
opencode service status; credentials are Basic auth with thepasswordfield of~/.config/opencode/service.json./api/pluginis location-scoped: pass the affected project directory aslocation[directory], otherwise you inspect the service's default location and can miss the failures you are chasing (a location with no live session may report no entries at all):curl -s -u "opencode:$(sed -n 's/.*"password": "\(.*\)".*/\1/p' ~/.config/opencode/service.json)" \ --get "http://127.0.0.1:<port>/api/plugin" \ --data-urlencode "location[directory]=/path/to/affected/project" \ | jq '[.data[] | select(.state.status != "active")]' -
opencode plugin listshows each registered entry with its source path. The same id appearing from two-plus sources predicts a duplicate-ID rejection.
Environment-variable note: ECC_HOOK_PROFILE / ECC_DISABLED_HOOKS are
read once at plugin setup. On Windows, setx affects only new processes, and
a service restarted from a terminal that predates the setx still inherits the
stale environment block — restart from a freshly opened terminal.
Performance Issues
Slow Response Times
Symptom: Agent takes 30+ seconds to respond
Causes:
- Large observation files
- Too many active hooks
- Network latency to API
Solutions:
# 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
# Keep active observation files small
# Large archives should live under ~/.claude/homunculus/archive/
High CPU Usage
Symptom: Claude Code consuming 100% CPU
Causes:
- Infinite observation loops
- File watching on large directories
- Memory leaks in hooks
Solutions:
# Check for runaway processes
top -o cpu | grep claude
# Disable continuous learning temporarily
touch ~/.claude/homunculus/disabled
# Restart Claude Code
# Cmd/Ctrl+Q then reopen
# Check observation file size
du -sh ~/.claude/homunculus/*/
Common Error Messages
"EACCES: permission denied"
# Fix hook permissions
find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;
# Fix observation directory permissions
chmod -R u+rwX,go+rX ~/.claude/homunculus
"MODULE_NOT_FOUND"
# Install plugin dependencies
# Replace <version> with the version from `claude plugin list`, for example 2.2.3
cd "$HOME/.claude/plugins/cache/ecc/ecc/<version>"
npm install
# Or for manual install
cd ~/.claude/plugins/ecc
npm install
"spawn UNKNOWN"
# Windows-specific: Ensure scripts use correct line endings
# Convert CRLF to LF
find ~/.claude/plugins -name "*.sh" -exec dos2unix {} \;
# Or install dos2unix
# macOS: brew install dos2unix
# Ubuntu: sudo apt install dos2unix
Getting Help
If you're still experiencing issues:
- Check GitHub Issues: github.com/affaan-m/ECC/issues
- Enable Debug Logging:
export CLAUDE_DEBUG=1 export CLAUDE_LOG_LEVEL=debug - Collect Diagnostic Info:
claude --version node --version python3 --version echo $CLAUDE_PACKAGE_MANAGER ls -la ~/.claude/plugins/cache/ - Open an Issue: Include debug logs, error messages, and diagnostic info
Related Documentation
- README.md - Installation and features
- CONTRIBUTING.md - Development guidelines
- docs/ - Detailed documentation
- examples/ - Usage examples