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.

Version note: Written and verified against ECC v2.0.0 (2026-06-23). v2.0.0 is a major rewrite: a new ecc selective-install CLI, a skills/ecc/ + rules/ecc/ namespaced layout, a SQLite/JSON install-state with doctor/repair/auto-update, and ~67 agents / 271 skills in the catalog. The GitHub repo was renamed from affaan-m/everything-claude-code to affaan-m/ECC (homepage https://ecc.tools); the old URL still redirects. Re-check the repository before relying on any version-specific detail below.

Prerequisites

• Node.js ≥ 18 + npm (v2.0.0 declares packageManager: yarn@4, but npm install still works; install.ps1/install.sh auto-install deps for you)
• Git
• Claude Code CLI
• PowerShell (Windows) or Bash (macOS/Linux)

Step 1 — Clone and install dependencies

Windows (PowerShell):

git clone https://github.com/affaan-m/ECC.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/ECC.git ~/everything-claude-code
cd ~/everything-claude-code
npm install

The clone directory name is your choice (everything-claude-code keeps older paths/scripts working). Runtime deps are small (sql.js, ajv, @iarna/toml). If you prefer the declared toolchain, corepack enable && corepack yarn install also works. You can skip npm install entirely if you use install.ps1/install.sh in Step 2 — they install deps automatically when node_modules is missing.

Step 2 — Run the installer

Run from inside the cloned repo. v2.0.0 ships a real CLI (scripts/ecc.js, also exposed as the ecc bin). Two equivalent ways to invoke it:

• node scripts/ecc.js <command> — most reliable, no PATH/npx ambiguity
• npx ecc <command> — works from inside the repo (the postinstall banner suggests this form)

Option A — Legacy language mode (simplest; matches older setups)

node scripts/ecc.js python typescript        # bare languages route to "install"

Equivalent compat scripts (auto-install deps, then delegate to the installer):

.\install.ps1 python typescript              # Windows

./install.sh python typescript               # macOS/Linux

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

Option B — Profile mode (v2.0.0, recommended for new installs)

node scripts/ecc.js install --profile developer --target claude

Profiles (node scripts/ecc.js catalog profiles for the live list):

Profile	Modules	Use
minimal	5	Low-context: rules, agents, commands, platform configs, quality — no hook runtime
core	6	Harness baseline with commands, hooks, platform configs, quality
developer	9	Default engineering profile for most users
security	7	Security-heavy, baseline runtime + security guidance
research	9	Research/content: investigation, synthesis, publishing
full	23	Everything currently classified
opencode	3	OpenCode target (excludes hooks-runtime)

Not sure what you need? node scripts/ecc.js consult "security reviews and python" recommends components/profiles from a natural-language query, and node scripts/ecc.js catalog components --family language lists installable components.

Selective install caveat: Profiles/languages only install the selected modules' skills. The full catalog is ~271 skills; a developer/language install lands ~70–80 under ~/.claude/skills/ecc/. Add more later with --modules <id> or a broader profile — they are additive.

What gets installed (v2.0.0 layout)

All files go to ~/.claude/ (global, applies to all projects). v2.0.0 namespaces skills and rules under ecc/; agents and commands stay flat (legacy-compat):

Category	Location	Notes
Skills	~/.claude/skills/ecc/<name>/	namespaced under ecc/
Rules	~/.claude/rules/ecc/	namespaced under ecc/
Agents	~/.claude/agents/<name>.md	flat — overwrites existing files of the same name
Commands	~/.claude/commands/<name>.md	flat
Hooks	~/.claude/hooks/	reusable hook scripts
ECC runtime	~/.claude/scripts/	lib/, hooks/ used by the CLI (new in v2.0.0)
Cross-harness	~/.claude/.agents/	shared agent/skill surface for Codex/Cursor/etc. (new)

settings.json and .claude.json are not touched by the installer — your hooks config and MCP server registrations are safe.

The install records state in ~/.claude/ecc/install-state.json (queryable with ecc list-installed).

Step 3 — Add Bash to read-only agents (still required in v2.0.0)

planner and architect ship with only Read, Grep, Glob. To let them use ast-index/vex and other CLI tools, add Bash. Edit the frontmatter tools: line in ~/.claude/agents/planner.md and ~/.claude/agents/architect.md:

# from
tools: ["Read", "Grep", "Glob"]
# to
tools: ["Read", "Grep", "Glob", "Bash"]

# Bash one-liner:
for a in planner architect; do
  sed -i 's/^tools: \["Read", "Grep", "Glob"\]$/tools: ["Read", "Grep", "Glob", "Bash"]/' ~/.claude/agents/$a.md
done

All other agents already include Bash.

Step 4 — Configure Continuous Learning v2

In v2.0.0 CL-v2 lives at ~/.claude/skills/ecc/continuous-learning-v2/.

4a. Add observation hooks

Merge into ~/.claude/settings.json (combine with any existing hooks key):

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

4b. Enable the observer (still ships disabled)

~/.claude/skills/ecc/continuous-learning-v2/config.json ships with "enabled": false. Set it to true:

{ "enabled": true }

Windows note: The two historical Windows-only observer bugs are fixed in v2.0.0 — observe.sh now detects the python3 Microsoft Store stub (_is_windows_app_installer_stub) and allows the claude-vscode/claude-desktop entrypoints. The only manual step left is flipping enabled to true above. The ~/.claude/homunculus/ instinct store is auto-created/managed by CL-v2 (no manual mkdir needed).

4c. Verify the observe script exists

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

If missing, re-run the installer (Step 2).

Step 5 — Restart Claude Code

Hooks and new/changed agents only take effect after a restart.

Step 6 — Configure agent model tiers

ECC agents mostly default to sonnet (a few ship opus already — e.g. architect, chief-of-staff, planner). Policy: reviewers and thinking-heavy agents → opus; build/error resolvers and mechanical agents → sonnet; lightweight doc agents → haiku. This applies to the v2.0.0 reviewer additions too (csharp-, react-, vue-, fastapi-, django-, swift-, php-, fsharp-, mle-, healthcare-reviewer, etc.).

Bulk-apply with a glob so it covers current and future reviewers:

cd ~/.claude/agents
# Every *-reviewer agent -> opus
for f in *-reviewer.md; do sed -i 's/^model: sonnet$/model: opus/' "$f"; done
# Thinking-heavy non-reviewer agents -> opus
for f in planner architect tdd-guide chief-of-staff code-architect performance-optimizer; do
  [ -f "$f.md" ] && sed -i 's/^model: sonnet$/model: opus/' "$f.md"
done

Tier	Agents (examples)	Rationale
opus	all *-reviewer, tdd-guide, planner, architect, code-architect, security-reviewer, chief-of-staff, performance-optimizer	Deep reasoning: code quality, security, architecture
sonnet	*-build-resolver, e2e-runner, refactor-cleaner, docs-lookup, harness-optimizer	Mechanical fixes, error resolution
haiku	doc-updater	Lightweight docs work

These overrides are intentional drift and will show up in ecc doctor as "drifted managed files" — that is expected, not an error.

Post-install verification

node scripts/ecc.js list-installed     # target, modules, source version
node scripts/ecc.js doctor             # health: drift / missing files / version mismatch

Inside Claude Code:

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

Useful commands

ECC CLI (node scripts/ecc.js <command>):

Command	Purpose
install	Install content (--profile, --target, or bare languages)
auto-update	Pull latest + reinstall managed targets in one step
doctor	Diagnose drift / missing / version mismatch
repair	Restore drifted or missing managed files (--dry-run to preview)
plan	Preview a resolved install plan (safe, read-only)
catalog	Discover profiles and components
consult	Recommend components/profiles from a NL query
list-installed	Inspect install-state
uninstall	Remove ECC-managed files (--dry-run to preview)
status	SQLite state-store summary

Slash commands (in Claude Code): /plan, /tdd, /code-review, /verify, /learn, /instinct-status, /evolve, /promote, /projects.

Updating ECC

One-command update (v2.0.0)

cd ~/everything-claude-code
node scripts/ecc.js auto-update

auto-update runs git fetch --prune + git pull --ff-only, then reinstalls every managed target using its recorded install request.

⚠️ Footgun — --dry-run auto-update is NOT a dry run. The global --dry-run flag is not honored by auto-update: it still pulls and performs a real reinstall (the flag does not propagate into the child install process). To preview an update safely, use node scripts/ecc.js plan or node scripts/ecc.js install --dry-run --target claude <languages> instead — those genuinely make no changes.

Manual update (equivalent)

cd ~/everything-claude-code
git pull
npm install                                   # if deps changed
node scripts/ecc.js install --target claude python typescript

After any update — re-apply customizations

A reinstall overwrites flat agents, so these are lost and must be re-applied:

1. Agent model tiers (Step 6) — reviewers/thinking-heavy back to opus.
2. Bash on planner + architect (Step 3).
3. "enabled": true in CL-v2 config.json (Step 4b) if you use the observer.

Skills and rules live under ecc/ and are replaced in place, so they need no manual fix-up.

Migrating from a pre-2.0 (flat) install

Old installs put skills/rules flat (~/.claude/skills/<name>). v2.0.0 writes them under ~/.claude/skills/ecc/<name> and does not delete the old flat copies, leaving stale duplicates. After updating, remove only the flat skills that now exist under ecc/ (preserves your own skills and any ECC skill whose module wasn't reinstalled):

cd ~/.claude/skills
comm -12 \
  <(ls -d */ | grep -vx 'ecc/' | xargs -n1 basename | sort) \
  <(ls -d ecc/*/ | xargs -n1 basename | sort) \
  | while read s; do rm -rf "./$s"; done

Then confirm with node scripts/ecc.js doctor (expect WARNING only for your intentional model-tier overrides).

Check current version

node scripts/ecc.js list-installed        # "Source version: X" + recorded modules
node scripts/ecc.js doctor                # flags repo-version mismatch
cat ~/everything-claude-code/VERSION      # repo version on disk

Known gotchas

1. --dry-run auto-update performs a real install — see the Updating section. Preview with ecc plan / ecc install --dry-run instead.

2. v2.0.0 namespaces skills/rules under ecc/ but keeps agents/commands flat. Paths in older notes (~/.claude/skills/<name>) are now ~/.claude/skills/ecc/<name>. Updating from a flat install leaves orphan duplicates (see migration cleanup above).

3. Reinstalls overwrite flat agents — agent model tiers and the planner/architect Bash addition must be re-applied after every update.

4. /plugin install path is unreliable — although v2.0.0 ships plugin/marketplace metadata, the selective-install CLI (ecc install / install.ps1) is the dependable full-install method. Don't rely on /plugin marketplace add / /plugin install.

5. Windows: don't mix WSL and PowerShell — pick one. PowerShell → Windows paths (C:\Users\...); WSL → Linux paths (~/...). Mixing breaks path resolution.

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

7. npm install vs yarn — v2.0.0 declares packageManager: yarn@4 and ships yarn.lock, but also a package-lock.json; npm install works. If you want the declared toolchain use corepack yarn install. Don't commit lockfile churn back to the clone.