claude-code-facts/ecc-setup-guide.md

Everything Claude Code (ECC) — Setup Guide

Step-by-step instructions for setting up ECC on a new machine. Can be followed manually or by Claude.

Prerequisites

• Node.js + npm installed
• Git installed
• Claude Code CLI installed
• PowerShell (Windows) or Bash (macOS/Linux)

Step 1 — Clone and install

Windows (PowerShell):

git clone https://github.com/affaan-m/everything-claude-code.git C:\Users\<USERNAME>\everything-claude-code
cd C:\Users\<USERNAME>\everything-claude-code
npm install

macOS/Linux (Bash):

git clone https://github.com/affaan-m/everything-claude-code.git ~/everything-claude-code
cd ~/everything-claude-code
npm install

Step 2 — Run the installer

Run the installer from inside the cloned repo.

Windows (PowerShell):

.\install.ps1 <languages>
# Example: .\install.ps1 python typescript

macOS/Linux (Bash):

./install.sh <languages>
# Example: ./install.sh python typescript

Cross-platform (npm):

npx ecc-install <languages>

Available languages: python, typescript, golang, swift, php, rust, cpp, csharp, java, kotlin, perl

Note: In legacy-compat mode the installer copies rules for ALL languages regardless of arguments. The extra rules are harmless — they sit in ~/.claude/rules/<lang>/ and only load when relevant.

What gets installed

All files go to ~/.claude/ (global, applies to all projects):

Category	Location	Examples
Rules	~/.claude/rules/	coding-style, testing, security (per language)
Agents	~/.claude/agents/	planner, architect, code-reviewer, tdd-guide, security-reviewer
Skills	~/.claude/skills/	python-patterns, tdd-workflow, e2e-testing, continuous-learning
Commands	~/.claude/commands/	/plan, /tdd, /code-review, /verify, /learn
Hooks	~/.claude/hooks/	auto-format, console-log check, cost tracker

Step 3 — Add Bash tool to read-only agents

Some agents (planner, architect) ship with only Read, Grep, Glob tools. To enable ast-index and other CLI tools, add Bash to their tool lists.

Edit these files in ~/.claude/agents/:

• planner.md
• architect.md

Change the frontmatter tools line from:

tools: ["Read", "Grep", "Glob"]

To:

tools: ["Read", "Grep", "Glob", "Bash"]

All other agents already have Bash in their tools list.

Step 4 — Configure Continuous Learning v2

4a. Add observation hooks

Add the following to ~/.claude/settings.json (merge into existing hooks key if one exists):

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh"
      }]
    }]
  }
}

4b. Create the directory structure

mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}

4c. Verify the observe script exists

ls ~/.claude/skills/continuous-learning-v2/hooks/observe.sh

If missing, re-run the installer from Step 2.

Step 5 — Restart Claude Code

Hooks and new agents only take effect after restarting Claude Code.

Post-install verification

Run these commands inside Claude Code to verify:

Command	Expected result
/plan "test"	Should invoke the planner agent
/instinct-status	Should show instinct status (empty on first run)
/code-review	Should invoke the code-reviewer agent

Useful commands

Command	Purpose
/plan	Create implementation plan before coding
/tdd	Test-driven development workflow
/code-review	Review code for quality issues
/verify	Run verification loop
/learn	Manually extract patterns mid-session
/instinct-status	View learned instincts
/evolve	Cluster instincts into skills/commands/agents
/promote	Promote project instincts to global scope
/projects	List known projects and instinct counts

Known gotchas

1. /plugin commands don't exist — The ECC README references /plugin marketplace add and /plugin install but Claude Code has no such CLI commands. Use the install.ps1 / install.sh script instead.

2. The extraKnownMarketplaces entry is cosmetic — Adding ECC to extraKnownMarketplaces in settings.json does NOT enable it as a plugin and it will NOT appear in the enabled/disabled plugins list. The manual install is the actual installation method.

3. Windows: don't mix WSL and PowerShell — If npm is installed on Windows, run everything in PowerShell with Windows paths (C:\Users\...). If using WSL, run everything in WSL with Linux paths (~/...). Mixing causes path resolution failures.

4. Windows paths in PowerShell — Use C:\Users\<USERNAME>\..., NOT /c/Users/... (that's Git Bash / WSL syntax).

5. Agent model selection — Each agent .md file in ~/.claude/agents/ supports a model field in frontmatter. Options: haiku (fast/cheap), sonnet (balanced), opus (deep reasoning). Choose based on agent complexity needs.

Continuous Learning v2 — Windows fixes (critical)

The observe hook ships with three bugs that silently prevent all observations on Windows:

6. python3 is the Windows Store stub — On Windows, python3 resolves to the Microsoft Store redirect (AppData/Local/Microsoft/WindowsApps/python3) which returns exit code 49 instead of running Python. The hook's resolve_python_cmd() uses command -v which finds the stub. Fix: In both ~/.claude/skills/continuous-learning-v2/hooks/observe.sh and ~/.claude/skills/continuous-learning-v2/scripts/detect-project.sh, change resolve_python_cmd() to test execution ("$candidate" -c "1") instead of just checking presence (command -v).

7. claude-vscode entrypoint rejected — The hook's Layer 1 filter only allows cli and sdk-ts entrypoints. VS Code extension sets CLAUDE_CODE_ENTRYPOINT=claude-vscode, so every observation is silently skipped. Fix: Add claude-vscode to the allowed entrypoints case pattern in observe.sh.

8. Observer disabled by default — ~/.claude/skills/continuous-learning-v2/config.json ships with "enabled": false. Fix: Set "enabled": true.

Step 6 — Configure agent model tiers

ECC agents ship with sonnet as default. For better results, set thinking-heavy agents to opus and keep mechanical agents on cheaper models.

Edit the model: line in each agent's frontmatter in ~/.claude/agents/:

Model	Agents	Rationale
opus	code-reviewer, python-reviewer, typescript-reviewer, rust-reviewer, go-reviewer, java-reviewer, kotlin-reviewer, cpp-reviewer, flutter-reviewer, database-reviewer, security-reviewer, tdd-guide, planner, architect, chief-of-staff	Deep reasoning for code quality, security, architecture
sonnet	build-error-resolver, cpp-build-resolver, go-build-resolver, java-build-resolver, kotlin-build-resolver, rust-build-resolver, pytorch-build-resolver, e2e-runner, harness-optimizer, loop-operator, docs-lookup, refactor-cleaner	Mechanical tasks, error fixing
haiku	doc-updater	Lightweight docs work

To bulk-update reviewers and thinking-heavy agents to opus:

# From bash/git bash:
for f in ~/.claude/agents/{code,python,typescript,rust,go,java,kotlin,cpp,flutter,database,security}-reviewer.md ~/.claude/agents/tdd-guide.md; do
  sed -i 's/^model: sonnet/model: opus/' "$f"
done