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.

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