Troubleshooting

Installation Issues

”Command not found: ecc”

Make sure the global npm bin directory is in your PATH:

npm config get prefix    # Check npm prefix
export PATH="$PATH:$(npm config get prefix)/bin"

Windows PowerShell Execution Policy

If install.ps1 fails with an execution policy error:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Yarn Berry Compatibility

ECC supports Yarn 4.x (Berry). If you encounter issues, ensure nodeLinker: node-modules is set in .yarnrc.yml.

Hook Issues

Hooks Not Firing

1. Check that hooks are installed: cat ~/.claude/hooks.json
2. Verify the hook profile: echo $ECC_HOOK_PROFILE (default: standard)
3. Check for disabled hooks: echo $ECC_DISABLED_HOOKS

Hook Errors on Windows

Windows uses .cmd wrappers for Node.js scripts. If hooks fail:

• Ensure Node.js is in your PATH
• Check that scripts/hooks/ files have correct line endings (LF, not CRLF)

Agent Issues

Agent Not Found

Agents must be in the agents/ directory with .md extension and valid YAML frontmatter.

Agent Using Wrong Model

Check the model field in the agent’s frontmatter. Valid values: opus, sonnet, haiku.

MCP Issues

MCP Server Connection Failed

1. Verify the server is installed and accessible
2. Check API keys are set in environment variables
3. Keep active MCP servers under 10 to avoid context window issues

Performance

Slow Context Loading

• Reduce active MCP servers
• Use selective install (language-specific profile) instead of full install
• Run /context-budget to analyze token usage

High Token Usage

• Use model routing (/model-route) to match tasks with appropriate model tiers
• Run /harness-audit to identify optimization opportunities
• Use /aside for exploratory conversations that don’t need full context