Rewrite ecc-setup-guide.md for ECC v2.0.0: the new `ecc` selective-install
CLI (profiles, auto-update, doctor/repair/plan/catalog/consult), the
skills/ecc + rules/ecc namespaced layout, updated install/model-tier and
Continuous-Learning-v2 sections, and the `--dry-run auto-update` footgun
(it performs a real install). Note 2 of 3 Windows CL-v2 bugs are now fixed
upstream.
Index the guide in README.md and bump the Last updated date.
Clarify the two git-history depth knobs and how to keep indexing fast on
repos with thousands of commits:
- vex history --depth N — query-time walk, per file (caps latency)
- vex index --history-depth N — one-time build, global newest-N (like git log -nN)
Added to the setup example, the .vex.toml history comment, and the command
reference in vex.md.
2026-06-11 01:18:29 +03:00
3 changed files with 197 additions and 161 deletions
A collection of interesting and useful facts, tips, tools, and guides for working with Claude and Claude Code.
@@ -10,6 +10,10 @@ A collection of interesting and useful facts, tips, tools, and guides for workin
MCP servers, skills, and plugins that extend Claude Code — including Context7 (library docs), AST Index, and vex (hybrid code search; summarized here with a link to its full reference).
### [Everything Claude Code (ECC) — Setup Guide](ecc-setup-guide.md)
Step-by-step setup and update guide for ECC (Everything Claude Code) v2.0.0 — clone/install, the `ecc` selective-install CLI (profiles, `auto-update`, `doctor`/`repair`), the `skills/ecc/` namespaced layout, agent model tiers, Continuous Learning v2, and Windows gotchas.
Minimal Gitea Actions workflow: push a `v*` tag → create a Gitea release with optional `RELEASE_NOTES.md`. No builds, no artifacts — just a release entry.
Step-by-step instructions for setting up ECC on a new machine. Can be followed manually or by Claude.
> **Staleness warning:** The Windows-specific fixes (gotchas 6–8) were documented against ECC as of early 2026. These bugs may have been fixed upstream — check the [ECC repository](https://github.com/affaan-m/everything-claude-code) for recent changes before applying the workarounds.
> **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](https://github.com/affaan-m/ECC) before relying on any version-specific detail below.
## Prerequisites
- Node.js + npm installed
- Git installed
- Claude Code CLI installed
-**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)
> 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 the installer **from inside the cloned repo**.
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:
**Windows (PowerShell):**
-`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)
```powershell
.\install.ps1<languages>
# Example: .\install.ps1 python typescript
nodescripts/ecc.jspythontypescript# bare languages route to "install"
```
**macOS/Linux (Bash):**
Equivalent compat scripts (auto-install deps, then delegate to the installer):
> **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.
### Option B — Profile mode (v2.0.0, recommended for new installs)
### What gets installed
All files go to `~/.claude/` (global, applies to all projects):
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 |
`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`:
```yaml
# from
tools:["Read","Grep","Glob"]
# to
tools:["Read","Grep","Glob","Bash"]
```
All other agents already have `Bash` in their tools list.
`~/.claude/skills/ecc/continuous-learning-v2/config.json` ships with `"enabled": false`. Set it to `true`:
```json
{"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
```bash
ls ~/.claude/skills/continuous-learning-v2/hooks/observe.sh
ls ~/.claude/skills/ecc/continuous-learning-v2/hooks/observe.sh
```
If missing, re-run the installer from Step 2.
If missing, re-run the installer (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 |
| `/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:
1.**`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`).
2.**`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`.
3.**Observer disabled by default** — `~/.claude/skills/continuous-learning-v2/config.json` ships with `"enabled": false`. **Fix:** Set `"enabled": true`.
Hooks and new/changed agents only take effect after a restart.
## 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.
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.).
Edit the `model:` line in each agent's frontmatter in `~/.claude/agents/`:
| **haiku** | `doc-updater` | Lightweight docs work |
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.
> These overrides are intentional drift and will show up in `ecc doctor` as "drifted managed files" — that is expected, not an error.
### Update steps
## Post-install verification
**1. Pull the latest version:**
**Windows (PowerShell):**
```powershell
cd C:\Users\<USERNAME>\everything-claude-code
gitpull
npminstall
```bash
node scripts/ecc.js list-installed # target, modules, source version
node scripts/ecc.js doctor # health: drift / missing files / version mismatch
```
**macOS/Linux (Bash):**
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 |
| `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)
```bash
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)
```bash
cd ~/everything-claude-code
git pull
npm install
npm install# if deps changed
node scripts/ecc.js install --target claude python typescript
```
**2. Back up your customizations:**
### 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):
- 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)
Then confirm with `node scripts/ecc.js doctor` (expect `WARNING` only for your intentional model-tier overrides).
### Check current version
```bash
cat ~/.claude/plugin.json | grep version
# or from the repo:
cat ~/everything-claude-code/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.
- **Git history (v1.16):** `history <Symbol>` walks git log and returns every historical version of a symbol — query-time, no index needed, works even on un-indexed repos. Flags: `--diff` (unified diffs between consecutive versions), `--since` / `--until` (date), `--author`, `--kind`, `--branch`, `--depth`, `--limit`. Opt into an indexed sidecar with `vex index --history` for ~ms lookups.
- **Git history (v1.16):** `history <Symbol>` walks git log and returns every historical version of a symbol — query-time, no index needed, works even on un-indexed repos. Flags: `--diff` (unified diffs between consecutive versions), `--since` / `--until` (date), `--author`, `--kind`, `--branch`, `--depth <N>` (max commits **per file** — bump down to cap query latency), `--limit <N>` (cap total results). Opt into an indexed sidecar with `vex index --history` for ~ms lookups.
**Taming history cost on large repos:** the two depth knobs are different. `vex history --depth <N>` limits the *query-time* walk **per file**. `vex index --history-depth <N>` caps the *one-time index build* at the **global** newest-N commits (mirrors `git log -nN`, implies `--history`); both are unbounded by default. On a repo with thousands of commits, build with e.g. `vex index --history-depth 500` so a full-history walk doesn't blow up index time and size.
- **Search scope & metadata filters:** `vex search` and `vex usages` accept `--kind fn,method`, `--include` / `--exclude '<glob>'` (repeatable), `--since <rev>` / `--since-branched` / `--changed-only` (restrict to git-changed files), plus on `search`: `--visibility pub|priv`, `--async-only` / `--no-async`, `--static-only`, `--sealed-only`, `--context-path <file>` (proximity boost), and `--why` (JSON trace of per-channel FST / BM25 / semantic hit counts — use when results look wrong).
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
alexei.dolgolyov