ECC Installation: All Targets, Profiles, and Modules

ECC uses a manifest-driven installer that resolves exactly which files to write for your chosen harness and profile, then records everything in a local state store. That state record is what makes upgrades, repairs, and clean uninstalls reliable — ECC only touches files it installed.

Requirements

Node.js 18 or later — all ECC scripts, hooks, and the installer itself run on Node.js. Earlier versions are not supported.
A supported AI coding harness — see the targets table below.
Claude Code v2.1.0 or later — required when targeting claude. Earlier Claude Code builds handle plugin hooks differently and produce duplicate-detection errors.

Check your Node version before proceeding:

node --version  # must print v18.0.0 or higher

Supported Targets

ECC’s installer accepts a --target flag that controls which harness-specific adapter files are written. All 14 targets share the same skill library and agent definitions; only platform configs, hook adapters, and directory layouts differ.

Target ID	Harness
`claude`	Claude Code CLI (primary target)
`claude-project`	Claude.ai project-level install
`cursor`	Cursor IDE
`antigravity`	Antigravity IDE
`codex`	OpenAI Codex app and CLI
`gemini`	Gemini CLI
`opencode`	OpenCode
`codebuddy`	CodeBuddy
`joycode`	JoyCode
`qwen`	Qwen CLI
`zed`	Zed editor
`hermes`	Hermes operator surface
`openclaw`	OpenClaw
`kimi`	Kimi

Three Install Paths

Choose exactly one. Layering methods (for example, plugin install followed by --profile full) creates duplicate skills and duplicate hook execution. If you already have a layered setup, see Uninstall before reinstalling.

macOS / Linux
Windows (PowerShell)

Path 1 — npx (recommended, no global install)

npx ecc install --profile minimal --target claude

npx downloads ecc-universal from npm and runs it once. Nothing is left in your global Node environment.

Path 2 — npm global

npm install -g ecc-universal
ecc install --profile minimal --target claude

Installs the ecc binary globally so you can invoke it from any directory without npx.

Path 3 — git clone

git clone https://github.com/affaan-m/ECC.git
cd ECC
npm install
./install.sh --profile minimal --target claude

Use this path when you want the full source tree (for rules, examples, and direct script access) or when your network cannot reach npm during install.

Path 1 — npx

npx ecc install --profile minimal --target claude

Path 2 — npm global

npm install -g ecc-universal
ecc install --profile minimal --target claude

Path 3 — git clone + PowerShell installer

git clone https://github.com/affaan-m/ECC.git
cd ECC
npm install
.\install.ps1 --profile minimal --target claude

On Windows, the Claude config directory is %USERPROFILE%\.claude, not ~/.claude. ECC’s Node-based scripts and install.ps1 resolve this automatically. If you are copying rule directories manually, use $HOME\.claude\rules\ecc\ in PowerShell or %USERPROFILE%\.claude\rules\ecc\ in CMD.

Install Profiles

Profiles are named module bundles. Pass the profile name with --profile to control what gets installed.

minimal — rules, agents, commands, platform configs, quality skills (no hooks)

Best for: Low-context setups, users who want ECC’s rule and skill layer without runtime hook enforcement.Modules: rules-core, agents-core, commands-core, platform-configs, workflow-qualityThe minimal profile intentionally excludes hooks-runtime. You get full rules, all 67 agents, the core command library, platform configurations for your target harness, and the complete quality/TDD/verification skill pack — but hooks do not run automatically. Add hooks later with --modules hooks-runtime when you want runtime enforcement.

npx ecc install --profile minimal --target claude

opencode — commands, platform configs, quality skills (OpenCode default)

Best for: OpenCode users who want the standard command surface without hooks.Modules: commands-core, platform-configs, workflow-qualityThe opencode profile is the recommended starting point for OpenCode. It excludes both rules-core (OpenCode uses its own instruction format) and hooks-runtime — opt in with --modules hooks-runtime when ready.

npx ecc install --profile opencode --target opencode

core — minimal + hooks-runtime

Best for: Users who want the standard harness baseline with automatic hook enforcement.Modules: rules-core, agents-core, commands-core, hooks-runtime, platform-configs, workflow-qualityAdds the hook runtime on top of minimal. Hooks fire on tool events — auto-formatting after file edits, TypeScript type-checking, console.log detection, dev-server tmux reminders, session persistence on Stop, and more. To install core without hooks on a specific baseline:

npx ecc install --profile core --without baseline:hooks --target claude

npx ecc install --profile core --target claude

developer — core + framework/language, database, orchestration

Best for: Day-to-day app engineering across multiple frameworks and languages.Modules: rules-core, agents-core, commands-core, hooks-runtime, platform-configs, workflow-quality, framework-language, database, orchestrationThe developer profile is the recommended default for most ECC users working on app codebases. It adds the full framework and language skill pack (React, Next.js, Django, Laravel, Spring Boot, Quarkus, NestJS, Go, Rust, Kotlin, Swift, C++, Dart/Flutter, .NET, and more), database skills (PostgreSQL, MySQL, ClickHouse, Prisma, JPA), and the worktree/tmux orchestration runtime.

npx ecc install --profile developer --target claude

security — core + security skills

Best for: Security-focused workflows, audits, compliance checks, and AgentShield integration.Modules: rules-core, agents-core, commands-core, hooks-runtime, platform-configs, workflow-quality, securityAdds the full security module: security-review, security-scan (AgentShield), security-bounty-hunter, hipaa-compliance, healthcare-phi-compliance, framework-specific security skills (Django, Laravel, Spring Boot, Quarkus), DeFi/AMM security, LLM trading agent security, and the complete Security Guide.

npx ecc install --profile security --target claude

research — core + research APIs, business content, social distribution

Best for: Research, synthesis, writing, and publishing workflows.Modules: rules-core, agents-core, commands-core, hooks-runtime, platform-configs, workflow-quality, research-apis, business-content, social-distributionAdds deep-research and scientific database skills (pubmed, uspto, gget, literature review, scholar evaluation), business content skills (article writing, brand voice, market research, investor materials, SEO), and social distribution (X/Twitter API, crosspost).

npx ecc install --profile research --target claude

full — all currently classified modules

Best for: Power users who want the entire ECC surface installed at once.Modules: All modules — rules-core, agents-core, commands-core, hooks-runtime, platform-configs, framework-language, database, workflow-quality, security, research-apis, business-content, operator-workflows, optimization-workflows, prediction-market-skills, social-distribution, media-generation, orchestration, swift-apple, agentic-patterns, devops-infra, machine-learning, supply-chain-domain, document-processing

npx ecc install --profile full --target claude

Do not run --profile full after a plugin install. The plugin already loads ECC skills, commands, and hooks. Running the full installer afterward copies those surfaces again and creates duplicates plus duplicate runtime behavior. Use --profile full only when doing a fully manual install instead of the plugin path.

Selective Module Install

Instead of a profile, you can name specific modules directly with --modules. This is useful for adding a single capability on top of an existing install:

# Add only the hooks runtime to an existing minimal install
npx ecc install --target claude --modules hooks-runtime

# Add security and research modules together
npx ecc install --target claude --modules security,research-apis

# Add the full agentic patterns module
npx ecc install --target claude --modules agentic-patterns

Available module IDs (from manifests/install-modules.json): rules-core · agents-core · commands-core · hooks-runtime · platform-configs · framework-language · database · workflow-quality · security · research-apis · business-content · operator-workflows · optimization-workflows · prediction-market-skills · social-distribution · media-generation · orchestration · swift-apple · agentic-patterns · devops-infra · machine-learning · supply-chain-domain · document-processing

Include and Exclude Syntax

The installer supports capability-tagged --with and --without flags for fine-grained selection within a profile:

# Add machine-learning capability on top of a minimal profile
npx ecc install --profile minimal --target claude --with capability:machine-learning

# Install core but exclude the hooks baseline
npx ecc install --profile core --target claude --without baseline:hooks

# Exclude a specific language pack
npx ecc install --profile developer --target claude --without lang:perl

Include/exclude tags follow the pattern (baseline|lang|framework|capability):<name>.

Preview Before Installing

Use --dry-run on any install command to see exactly what files would be written without touching the filesystem:

npx ecc install --profile developer --target claude --dry-run

Use the plan command for a structured view of the resolved install plan:

npx ecc plan --profile developer --target claude

Verify, Repair, and Diagnose

# List all files ECC installed for the current context
npx ecc list-installed

# Show install state and readiness summary
npx ecc status

# Diagnose missing or drifted ECC-managed files
npx ecc doctor

# Restore drifted or missing files without reinstalling
npx ecc repair

Upgrade

Pull the latest ECC changes and reinstall all currently managed targets:

npx ecc auto-update

Preview the upgrade first:

npx ecc auto-update --dry-run

Uninstall

ECC only removes files it recorded in its install state — it will never delete unrelated files.

# Preview removal without deleting anything
npx ecc uninstall --dry-run

# Remove all ECC-managed files
npx ecc uninstall

# Remove files for a specific target only
npx ecc uninstall --target cursor --dry-run
npx ecc uninstall --target cursor

If you layered multiple install methods, clean up in order:

Remove the Claude Code plugin install (/plugin remove ecc@ecc in Claude Code).
Run npx ecc uninstall to remove install-state-managed files.
Delete any rule folders you copied manually under ~/.claude/rules/ecc/.
Reinstall once, using a single path.

Hook Runtime Controls

After installing a profile that includes hooks-runtime, tune hook behavior with environment variables without editing hook files:

# Hook strictness profile: minimal | standard | strict (default: standard)
export ECC_HOOK_PROFILE=standard

# Disable specific hooks by ID (comma-separated)
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

# Cap SessionStart context injection (default: 8000 chars)
export ECC_SESSION_START_MAX_CHARS=4000

# Disable SessionStart context entirely (useful for local/low-context models)
export ECC_SESSION_START_CONTEXT=off

# Session-tmp retention window in days (default: 30); set to 0 or "never" to keep all
export ECC_SESSION_RETENTION_DAYS=14

# Cap how many learned instincts are injected at SessionStart (default: 6)
export ECC_MAX_INJECTED_INSTINCTS=6

# Minimum confidence for instinct injection, 0–1 (default: 0.7)
export ECC_INSTINCT_CONFIDENCE_THRESHOLD=0.7

macOS / Linux
Windows (PowerShell)

Add these to your shell profile (~/.zshrc, ~/.bashrc, etc.) to make them persistent:

export ECC_HOOK_PROFILE=standard
export ECC_SESSION_START_MAX_CHARS=4000

Set environment variables persistently at the user level:

[Environment]::SetEnvironmentVariable('ECC_HOOK_PROFILE', 'standard', 'User')
[Environment]::SetEnvironmentVariable('ECC_SESSION_START_MAX_CHARS', '4000', 'User')
[Environment]::SetEnvironmentVariable('ECC_SESSION_RETENTION_DAYS', '14', 'User')
[Environment]::SetEnvironmentVariable('ECC_CONTEXT_MONITOR_COST_WARNINGS', 'off', 'User')

Multi-Harness Isolation

When running ECC in both Claude Code and Cursor on the same machine, set a separate agent data root for Cursor to prevent session files from overwriting each other:

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

Paths resolved under that root:

Path	Purpose
`$ECC_AGENT_DATA_HOME/session-data/`	Session summaries
`$ECC_AGENT_DATA_HOME/skills/learned/`	Skills learned from `evaluate-session`
`$ECC_AGENT_DATA_HOME/session-aliases.json`	Session aliases
`$ECC_AGENT_DATA_HOME/metrics/`	Cost and activity metrics

Getting Started

Core Concepts

Using ECC

Security

ECC Installation: All Targets, Profiles, and Modules

Requirements

Supported Targets

Three Install Paths

Path 1 — npx (recommended, no global install)

Path 2 — npm global

Path 3 — git clone

Path 1 — npx

Path 2 — npm global

Path 3 — git clone + PowerShell installer

Install Profiles

Selective Module Install

Include and Exclude Syntax

Preview Before Installing

Verify, Repair, and Diagnose

Upgrade

Uninstall

Hook Runtime Controls

Multi-Harness Isolation

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Using ECC

Security

Documentation Index

​Requirements

​Supported Targets

​Three Install Paths

​Path 1 — npx (recommended, no global install)

​Path 2 — npm global

​Path 3 — git clone

​Path 1 — npx

​Path 2 — npm global

​Path 3 — git clone + PowerShell installer

​Install Profiles

​Selective Module Install

​Include and Exclude Syntax

​Preview Before Installing

​Verify, Repair, and Diagnose

​Upgrade

​Uninstall

​Hook Runtime Controls

​Multi-Harness Isolation

Build docs developers (and LLMs) love

Requirements

Supported Targets

Three Install Paths

Path 1 — npx (recommended, no global install)

Path 2 — npm global

Path 3 — git clone

Path 1 — npx

Path 2 — npm global

Path 3 — git clone + PowerShell installer

Install Profiles

Selective Module Install

Include and Exclude Syntax

Preview Before Installing

Verify, Repair, and Diagnose

Upgrade

Uninstall

Hook Runtime Controls

Multi-Harness Isolation