ECC

Supports Claude Code, Codex, Cursor, Mcp

Option 1: Install as Plugin (Recommended)

The easiest way to use this repo - install as a Claude Code plugin:

# Add this repo as a marketplace
/plugin marketplace add https://github.com/affaan-m/ECC

# Install the plugin
/plugin install ecc@ecc

Or add directly to your ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "ecc": {
      "source": {
        "source": "github",
        "repo": "affaan-m/ECC"
      }
    }
  },
  "enabledPlugins": {
    "ecc@ecc": true
  }
}

This gives you instant access to all commands, agents, skills, and hooks.

Note: The Claude Code plugin system does not support distributing rules via plugins (upstream limitation). You need to install rules manually:

# Clone the repo first
git clone https://github.com/affaan-m/ECC.git
cd ECC

# Option A: User-level rules (applies to all projects)
mkdir -p ~/.claude/rules/ecc
cp -r rules/common ~/.claude/rules/ecc/
cp -r rules/typescript ~/.claude/rules/ecc/   # pick your stack
cp -r rules/python ~/.claude/rules/ecc/
cp -r rules/golang ~/.claude/rules/ecc/
cp -r rules/php ~/.claude/rules/ecc/

# Option B: Project-level rules (applies to current project only)
mkdir -p .claude/rules/ecc
cp -r rules/common .claude/rules/ecc/
cp -r rules/typescript .claude/rules/ecc/     # pick your stack

Option 2: Manual Installation

If you prefer manual control over what's installed:

# Clone the repo
git clone https://github.com/affaan-m/ECC.git
cd ECC

# Copy agents to your Claude config
cp agents/*.md ~/.claude/agents/

# Copy rules directories (common + language-specific)
mkdir -p ~/.claude/rules/ecc
cp -r rules/common ~/.claude/rules/ecc/
cp -r rules/typescript ~/.claude/rules/ecc/   # pick your stack
cp -r rules/python ~/.claude/rules/ecc/
cp -r rules/golang ~/.claude/rules/ecc/
cp -r rules/php ~/.claude/rules/ecc/
cp -r rules/arkts ~/.claude/rules/ecc/

# Copy skills first (primary workflow surface)
# Recommended (new users): core/general skills only
mkdir -p ~/.claude/skills
cp -r .agents/skills/* ~/.claude/skills/
cp -r skills/search-first ~/.claude/skills/
# Claude Code loads skills only from direct children of ~/.claude/skills.
# Do not nest manual installs under ~/.claude/skills/ecc/.

# Optional: add niche/framework-specific skills only when needed
# for s in django-patterns django-tdd laravel-patterns springboot-patterns quarkus-patterns; do
# cp -r skills/$s ~/.claude/skills/
# done

# Optional: keep maintained slash-command compatibility during migration
mkdir -p ~/.claude/commands
cp commands/*.md ~/.claude/commands/

# Retired shims live in legacy-command-shims/commands/.
# Copy individual files from there only if you still need old names such as /tdd.

Install hooks

Do not copy the raw repo hooks/hooks.json into ~/.claude/settings.json or ~/.claude/hooks/hooks.json. That file is plugin/repo-oriented and is meant to be installed through the ECC installer or loaded as a plugin, so raw copying is not a supported manual install path.

Use the installer to install only the Claude hook runtime so command paths are rewritten correctly:

# macOS / Linux
bash ./install.sh --target claude --modules hooks-runtime

# Windows PowerShell
pwsh -File .\install.ps1 --target claude --modules hooks-runtime

That writes resolved hooks to ~/.claude/hooks/hooks.json and leaves any existing ~/.claude/settings.json untouched.

If you installed ECC via /plugin install, do not copy those hooks into settings.json. Claude Code v2.1+ already auto-loads plugin hooks/hooks.json, and duplicating them in settings.json causes duplicate execution and cross-platform hook conflicts.

Windows note: the Claude config directory is %USERPROFILE%\\.claude, not ~/claude.

Configure MCPs

Claude plugin installs intentionally do not auto-enable ECC's bundled MCP server definitions. This avoids overlong plugin MCP tool names on strict third-party gateways while keeping manual MCP setup available.

Use Claude Code's /mcp command or CLI-managed MCP setup for live Claude Code server changes. Use /mcp for Claude Code runtime disables; Claude Code persists those choices in ~/.claude.json.

For repo-local MCP access, copy desired MCP server definitions from mcp-configs/mcp-servers.json into a project-scoped .mcp.json.

ECC ships exactly one default connector (chrome-devtools); everything else is a skill wrapping a CLI/REST API or an opt-in catalog entry. The rule and the June 2026 audit that retired the previous six defaults live in docs/MCP-CONNECTOR-POLICY.md.

If you already run your own copies of ECC-bundled MCPs, set:

export ECC_DISABLED_MCPS="chrome-devtools"

ECC-managed install and Codex sync flows will skip or remove those bundled servers instead of re-adding duplicates. ECC_DISABLED_MCPS is an ECC install/sync filter, not a live Claude Code toggle.

Important: Replace YOUR_*_HERE placeholders with your actual API keys.

Get up and running in under 2 minutes:

Pick one path only

Most Claude Code users should use exactly one install path:

• Recommended default: install the Claude Code plugin, then copy only the rule folders you actually want.
• Use the manual installer only if you want finer-grained control, want to avoid the plugin path entirely, or your Claude Code build has trouble resolving the self-hosted marketplace entry.
• Do not stack install methods. The most common broken setup is: /plugin install first, then install.sh --profile full or npx ecc-install --profile full afterward.

If you already layered multiple installs and things look duplicated, skip straight to Reset / Uninstall ECC.

Low-context / no-hooks path

If hooks feel too global or you only want ECC's rules, agents, commands, and core workflow skills, skip the plugin and use the minimal manual profile:

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

.\install.ps1 --profile minimal --target claude
# or
npx ecc-install --profile minimal --target claude

This profile intentionally excludes hooks-runtime.

If you want the normal core profile but need hooks off, use:

./install.sh --profile core --without baseline:hooks --target claude

Add hooks later only if you want runtime enforcement:

./install.sh --target claude --modules hooks-runtime

Find the right components first

If you are not sure which ECC profile or component to install, ask the packaged advisor from any project:

npx ecc consult "security reviews" --target claude

It returns matching components, related profiles, and preview/install commands. Use the preview command before installing if you want to inspect the exact file plan.

For production ML/MLOps workflows, keep the install opt-in and component-scoped:

npx ecc consult "mlops training model deployment" --target claude
npx ecc install --profile minimal --target claude --with capability:machine-learning

Step 1: Install the Plugin (Recommended)

NOTE: The plugin is convenient, but the OSS installer below is still the most reliable path if your Claude Code build has trouble resolving self-hosted marketplace entries.

# Add marketplace
/plugin marketplace add https://github.com/affaan-m/ECC

# Install plugin
/plugin install ecc@ecc

Naming + Migration Note

ECC now has three public identifiers, and they are not interchangeable:

• GitHub source repo: affaan-m/ECC
• Claude marketplace/plugin identifier: ecc@ecc
• npm package: ecc-universal

This is intentional. Anthropic marketplace/plugin installs are keyed by a canonical plugin identifier, so ECC uses ecc@ecc to keep tool names and slash-command namespaces short enough for strict Desktop/API validators. Older posts may still show the former long marketplace identifier; treat that as a legacy alias only. Separately, the npm package stayed on ecc-universal, so npm installs and marketplace installs intentionally use different names.

Step 2: Install Rules Only If You Need Them

WARNING: Important: Claude Code plugins cannot distribute rules automatically.

If you already installed ECC via /plugin install, do not run ./install.sh --profile full, .\install.ps1 --profile full, or npx ecc-install --profile full afterward. The plugin already loads ECC skills, commands, and hooks. Running the full installer after a plugin install copies those same surfaces into your user directories and can create duplicate skills plus duplicate runtime behavior.

For plugin installs, manually copy only the rules/ directories you want under ~/.claude/rules/ecc/. Start with rules/common plus one language or framework pack you actually use. Do not copy every rules directory unless you explicitly want all of that context in Claude.

Use the full installer only when you are doing a fully manual ECC install instead of the plugin path.

If your local Claude setup was wiped or reset, that does not mean you need to repurchase ECC. Start with node scripts/ecc.js list-installed, then run node scripts/ecc.js doctor and node scripts/ecc.js repair before reinstalling anything. That usually restores ECC-managed files without rebuilding your setup. If the problem is account or marketplace access for ECC Tools, handle billing/account recovery separately.

# Clone the repo first
git clone https://github.com/affaan-m/ECC.git
cd ECC

# Install dependencies (pick your package manager)
npm install        # or: pnpm install | yarn install | bun install

# Plugin install path: copy only ECC rules into an ECC-owned namespace
mkdir -p ~/.claude/rules/ecc
cp -R rules/common ~/.claude/rules/ecc/
cp -R rules/typescript ~/.claude/rules/ecc/

# Fully manual ECC install path (use this instead of /plugin install)
# ./install.sh --profile full

# Windows PowerShell

# Plugin install path: copy only ECC rules into an ECC-owned namespace
New-Item -ItemType Directory -Force -Path "$HOME/.claude/rules/ecc" | Out-Null
Copy-Item -Recurse rules/common "$HOME/.claude/rules/ecc/"
Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/ecc/"

# Fully manual ECC install path (use this instead of /plugin install)
# .\install.ps1 --profile full
# npx ecc-install --profile full

For manual install instructions see the README in the rules/ folder. When copying rules manually, copy the whole language directory (for example rules/common or rules/golang), not the files inside it, so relative references keep working and filenames do not collide.

Fully manual install (Fallback)

Use this only if you are intentionally skipping the plugin path:

./install.sh --profile full

.\install.ps1 --profile full
# or
npx ecc-install --profile full

If you choose this path, stop there. Do not also run /plugin install.

Reset / Uninstall ECC

If ECC feels duplicated, intrusive, or broken, do not keep reinstalling it on top of itself.

• Plugin path: remove the plugin from Claude Code, then delete the specific rule folders you manually copied under ~/.claude/rules/ecc/.
• Manual installer / CLI path: from the repo root, preview removal first:

node scripts/uninstall.js --dry-run

Then remove ECC-managed files:

node scripts/uninstall.js

You can also use the lifecycle wrapper:

node scripts/ecc.js list-installed
node scripts/ecc.js doctor
node scripts/ecc.js repair
node scripts/ecc.js uninstall --dry-run

ECC only removes files recorded in its install-state. It will not delete unrelated files it did not install.

If you stacked methods, clean up in this order:

1. Remove the Claude Code plugin install.
2. Run the ECC uninstall command from the repo root to remove install-state-managed files.
3. Delete any extra rule folders you copied manually and no longer want.
4. Reinstall once, using a single path.

Step 3: Start Using

# Skills are the primary workflow surface.
# Existing slash-style command names still work while ECC migrates off commands/.

# Plugin install uses the canonical namespaced form
/ecc:plan "Add user authentication"

# Manual install keeps the shorter slash form:
# /plan "Add user authentication"

# Check available commands
/plugin list ecc@ecc

That's it! You now have access to 67 agents, 278 skills, and 94 legacy command shims.

Dashboard GUI

Launch the desktop dashboard to visually explore ECC components:

npm run dashboard
# or
python3 ./ecc_dashboard.py

Features:

• Tabbed interface: Agents, Skills, Commands, Rules, Settings
• Dark/Light theme toggle
• Font customization (family & size)
• Project logo in header and taskbar
• Search and filter across all components

Multi-model commands require additional setup

WARNING: multi-* commands are not covered by the base plugin/rules install above.

To use /multi-plan, /multi-execute, /multi-backend, /multi-frontend, and /multi-workflow, you must also install the ccg-workflow runtime.

Initialize it with npx ccg-workflow.

That runtime provides the external dependencies these commands expect, including:

• ~/.claude/bin/codeagent-wrapper
• ~/.claude/.ccg/prompts/*

Without ccg-workflow, these multi-* commands will not run correctly.

Windows PowerShell:

[Environment]::SetEnvironmentVariable('ECC_CONTEXT_MONITOR_COST_WARNINGS', 'off', 'User')
[Environment]::SetEnvironmentVariable('ECC_SESSION_RETENTION_DAYS', '14', 'User')

Agent data home (multi-harness isolation)

Memory persistence hooks (session summaries, learned skills, session aliases, metrics) store data under a single agent data root. By default that root is ~/.claude. When you use ECC in both Claude Code and Cursor on the same machine, set a separate root for Cursor so the two environments do not overwrite each other's session files:

# Cursor-only boundary (Claude Code keeps the default ~/.claude)
export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc"

Paths resolved under that root include:

• $ECC_AGENT_DATA_HOME/session-data/ — session summaries
• $ECC_AGENT_DATA_HOME/skills/learned/ — learned skills from evaluate-session
• $ECC_AGENT_DATA_HOME/session-aliases.json — session aliases
• $ECC_AGENT_DATA_HOME/metrics/ — cost and activity metrics

See affaan-m/ECC#2065.

Common Workflows

Slash forms below are shown where they remain part of the maintained command surface. Retired short-name shims such as /tdd and /eval live in legacy-command-shims/ for explicit opt-in only.

Starting a new feature:

/ecc:plan "Add user authentication with OAuth"
                                              → planner creates implementation blueprint
tdd-workflow skill                            → tdd-guide enforces write-tests-first
/code-review                                  → code-reviewer checks your work

Fixing a bug:

tdd-workflow skill                            → tdd-guide: write a failing test that reproduces it
                                              → implement the fix, verify test passes
/code-review                                  → code-reviewer: catch regressions

Preparing for production:

/security-scan                                → security-reviewer: OWASP Top 10 audit
e2e-testing skill                             → e2e-runner: critical user flow tests
/test-coverage                                → verify 80%+ coverage