Install ECC on Mac Mini 2026: Everything Claude Code Setup Guide

Why Install ECC on a Mac Mini?

Claude Code runs best on macOS with stable SSH, fast NVMe, and always-on uptime. Many teams rent a dedicated Mac Mini M4 instead of tying ECC to a laptop that sleeps:

• Persistent ~/.claude state — skills, hooks, and rules survive your local machine reboots when the harness lives on the server
• Low latency to Anthropic API — Japan node ~24 ms RTT vs 180+ ms from mis-matched regions (region matrix)
• 16 GB is enough for ECC + Claude Code CLI; reserve 24 GB if you also run OpenClaw or heavy Docker sidecars

ECC is not a replacement for Claude Code — it is a configuration and workflow layer on top. If you only need a bare terminal agent without 246 skills, see Claude Code free alternatives first.

ECC Architecture: What Gets Installed

ECC (repo: affaan-m/ECC, npm: ecc-universal) installs into harness-specific directories. For Claude Code on macOS:

Three public identifiers (do not mix them up):

1. GitHub: affaan-m/ECC
2. Claude marketplace plugin: ecc@ecc
3. npm CLI: ecc-universal / npx ecc-install

Upstream explicitly warns: /plugin install + ./install.sh --profile full = duplicate skills and broken hooks. Choose one path below.

External reference: Anthropic Claude Code documentation.

Prerequisites on Mac Mini

Verify before installing:

# macOS 14+ recommended (Sequoia tested on M4) sw_vers # Node.js 20 LTS (18+ minimum for ECC scripts) node -v # expect v20.x or v22.x npm -v # Git git --version # Claude Code CLI (install separately if missing) claude --version

On a fresh KuzCloud node, install Node via Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" brew install node git

Budget ~2 GB disk for ECC clone + node_modules, ~500 MB RAM at idle for hooks, plus Claude Code's own footprint. For rental window planning, a 3–7 day burst covers first-time ECC setup and evaluation.

Install ECC on Mac Mini: 8-Step Runbook

Step 1 — SSH into your Mac Mini and create a workspace

ssh -i ~/.ssh/kuzcloud.pem user@YOUR_NODE_IP mkdir -p ~/ecc-lab && cd ~/ecc-lab

Credentials usually arrive within ~5 minutes of ordering — same flow as other remote Mac guides.

Step 2 — Clone the ECC repository

git clone https://github.com/affaan-m/ECC.git cd ECC git checkout main # or pin a release tag, e.g. v2.0.0-rc.1

Step 3 — Install Node dependencies

npm install # Alternatives: pnpm install | yarn install | bun install

This step downloads hook adapters and installer scripts. Expect 3–8 minutes on first run depending on region bandwidth.

Step 4 — Choose ONE install path

Path A — Claude Code plugin (recommended for most users)

Inside an interactive Claude Code session on the Mac Mini:

/plugin marketplace add https://github.com/affaan-m/ECC /plugin install ecc@ecc

Then copy only the rule packs you need (plugin cannot auto-distribute rules):

mkdir -p ~/.claude/rules/ecc cp -R rules/common ~/.claude/rules/ecc/ cp -R rules/typescript ~/.claude/rules/ecc/ # omit if you do not use TS

Do not run ./install.sh --profile full after Path A.

Path B — Manual minimal profile (no hooks, lowest overhead)

./install.sh --profile minimal --target claude

Equivalent:

npx ecc-install --profile minimal --target claude

Use Path B on 16 GB nodes when hooks feel too aggressive or you only want rules + agents.

Path C — Full manual install (power users only)

./install.sh --profile full --target claude

Do not also run /plugin install ecc@ecc if you choose Path C.

Step 5 — Optional: consult before installing extra modules

npx ecc consult "security reviews typescript" --target claude

Review the preview plan, then install scoped capabilities:

npx ecc install --profile minimal --target claude --with capability:machine-learning

Step 6 — Verify install health

node scripts/ecc.js list-installed node scripts/ecc.js doctor node scripts/ecc.js repair # safe first repair pass if doctor reports issues

Expected: doctor reports installed profiles without duplicate hook registrations.

Step 7 — Configure hook profile (Path A or full install only)

export ECC_HOOK_PROFILE=standard # or minimal | strict export ECC_DISABLED_HOOKS= # comma-separated to disable specific hooks

Add to ~/.zshrc on the Mac Mini for persistence across SSH sessions.

Step 8 — Smoke-test Claude Code with ECC

cd ~/ecc-lab/sample-project # your repo claude

In session, run a packaged command (example):

/harness-audit

Or ask: "Use ECC skills to review this README for token-heavy sections."

Path Comparison Table

Recommendation: If you rent a KuzCloud Mac Mini only for ECC + Claude Code, use Path A + rules/common only, then add language packs incrementally. Enable hooks with ECC_HOOK_PROFILE=minimal first; escalate to standard only after one clean week.

Troubleshooting

Error: duplicate skills / commands fire twice

Symptom: Same slash command appears twice; hook logs show double SessionStart.

Cause: Plugin install + full install.sh stacked.

Fix:

node scripts/ecc.js doctor # Follow reset instructions in ECC README "Reset / Uninstall ECC" # Then reinstall with ONE path only

Error: claude: command not found on remote Mac

Symptom: Plugin commands fail; claude --version not found.

Fix:

npm install -g @anthropic-ai/claude-code # Or follow https://docs.anthropic.com/en/docs/claude-code/setup export ANTHROPIC_API_KEY=sk-ant-...

Re-SSH in and repeat Step 4.

Error: marketplace plugin ecc@ecc not found

Symptom: /plugin install ecc@ecc fails on marketplace resolution.

Fix: Skip Path A; use Path B:

cd ~/ecc-lab/ECC && ./install.sh --profile minimal --target claude

Error: Node OOM during npm install

Symptom: Killed: 9 during install on 16 GB Mac Mini.

Fix: Add swap temporarily or upgrade to 24 GB node; alternatively run npm install --omit=dev if upstream documents support.

ECC on Mac Mini vs Buying Hardware

ECC does not require Apple Silicon GPU — any M4 Mac Mini with Node 20 and ~10 GB free disk suffices. If you use ECC fewer than 22 full days per month, renting beats a $599+ purchase (rent vs buy guide).

FAQ

Is ECC the same as Claude Code?

No. Claude Code is Anthropic's agentic coding CLI. ECC is a community-maintained harness enhancement pack (skills, rules, hooks) maintained at github.com/affaan-m/ECC. You need Claude Code (or another supported harness) installed first.

Can I install ECC on Cursor without Claude Code?

Yes. ECC supports Cursor, Codex, OpenCode, and others via --target cursor (or harness-specific installers). This guide focuses on Claude Code on Mac Mini because that is the most common KuzCloud workload.

Does ECC send my code to extra third parties?

ECC adds local rules, hooks, and skills. LLM calls still go through whichever model provider your harness uses (Anthropic, OpenAI, etc.). Review ECC's Security Guide and run /security-scan (AgentShield) before production repos.

How do I uninstall ECC completely?

Follow the upstream Reset / Uninstall ECC section: run node scripts/ecc.js repair/list commands, remove ~/.claude/rules/ecc/, uninstall the plugin via Claude Code, and delete duplicated skill folders identified by doctor.

Will ECC work over SSH from my laptop?

Yes. Install ECC on the remote Mac Mini, run claude in tmux or screen, and connect from your laptop via SSH. Use port forwarding only if you need a local GUI for the ECC Tk dashboard (npm run dashboard).