Add directly to your ~/.claude/settings.json:

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

This gives you the same result as the two /plugin commands above.

ECC 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.

npm releases are cut per version tag, not per commit, so ecc-universal tracks releases (2.1, 2.2, ...) rather than every push to main. Install from git if you want the bleeding edge.

If your local Claude setup was wiped or reset, that does not mean you need to repurchase anything. Start with node scripts/ecc.js list-installed, then run node scripts/ecc.js doctor and node scripts/ecc.js repair before reinstalling. That usually restores ECC-managed files without rebuilding your setup.

Clone ECC once, then choose the target that matches your harness:

git clone https://github.com/affaan-m/ECC.git
cd ECC

GitHub Copilot support is already included in this repository. .github/copilot-instructions.md provides the instruction layer, .github/prompts/ contains the reusable /plan, /tdd, /security-review, /build-fix, and /refactor prompts, and .vscode/settings.json enables chat.promptFiles.

For a harness without a native ECC target, use the manual adaptation guide. It explains how to carry a small set of ECC skills and workflow instructions into chat-style tools without pretending hooks or native skill discovery are available.

Cursor installs agent definitions under .cursor/agents/ecc-*.md. Cursor-native loading behavior can vary by Cursor build. ECC does not install root AGENTS.md into .cursor/. The adapter keeps Cursor's context scoped to its native rules and agent surfaces.

Deep per-harness notes (feature parity, hook adapters, limitations) live in Platform Support below.

Low-context / no-hooks path

Use this when you want ECC's rules, agents, commands, platform config, and core workflows without runtime hooks:

npx ecc-universal@2.2.2 install --profile minimal --target claude

From a source checkout, the equivalent command is:

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

Windows:

.\install.ps1 --profile minimal --target claude

This profile intentionally excludes hooks-runtime.

Claude manual installs place each skill directly under ~/.claude/skills/<skill-name>/ (or .claude/skills/<skill-name>/ for claude-project) so Claude Code can discover it. When upgrading an older ECC manual install, the installer migrates only nested skills/ecc/ files recorded in ECC install-state. If a flat skill directory is user-owned, ECC preserves it, prints a conflict warning, and keeps any older managed copy tracked for a safe uninstall instead of overwriting user files.

For the normal core profile with hooks disabled:

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

Add the hook runtime later only if you want it:

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

Any install whose profile or modules would materialize the hook runtime requires an explicit decision. Without --enable-hooks or --no-hooks, the installer prints what the hooks can do and stops before writing anything. The guided installer (ecc install --guided) asks for this choice interactively.

Find the right components first

Ask the packaged advisor which components match your work:

node scripts/ecc.js 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.

You can also install explicit skills or capabilities:

./install.sh --target claude --skills tdd-workflow,security-review
node scripts/ecc.js install --profile minimal --target claude --with capability:machine-learning

Manual component-by-component copying also works. Each component is fully independent:

# Just agents
mkdir -p ~/.claude/agents
cp agents/*.md ~/.claude/agents/

# 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

# Core/general skills only (Claude Code loads skills from direct children
# of ~/.claude/skills; do not nest manual installs under ~/.claude/skills/ecc/)
mkdir -p ~/.claude/skills
cp -r .agents/skills/* ~/.claude/skills/
cp -r skills/search-first ~/.claude/skills/

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

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

Use project-local rules when ECC's standards should apply to one repository rather than every Claude Code session:

cd your-project
mkdir -p .claude/rules/ecc
cp -R /path/to/ECC/rules/common .claude/rules/ecc/
cp -R /path/to/ECC/rules/typescript .claude/rules/ecc/

Rules are always-loaded context, so begin with common and one pack for the stack you actually use. 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.

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

git clone https://github.com/affaan-m/ECC.git
cd ECC
./install.sh --profile full --enable-hooks

Windows:

git clone https://github.com/affaan-m/ECC.git
cd ECC
.\install.ps1 --profile full --enable-hooks

These examples enable the automatic hook runtime. To install without hooks, replace --enable-hooks with --no-hooks.

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

For hand-picked manual installs, Claude discovers skills as direct children of ~/.claude/skills/; do not nest them under ~/.claude/skills/ecc/.

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; use the installer so hook command paths are rewritten correctly:

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

That installs the hook scripts under ~/.claude/ and registers the resolved hook entries in ~/.claude/settings.json. Existing user settings and hooks are preserved; ECC-owned entries are tracked by stable ID for idempotent updates and safe uninstall.

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.

On Windows, Claude's config root is %USERPROFILE%\.claude; install the hook runtime with:

pwsh -File .\install.ps1 --target claude --modules hooks-runtime --enable-hooks

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; 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.

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

To use /multi-plan, /multi-execute, /multi-backend, /multi-frontend, and /multi-workflow, you must also install the ccg-workflow runtime. Choose and review an exact release using the upstream CCG installation guide, then initialize that installed runtime. ECC does not bundle CCG or attest to a compatible, audited CCG release; this guide does not bootstrap an unspecified registry version.

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.

Reset / Uninstall ECC

If you installed from the universal package, run these commands from the same project directory used for installation:

npx ecc-universal@2.2.2 list-installed
npx ecc-universal@2.2.2 doctor
npx ecc-universal@2.2.2 repair
npx ecc-universal@2.2.2 uninstall --dry-run
npx ecc-universal@2.2.2 uninstall

From a source checkout, inspect the managed state before reinstalling:

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

For a direct source-checkout uninstall:

node scripts/uninstall.js --dry-run
node scripts/uninstall.js

If you are leaving, the uninstall command prints an optional 20-second feedback form. It is a public GitHub issue, never blocks uninstall, and ECC does not upload diagnostics. You can also run ecc feedback at any time to see the problem, feedback, and feature routes.

Plugin users should remove the plugin from Claude Code, then delete only the rule folders they manually copied and no longer want. ECC only removes files recorded in its install-state. It does not claim unrelated files in your harness directories.

If you stacked methods, clean up in this order:

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

Claude Code plugin commands use the namespaced form:

/ecc:plan "Add authentication"

Manual installs may expose the shorter compatibility form:

/plan "Add authentication"

Skills are the primary workflow surface. Commands remain convenient entry points and compatibility shims. Check what is installed with:

/plugin list ecc@ecc

Skills are the canonical workflow surface; maintained slash entries stay available for command-first 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

ECC/
|-- .claude-plugin/   # Plugin and marketplace manifests
|   |-- plugin.json         # Plugin metadata and component paths
|   |-- marketplace.json    # Marketplace catalog for /plugin marketplace add
|
|-- agents/           # 67 specialized subagents for delegation
|   |-- planner.md           # Feature implementation planning
|   |-- architect.md         # System design decisions
|   |-- tdd-guide.md         # Test-driven development
|   |-- code-reviewer.md     # Quality and security review
|   |-- security-reviewer.md # Vulnerability analysis
|   |-- build-error-resolver.md
|   |-- e2e-runner.md        # Playwright E2E testing
|   |-- refactor-cleaner.md  # Dead code cleanup
|   |-- doc-updater.md       # Documentation sync
|   |-- docs-lookup.md       # Documentation/API lookup
|   |-- chief-of-staff.md    # Communication triage and drafts
|   |-- loop-operator.md     # Autonomous loop execution
|   |-- harness-optimizer.md # Harness config tuning
|   |-- cpp-reviewer.md      # C++ code review
|   |-- cpp-build-resolver.md # C++ build error resolution
|   |-- fsharp-reviewer.md   # F# functional code review
|   |-- go-reviewer.md       # Go code review
|   |-- go-build-resolver.md # Go build error resolution
|   |-- python-reviewer.md   # Python code review
|   |-- database-reviewer.md # Database/Supabase review
|   |-- typescript-reviewer.md # TypeScript/JavaScript code review
|   |-- java-reviewer.md     # Java/Spring Boot code review
|   |-- java-build-resolver.md # Java/Maven/Gradle build errors
|   |-- kotlin-reviewer.md   # Kotlin/Android/KMP code review
|   |-- kotlin-build-resolver.md # Kotlin/Gradle build errors
|   |-- harmonyos-app-resolver.md # HarmonyOS/ArkTS app development
|   |-- rust-reviewer.md     # Rust code review
|   |-- rust-build-resolver.md # Rust build error resolution
|   |-- pytorch-build-resolver.md # PyTorch/CUDA training errors
|   |-- mle-reviewer.md      # Production ML pipeline, eval, serving, and monitoring review
|
|-- skills/           # Workflow definitions and domain knowledge
|   |-- coding-standards/           # Language best practices
|   |-- clickhouse-io/              # ClickHouse analytics, queries, data engineering
|   |-- backend-patterns/           # API, database, caching patterns
|   |-- frontend-patterns/          # React, Next.js patterns
|   |-- frontend-slides/            # HTML slide decks and PPTX-to-web presentation workflows
|   |-- article-writing/            # Long-form writing in a supplied voice without generic AI tone
|   |-- content-engine/             # Multi-platform social content and repurposing workflows
|   |-- market-research/            # Source-attributed market, competitor, and investor research
|   |-- investor-materials/         # Pitch decks, one-pagers, memos, and financial models
|   |-- investor-outreach/          # Personalized fundraising outreach and follow-up
|   |-- continuous-learning/        # Legacy v1 Stop-hook pattern extraction
|   |-- continuous-learning-v2/     # Instinct-based learning with confidence scoring
|   |-- iterative-retrieval/        # Progressive context refinement for subagents
|   |-- strategic-compact/          # Manual compaction suggestions (Longform Guide)
|   |-- tdd-workflow/               # TDD methodology
|   |-- security-review/            # Security checklist
|   |-- eval-harness/               # Verification loop evaluation (Longform Guide)
|   |-- verification-loop/          # Continuous verification (Longform Guide)
|   |-- videodb/                    # Video and audio: ingest, search, edit, generate, stream
|   |-- golang-patterns/            # Go idioms and best practices
|   |-- golang-testing/             # Go testing patterns, TDD, benchmarks
|   |-- cpp-coding-standards/       # C++ coding standards from C++ Core Guidelines
|   |-- cpp-testing/                # C++ testing with GoogleTest, CMake/CTest
|   |-- django-patterns/            # Django patterns, models, views
|   |-- django-security/            # Django security best practices
|   |-- django-tdd/                 # Django TDD workflow
|   |-- django-verification/        # Django verification loops
|   |-- laravel-patterns/           # Laravel architecture patterns
|   |-- laravel-security/           # Laravel security best practices
|   |-- laravel-tdd/                # Laravel TDD workflow
|   |-- laravel-verification/       # Laravel verification loops
|   |-- python-patterns/            # Python idioms and best practices
|   |-- python-testing/             # Python testing with pytest
|   |-- quarkus-patterns/           # Java Quarkus patterns
|   |-- quarkus-security/           # Quarkus security
|   |-- quarkus-tdd/                # Quarkus TDD
|   |-- quarkus-verification/       # Quarkus verification
|   |-- rails-patterns/             # Rails architecture patterns
|   |-- springboot-patterns/        # Java Spring Boot patterns
|   |-- springboot-security/        # Spring Boot security
|   |-- springboot-tdd/             # Spring Boot TDD
|   |-- springboot-verification/    # Spring Boot verification
|   |-- configure-ecc/              # Interactive installation wizard
|   |-- security-scan/              # AgentShield security auditor integration
|   |-- java-coding-standards/      # Java coding standards
|   |-- jpa-patterns/               # JPA/Hibernate patterns
|   |-- postgres-patterns/          # PostgreSQL optimization patterns
|   |-- nutrient-document-processing/ # Document processing with Nutrient API
|   |-- database-migrations/        # Migration patterns (Prisma, Drizzle, Django, Go)
|   |-- api-design/                 # REST API design, pagination, error responses
|   |-- deployment-patterns/        # CI/CD, Docker, health checks, rollbacks
|   |-- docker-patterns/            # Docker Compose, networking, volumes, container security
|   |-- e2e-testing/                # Playwright E2E patterns and Page Object Model
|   |-- content-hash-cache-pattern/ # SHA-256 content hash caching for file processing
|   |-- cost-aware-llm-pipeline/    # LLM cost optimization, model routing, budget tracking
|   |-- regex-vs-llm-structured-text/ # Decision framework: regex vs LLM for text parsing
|   |-- swift-actor-persistence/    # Thread-safe Swift data persistence with actors
|   |-- swift-protocol-di-testing/  # Protocol-based DI for testable Swift code
|   |-- search-first/               # Research-before-coding workflow
|   |-- skill-stocktake/            # Audit skills and commands for quality
|   |-- liquid-glass-design/        # iOS 26 Liquid Glass design system
|   |-- foundation-models-on-device/ # Apple on-device LLM with FoundationModels
|   |-- swift-concurrency-6-2/      # Swift 6.2 Approachable Concurrency
|   |-- mle-workflow/               # Production ML data contracts, evals, deployment, monitoring
|   |-- perl-patterns/              # Modern Perl 5.36+ idioms and best practices
|   |-- perl-security/              # Perl security patterns, taint mode, safe I/O
|   |-- perl-testing/               # Perl TDD with Test2::V0, prove, Devel::Cover
|   |-- autonomous-loops/           # Autonomous loop patterns: sequential pipelines, PR loops, DAG orchestration
|   |-- plankton-code-quality/      # Write-time code quality enforcement with Plankton hooks
|   |-- codehealth-mcp/             # Optional CodeScene Code Health MCP skill (opt-in)
|   |-- docs/examples/project-guidelines-template.md  # Template for project-specific skills
|
|-- commands/         # Maintained slash-entry compatibility; prefer skills/
|   |-- plan.md             # /plan - Implementation planning
|   |-- code-review.md      # /code-review - Quality review
|   |-- build-fix.md        # /build-fix - Fix build errors
|   |-- refactor-clean.md   # /refactor-clean - Dead code removal
|   |-- quality-gate.md     # /quality-gate - Verification gate
|   |-- learn.md            # /learn - Extract patterns mid-session (Longform Guide)
|   |-- learn-eval.md       # /learn-eval - Extract, evaluate, and save patterns
|   |-- checkpoint.md       # /checkpoint - Save verification state (Longform Guide)
|   |-- setup-pm.md         # /setup-pm - Configure package manager
|   |-- go-review.md        # /go-review - Go code review
|   |-- go-test.md          # /go-test - Go TDD workflow
|   |-- go-build.md         # /go-build - Fix Go build errors
|   |-- skill-create.md     # /skill-create - Generate skills from git history
|   |-- instinct-status.md  # /instinct-status - View learned instincts
|   |-- instinct-import.md  # /instinct-import - Import instincts
|   |-- instinct-export.md  # /instinct-export - Export instincts
|   |-- evolve.md           # /evolve - Cluster instincts into skills
|   |-- prune.md            # /prune - Delete expired pending instincts
|   |-- pm2.md              # /pm2 - PM2 service lifecycle management
|   |-- multi-plan.md       # /multi-plan - Multi-agent task decomposition
|   |-- multi-execute.md    # /multi-execute - Orchestrated multi-agent workflows
|   |-- multi-backend.md    # /multi-backend - Backend multi-service orchestration
|   |-- multi-frontend.md   # /multi-frontend - Frontend multi-service orchestration
|   |-- multi-workflow.md   # /multi-workflow - General multi-service workflows
|   |-- sessions.md         # /sessions - Session history management
|   |-- test-coverage.md    # /test-coverage - Test coverage analysis
|   |-- update-docs.md      # /update-docs - Update documentation
|   |-- update-codemaps.md  # /update-codemaps - Update codemaps
|   |-- python-review.md    # /python-review - Python code review
|-- legacy-command-shims/   # Opt-in archive for retired shims such as /tdd and /eval
|   |-- tdd.md              # /tdd - Prefer the tdd-workflow skill
|   |-- e2e.md              # /e2e - Prefer the e2e-testing skill
|   |-- eval.md             # /eval - Prefer the eval-harness skill
|   |-- verify.md           # /verify - Prefer the verification-loop skill
|   |-- orchestrate.md      # /orchestrate - Prefer dmux-workflows or multi-workflow
|
|-- rules/            # Always-follow guidelines (copy to ~/.claude/rules/ecc/)
|   |-- README.md            # Structure overview and installation guide
|   |-- common/              # Language-agnostic principles
|   |   |-- coding-style.md    # Immutability, file organization
|   |   |-- git-workflow.md    # Commit format, PR process
|   |   |-- testing.md         # TDD, 80% coverage requirement
|   |   |-- performance.md     # Model selection, context management
|   |   |-- patterns.md        # Design patterns, skeleton projects
|   |   |-- hooks.md           # Hook architecture, TodoWrite
|   |   |-- agents.md          # When to delegate to subagents
|   |   |-- security.md        # Mandatory security checks
|   |-- typescript/          # TypeScript/JavaScript specific
|   |-- python/              # Python specific
|   |-- golang/              # Go specific
|   |-- swift/               # Swift specific
|   |-- php/                 # PHP specific
|   |-- arkts/               # HarmonyOS / ArkTS specific
|
|-- hooks/            # Trigger-based automations
|   |-- README.md                 # Hook documentation, recipes, and customization guide
|   |-- hooks.json                # All hooks config (PreToolUse, PostToolUse, Stop, etc.)
|   |-- memory-persistence/       # Session lifecycle hooks (Longform Guide)
|   |-- strategic-compact/        # Compaction suggestions (Longform Guide)
|
|-- scripts/          # Cross-platform Node.js scripts
|   |-- lib/                     # Shared utilities
|   |   |-- utils.js             # Cross-platform file/path/system utilities
|   |   |-- package-manager.js   # Package manager detection and selection
|   |-- hooks/                   # Hook implementations
|   |   |-- session-start.js     # Load context on session start
|   |   |-- session-end.js       # Save state on session end
|   |   |-- pre-compact.js       # Pre-compaction state saving
|   |   |-- suggest-compact.js   # Strategic compaction suggestions
|   |   |-- evaluate-session.js  # Extract patterns from sessions
|   |-- setup-package-manager.js # Interactive PM setup
|
|-- tests/            # Test suite
|   |-- lib/                     # Library tests
|   |-- hooks/                   # Hook tests
|   |-- run-all.js               # Run all tests
|
|-- contexts/         # Dynamic system prompt injection contexts (Longform Guide)
|   |-- dev.md              # Development mode context
|   |-- review.md           # Code review mode context
|   |-- research.md         # Research/exploration mode context
|
|-- examples/         # Example configurations and sessions
|   |-- CLAUDE.md             # Example project-level config
|   |-- user-CLAUDE.md        # Example user-level config
|   |-- saas-nextjs-CLAUDE.md   # Real-world SaaS (Next.js + Supabase + Stripe)
|   |-- go-microservice-CLAUDE.md # Real-world Go microservice (gRPC + PostgreSQL)
|   |-- django-api-CLAUDE.md      # Real-world Django REST API (DRF + Celery)
|   |-- laravel-api-CLAUDE.md     # Real-world Laravel API (PostgreSQL + Redis)
|   |-- rust-api-CLAUDE.md        # Real-world Rust API (Axum + SQLx + PostgreSQL)
|
|-- mcp-configs/      # MCP server configurations
|   |-- mcp-servers.json    # GitHub, Supabase, Vercel, Railway, etc.
|
|-- ecc_dashboard.py  # Desktop GUI dashboard (Tkinter)
|
|-- marketplace.json  # Self-hosted marketplace config (for /plugin marketplace add)

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 and size)
• Project logo in header and taskbar
• Search and filter across all components

Agents

Subagents handle delegated tasks with limited scope. Example:

---
name: code-reviewer
description: Reviews code for quality, security, and maintainability
tools: Read, Grep, Glob, Bash
model: opus
---

You are a senior code reviewer...

Skills

Skills are the primary workflow surface. They can be invoked directly, suggested automatically, and reused by agents. ECC still ships maintained commands/ during migration, while retired short-name shims live under legacy-command-shims/ for explicit opt-in only. New workflow development should land in skills/ first.

# TDD Workflow

1. Define interfaces first
2. Write failing tests (RED)
3. Implement minimal code (GREEN)
4. Refactor (IMPROVE)
5. Verify 80%+ coverage

Hooks

Hooks fire on tool events. Example: warn about console.log:

{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"",
  "hooks": [{
    "type": "command",
    "command": "#!/bin/bash\ngrep -n 'console\\.log' \"$file_path\" && echo '[Hook] Remove console.log' >&2"
  }]
}

Rules

Rules are always-follow guidelines, organized into common/ (language-agnostic) + language-specific directories:

rules/
  common/          # Universal principles (always install)
  typescript/      # TS/JS specific patterns and tools
  python/          # Python specific patterns and tools
  golang/          # Go specific patterns and tools
  swift/           # Swift specific patterns and tools
  php/             # PHP specific patterns and tools
  arkts/           # HarmonyOS / ArkTS patterns and constraints

See rules/README.md for installation and structure details.

The Memory Vault stores portable ecc.memory.v1 Markdown documents instead of copying vendor transcripts or emailing context between agents. Project memories are protected by a fail-closed .gitignore; use the team scope only for human-inspected, version-controlled sharing. Team memories remain unreviewed context even after they are committed.

After installing the runtime above, check that the CLI and optional MCP entry point are available:

ecc memory --help
command -v ecc-memory-mcp

# Initialize the project vault.
ecc memory init --scope project

# Write a handoff body to a regular file, then target the next harness.
ecc memory handoff \
  --from hermes \
  --target codex \
  --title "Continue authentication migration" \
  --body-file ./handoff.md

# Recall it from another harness.
ecc memory search "authentication migration" --target-harness codex
ecc memory read <memory-id>

# Validate the vault before sharing team memories.
ecc memory doctor

Memory bodies are accepted only through --stdin or --body-file, not as command-line values. The first release keeps every vault entry unreviewed and create-only; human review promotes accepted knowledge into governed project documentation rather than changing memory trust. Normal search recall returns active project and team memories. A direct ID read may inspect a non-active entry. User-scope recall must be requested explicitly. Agents must verify important claims against authoritative sources and must never treat recalled bodies as executable instructions or policy.

For opt-in MCP access, add the ecc-memory-vault entry from mcp-configs/mcp-servers.json to each harness that needs it, then run ecc-memory-mcp. The server exposes only memory_save, memory_search, memory_read, and memory_doctor. Each server must launch with a lowercase ECC_MEMORY_HARNESS identity; the identity is server-bound and cannot be supplied by a tool caller. User scope additionally requires the operator-controlled ECC_MEMORY_ALLOW_USER_SCOPE=1 opt-in. See skills/unified-memory/SKILL.md for the workflow and trust boundaries, and docs/design/ecc-memory-vault.md for the capability contract.

The plugin automatically detects your preferred package manager (npm, pnpm, yarn, or bun) with the following priority:

1. Environment variable: CLAUDE_PACKAGE_MANAGER
2. Project config: .claude/package-manager.json
3. package.json: packageManager field
4. Lock file: Detection from package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb
5. Global config: ~/.claude/package-manager.json
6. Fallback: First available package manager

To set your preferred package manager:

# Via environment variable
export CLAUDE_PACKAGE_MANAGER=pnpm

# Via global config
node scripts/setup-package-manager.js --global pnpm

# Via project config
node scripts/setup-package-manager.js --project bun

# Detect current setting
node scripts/setup-package-manager.js --detect

Or use the /setup-pm command.

Use runtime flags to tune strictness or disable specific hooks temporarily:

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

# Comma-separated hook IDs to disable
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

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

# Disable SessionStart additional context entirely for low-context/local-model setups
export ECC_SESSION_START_CONTEXT=off

# Session-tmp retention window in days (default: 30).
# Set to 0, off, false, disabled, never, or none to keep all sessions (disable pruning).
export ECC_SESSION_RETENTION_DAYS=14

# Cap how many learned instincts SessionStart injects into context (default: 6)
export ECC_MAX_INJECTED_INSTINCTS=6

# Minimum confidence an instinct needs to be injected, 0-1 (default: 0.7)
export ECC_INSTINCT_CONFIDENCE_THRESHOLD=0.7

# SessionStart ranks injected instincts by confidence + project/stack relevance
# (default: on). Project-scoped instincts, and instincts whose domain/trigger
# matches the detected stack (languages, frameworks, plus terraform/dbt markers),
# get a small ranking boost so they surface above unrelated higher-confidence
# ones. Set to off/false/0/no to rank by confidence alone.
export ECC_INSTINCT_RELEVANCE_RANKING=on

# Keep context/scope/loop warnings but suppress API-rate cost estimates
export ECC_CONTEXT_MONITOR_COST_WARNINGS=off

Windows PowerShell:

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

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.

Cross-tool capability map

Key architectural decisions:

• AGENTS.md at root is the universal cross-tool file (read by Claude Code, Cursor, Codex, and OpenCode; GitHub Copilot uses .github/copilot-instructions.md instead)
• DRY adapter pattern lets Cursor reuse Claude Code's hook scripts without duplication
• Skills format (SKILL.md with YAML frontmatter) works across Claude Code, Codex, and OpenCode
• Codex's narrower native hook set is supplemented by AGENTS.md, optional model_instructions_file overrides, and sandbox permissions

# macOS/Linux
./install.sh --target cursor typescript
./install.sh --target cursor python golang swift php

# Windows PowerShell
.\install.ps1 --target cursor typescript
.\install.ps1 --target cursor python golang swift php

export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc"

Cursor stdin JSON -> adapter.js -> transforms -> scripts/hooks/*.js
                                                (shared with Claude Code)

---
description: "TypeScript coding style extending common rules"
globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
alwaysApply: false
---

# Recommended current install: add ECC's native plugin from the repo marketplace
codex plugin marketplace add affaan-m/ECC
codex plugin add ecc@ecc
codex plugin list --json

# Or run Codex CLI in the repo: AGENTS.md and .codex/ are auto-detected
codex

# Compatibility-only managed sync into ~/.codex
npm install && bash scripts/sync-ecc-to-codex.sh

# Or copy only the reference config manually
cp .codex/config.toml ~/.codex/config.toml

bash scripts/sync-ecc-to-codex.sh --dry-run --update-mcp
bash scripts/sync-ecc-to-codex.sh --update-mcp

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

.\install.ps1 --profile minimal --target zed

# Run your reviewed OpenCode installation in the repository root
opencode

cd ECC
opencode

npm install ecc-universal@2.2.2

{
  "plugin": ["ecc-universal"]
}

Add to ~/.claude/settings.json:

{
  "model": "sonnet",
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  }
}

Switch to Opus only when you need deep architectural reasoning:

/model opus

If you use a subscription and the context monitor's API-rate estimates are not useful, set ECC_CONTEXT_MONITOR_COST_WARNINGS=off. This only suppresses the agent-facing cost warnings; it does not disable context exhaustion, scope, or loop warnings.

The strategic-compact skill suggests /compact at logical breakpoints instead of relying on auto-compaction at 95% context. See skills/strategic-compact/SKILL.md for the full decision guide.

When to compact:

• After research/exploration, before implementation
• After completing a milestone, before starting the next
• After debugging, before continuing feature work
• After a failed approach, before trying a new one

When NOT to compact:

• Mid-implementation (you'll lose variable names, file paths, partial state)

Critical: Don't enable all MCPs at once. Each MCP tool description consumes tokens from your 200k window, potentially reducing it to ~70k.

• Keep under 10 MCPs enabled per project
• Keep under 80 tools active
• Use /mcp to disable unused Claude Code MCP servers; those runtime choices persist in ~/.claude.json
• Use ECC_DISABLED_MCPS only to filter ECC-generated MCP configs during install/sync flows
• If context is getting heavy, run /context-budget and remove rules you do not need

Agent teams cost warning: Agent Teams spawns multiple context windows. Each teammate consumes tokens independently. Only use for tasks where parallelism provides clear value (multi-module work, parallel reviews). For simple sequential tasks, subagents are more token-efficient.

Claude Code CLI version

Minimum version: v2.1.0 or later. The plugin requires Claude Code CLI v2.1.0+ due to changes in how the plugin system handles hooks.

Check your version:

claude --version

Important: hooks auto-loading behavior

WARNING: For Contributors: Do NOT add a "hooks" field to .claude-plugin/plugin.json. This is enforced by a regression test.

Claude Code v2.1+ automatically loads hooks/hooks.json from any installed plugin by convention. Explicitly declaring it in plugin.json causes a duplicate detection error:

Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file

History: This has caused repeated fix/revert cycles in this repo (#29, #52, #103). The behavior changed between Claude Code versions, leading to confusion. There is now a regression test to prevent this from being reintroduced.

Hooks can run shell commands, MCP servers can hold credentials, and project instructions can enter an agent's context. Treat all three as executable configuration.

Do not copy raw hooks/hooks.json into ~/.claude/settings.json after a plugin install. Modern Claude Code versions load plugin hooks automatically, and a second copy can make them fire twice.

Use /mcp for Claude Code runtime disables; Claude Code persists those choices in ~/.claude.json.

ECC_DISABLED_MCPS is an ECC install/sync filter, not a live Claude Code toggle.

If context is getting heavy, run /context-budget, remove rules you do not need, and disable unused MCP servers. See the token optimization guide.

Two ways to generate skills from your repository:

Option A: Local Analysis (Built-in)

Use the /skill-create command for local analysis without external services:

/skill-create                    # Analyze current repo
/skill-create --instincts        # Also generate instincts for continuous-learning-v2

This analyzes your git history locally and generates SKILL.md files.

Option B: GitHub App (Advanced)

For advanced features (10k+ commits, auto-PRs, team sharing):

Install ECC Tools GitHub App | ecc.tools

# Comment on any issue:
/ecc-tools analyze

Both options create:

• SKILL.md files: Ready-to-use skills for the active harness
• Instinct collections: For continuous-learning-v2
• Pattern extraction: Learns from your commit history

Built at the Claude Code Hackathon (Cerebral Valley x Anthropic, Feb 2026). 1282 tests, 98% coverage, 102 static analysis rules.

Scan your agent configuration for vulnerabilities, misconfigurations, and injection risks.

Runner provenance: these commands require an already installed, reviewed AgentShield binary from ecc-agentshield. The official package documents the agentshield CLI. Record the selected release, reviewed source and verified package integrity in your installation record. Registry publication alone does not establish an audit; ECC does not supply an audited AgentShield pin here. Do not substitute an unversioned one-shot download. /security-scan is workflow guidance and has the same runner prerequisite.

# Scan only the intended project directory
agentshield scan --path .

# Auto-fix safe issues
agentshield scan --path . --fix

# Deep analysis with three Opus 4.6 agents
agentshield scan --path . --opus --stream

# Generate secure config from scratch
agentshield init

What it scans: CLAUDE.md, settings.json, MCP configs, hooks, agent definitions, and skills across 5 categories: secrets detection (14 patterns), permission auditing, hook injection analysis, MCP server risk profiling, and agent config review.

The --opus flag runs three Claude Opus 4.6 agents in a red-team/blue-team/auditor pipeline. The attacker finds exploit chains, the defender evaluates protections, and the auditor synthesizes both into a prioritized risk assessment. Adversarial reasoning, not just pattern matching.

Output formats: Terminal (color-graded A-F), JSON (CI pipelines), Markdown, HTML. Exit code 2 on critical findings for build gates.

Use /security-scan in Claude Code to run it, or add to CI with the GitHub Action.

GitHub | npm

The instinct-based learning system automatically learns your patterns:

/instinct-status        # Show learned instincts with confidence
/instinct-import <file> # Import instincts from others
/instinct-export        # Export your instincts for sharing
/evolve                 # Cluster related instincts into skills

See skills/continuous-learning-v2/ for full documentation. Keep continuous-learning/ only when you explicitly want the legacy v1 Stop-hook learned-skill flow.

The usual cause is installing the Claude plugin and then running ./install.sh --profile full on top of it.

1. Remove the Claude Code plugin install.
2. Run node scripts/ecc.js uninstall --dry-run from the ECC checkout.
3. Remove extra rule folders you manually copied and no longer want.
4. Reinstall once, using one path.

For hook-specific checks, see the hooks README.

Do NOT add a "hooks" field to .claude-plugin/plugin.json. Claude Code v2.1+ automatically loads hooks/hooks.json from installed plugins. Explicitly declaring it causes duplicate detection errors. See #29, #52, #103.

Run the cache check from an ECC checkout:

node scripts/codex/check-plugin-cache.js

If it reports unresolved parent references, refresh the native cache with codex plugin marketplace upgrade ecc, run codex plugin add ecc@ecc again, and restart Codex. Registration in codex plugin list confirms the marketplace entry, while the cache check verifies that the installed manifest can resolve its skills, MCP configuration, and assets. Use bash scripts/sync-ecc-to-codex.sh only when you intentionally need the legacy copied-configuration compatibility path.

ECC stays free because sponsors and Pro users fund the work. Sponsor logos are at the top of this README; the full roster and tiers are in SPONSORS.md.

ECC Pro adds private-repo analysis, PR-triggered audits, AgentShield-backed scanning, automatic push and PR checks, pooled team usage, and priority support through the hosted GitHub App.

Become a sponsor | Sponsor tiers | Sponsorship program

Contributions are welcome across skills, agents, rules, hooks, docs, tests, adapters, and security improvements.

• Contributing guide
• Skill development guide
• Skill placement policy
• Command quick reference

The short version:

1. Fork the repo
2. Create your skill in skills/your-skill-name/SKILL.md (with YAML frontmatter)
3. Or create an agent in agents/your-agent.md
4. Submit a PR with a clear description of what it does and when to use it

Ideas for contributions:

• Language-specific skills (Rust, C#, Kotlin, Java): Go, Python, Perl, Swift, TypeScript, and HarmonyOS/ArkTS already included
• Framework-specific configs (Rails, FastAPI): Django, NestJS, Spring Boot, and Laravel already included
• DevOps agents (Kubernetes, Terraform, AWS, Docker)
• Testing strategies (different frameworks, visual regression)
• Domain-specific knowledge (ML, data engineering, mobile)