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):**
```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):**
```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):**
```powershell
.\install.ps1 <languages>
# Example: .\install.ps1 python typescript
```

**macOS/Linux (Bash):**
```bash
./install.sh <languages>
# Example: ./install.sh python typescript
```

**Cross-platform (npm):**
```bash
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:
```yaml
tools: ["Read", "Grep", "Glob"]
```
To:
```yaml
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):

```json
{
  "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

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

### 4c. Verify the observe script exists

```bash
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:
```bash
# 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
```

## Updating ECC

The installer overwrites all files in `~/.claude/`, so updating is straightforward — but custom changes (model tiers, hook fixes) will be lost. Back them up first.

### Update steps

**1. Pull the latest version:**

**Windows (PowerShell):**
```powershell
cd C:\Users\<USERNAME>\everything-claude-code
git pull
npm install
```

**macOS/Linux (Bash):**
```bash
cd ~/everything-claude-code
git pull
npm install
```

**2. Back up your customizations:**
```bash
# Save agent model overrides
grep -l 'model: opus' ~/.claude/agents/*.md > /tmp/ecc-opus-agents.txt

# Save patched hook files
cp ~/.claude/skills/continuous-learning-v2/hooks/observe.sh /tmp/observe.sh.bak
cp ~/.claude/skills/continuous-learning-v2/scripts/detect-project.sh /tmp/detect-project.sh.bak
cp ~/.claude/skills/continuous-learning-v2/config.json /tmp/cl-config.json.bak
```

**3. Re-run the installer:**

**Windows (PowerShell):**
```powershell
.\install.ps1 python typescript
```

**macOS/Linux (Bash):**
```bash
./install.sh python typescript
```

**4. Re-apply customizations:**

- Re-apply agent model tiers (Step 6 above)
- Re-apply the three Windows hook fixes (gotchas 6–8 above)
- Re-enable observer in `config.json` (`"enabled": true`)
- Re-add `Bash` to planner and architect tools (Step 3 above)

### Check current version

```bash
cat ~/.claude/plugin.json | grep version
# or from the repo:
cat ~/everything-claude-code/VERSION
```