Skip to content
Back to search

ecc

SkillWorks with CodexGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/affaan-m/ECC with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/affaan-m/ECC'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/affaan-m-ecc/badge.svg)](/listings/affaan-m-ecc)

HTML

<a href="/listings/affaan-m-ecc"><img src="/api/listings/affaan-m-ecc/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Use the [guided setup](#install-ecc) or [native plugin commands](#claude-code-details). Both install the same `ecc@ecc` plugin. Choose one and do not stack a full manual Claude install on top.

<div align="center">

<table aria-label="ECC primary links"> <tr> <td width="33%" align="center"> <a href="https://ecc.tools/pricing"> <img src="assets/images/community/ecc-tools-mark.svg" height="42" alt="ECC Tools" /><br /> <strong>ECC Pro + GitHub App</strong> </a><br /> <sub><a href="https://github.com/apps/ecc-tools">Install free</a> · <a href="https://ecc.tools/pricing">Private repos from $19/seat/mo</a></sub> </td> <td width="33%" align="center"> <a href="https://github.com/sponsors/affaan-m"> <img src="assets/images/community/heart.svg" height="42" alt="" /><br /> <strong>Sponsor ECC</strong> </a><br /> <sub>Fund the open-source project</sub> </td> <td width="33%" align="center"> <a href="https://discord.gg/36yGMHGFbR"> <img src="assets/images/community/discord.svg" height="42" alt="Discord" /><br /> <strong>Community</strong> </a><br /> <sub>Discord · Q&amp;A · Show and Tell</sub> </td> </tr> </table>

</div>

<sub>**OSS stays free.** This repo is MIT-licensed forever. ECC Pro is the hosted GitHub App for private repos. <a href="https://github.com/sponsors/affaan-m">Sponsors</a> and <a href="https://ecc.tools/pricing">Pro subscribers</a> fund the work. That's why a single maintainer ships weekly across 7 harnesses.</sub>

<div align="center">

<sub><strong>Partners &amp; sponsors</strong></sub>

<p align="center" aria-label="Partners and sponsors"> <a href="https://www.coderabbit.ai" title="CodeRabbit"><img src="assets/images/sponsors/coderabbit.png" height="54" alt="CodeRabbit" /></a>&nbsp;&nbsp;&nbsp; <a href="https://www.greptile.com/go/ecc" title="Greptile"><img src="assets/images/sponsors/greptile.png" height="54" alt="Greptile" /></a>&nbsp;&nbsp;&nbsp; <a href="https://platform.kimi.ai?aff=ecc" title="Moonshot AI - Kimi"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/images/sponsors/moonshot-dark.png" /><img src="assets/images/sponsors/moonshot.png" width="132" alt="Moonshot AI - Kimi" /></picture></a>&nbsp;&nbsp;&nbsp; <a href="https://compute.itomarkets.com" title="Itô Markets"><picture><source media="(prefers-color-scheme: light)" srcset="assets/images/sponsors/ito-transparent-light.png" /><img src="assets/images/sponsors/ito-transparent.png" width="96" alt="Itô Markets" /></picture></a>&nbsp;&nbsp;&nbsp; <a href="https://serpapi.com/github-ecc" title="SerpApi: Web Search API"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/images/sponsors/serpapi-logo-dark-mode.svg" /><img src="assets/images/sponsors/serpapi-logo-light-mode.svg" width="200" alt="SerpApi: Web Search API" /></picture></a> </p>

<sub><strong>Past sponsors:</strong> <a href="https://www.atlascloud.ai/?utm_source=github&amp;utm_medium=link&amp;utm_campaign=ECC">Atlas Cloud</a> · <a href="https://github.com/mikejmorgan-ai">Mike Morgan (inactive)</a></sub>

<sub><strong>Community sponsors:</strong> <a href="https://github.com/jasonwu513">@jasonwu513</a> · <a href="https://github.com/1anter">@1anter</a> · <a href="https://github.com/massimotodaro">@massimotodaro</a> · <a href="https://github.com/meadmccabe">@meadmccabe</a></sub>

<sub><a href="https://github.com/sponsors/affaan-m"><strong>Become a Sponsor</strong></a> · <a href="SPONSORS.md">Sponsor Tiers</a> · <a href="SPONSORING.md">Sponsorship Program</a></sub>

</div>

<p align="center"><a href="#install-ecc">Jump to install ↓</a></p>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 47 lines
  1. {
  2. "name": "ecc",
  3. "owner": {
  4. "name": "Affaan Mustafa",
  5. "email": "me@affaanmustafa.com"
  6. },
  7. "metadata": {
  8. "description": "Harness-native ECC skills, hooks, rules, MCP conventions, and operator workflows"
  9. },
  10. "plugins": [
  11. {
  12. "name": "ecc",
  13. "source": "./",
  14. "description": "Harness-native ECC operator layer - 72 agents, 327 skills, 98 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready workflows for Claude Code, Codex, OpenCode, Cursor, and related agent harnesses",
  15. "version": "2.2.3",
  16. "author": {
  17. "name": "Affaan Mustafa",
  18. "email": "me@affaanmustafa.com"
  19. },
  20. "homepage": "https://ecc.tools",
  21. "repository": "https://github.com/affaan-m/ECC",
  22. "license": "MIT",
  23. "keywords": [
  24. "agents",
  25. "skills",
  26. "hooks",
  27. "commands",
  28. "tdd",
  29. "code-review",
  30. "security",
  31. "best-practices"
  32. ],
  33. "category": "workflow",
  34. "tags": [
  35. "agents",
  36. "skills",
  37. "hooks",
  38. "commands",
  39. "tdd",
  40. "code-review",
  41. "security",
  42. "best-practices"
  43. ],
  44. "strict": false
  45. }
  46. ]
  47. }
README.md · README · 2,215 lines
  1. <p align="center">
  2. <img src="assets/hero.png" alt="ECC - the agent harness operating system" width="100%" />
  3. </p>
  4. <p align="center">
  5. <a href="https://www.star-history.com/affaan-m/ecc">
  6. <picture>
  7. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=affaan-m/ECC&type=trending&theme=dark" />
  8. <img src="https://api.star-history.com/badge?repo=affaan-m/ECC&type=trending" alt="GitHub Trending Repository of the Day" height="46" />
  9. </picture>
  10. </a>
  11. <a href="https://www.star-history.com/affaan-m/ecc">
  12. <picture>
  13. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=affaan-m/ECC&type=rank&theme=dark" />
  14. <img src="https://api.star-history.com/badge?repo=affaan-m/ECC&type=rank" alt="Star History Global Rank" height="46" />
  15. </picture>
  16. </a>
  17. </p>
  18. <p align="center">
  19. <strong>Language:</strong>
  20. <a href="README.md">English</a> |
  21. <a href="docs/ar/README.md">العربية</a> |
  22. <a href="docs/pt-BR/README.md">Português (Brasil)</a> |
  23. <a href="README.zh-CN.md">简体中文</a> |
  24. <a href="docs/zh-TW/README.md">繁體中文</a> |
  25. <a href="docs/ja-JP/README.md">日本語</a> |
  26. <a href="docs/ko-KR/README.md">한국어</a> |
  27. <a href="docs/tr/README.md">Türkçe</a> |
  28. <a href="docs/ru/README.md">Русский</a> |
  29. <a href="docs/vi-VN/README.md">Tiếng Việt</a> |
  30. <a href="docs/th/README.md">ไทย</a> |
  31. <a href="docs/de-DE/README.md">Deutsch</a> |
  32. <a href="docs/es/README.md">Español</a> |
  33. <a href="docs/uk-UA/README.md">Українська</a> |
  34. <a href="docs/pl/README.md">Polski</a> |
  35. <a href="docs/bn/README.md">বাংলা</a> |
  36. <a href="docs/it-IT/README.md">Italiano</a>
  37. </p>
  38. <p align="center">
  39. <a href="https://discord.gg/36yGMHGFbR"><img src="https://img.shields.io/discord/1496644400590094540?logo=discord&logoColor=white&label=Discord&color=5865F2" alt="Discord" /></a>
  40. <a href="https://ecc.tools"><img src="https://img.shields.io/badge/Website-ecc.tools-E07856?logo=googlechrome&logoColor=white" alt="Website" /></a>
  41. <a href="https://github.com/apps/ecc-tools"><img src="https://img.shields.io/badge/GitHub%20App-ECC%20Tools-181717?logo=github&logoColor=white" alt="GitHub App" /></a>
  42. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license" /></a>
  43. </p>
  44. <p align="center">
  45. <a href="https://github.com/affaan-m/ECC"><img src="https://img.shields.io/github/stars/affaan-m/ECC?style=flat" alt="GitHub stars" /></a>
  46. <a href="https://github.com/affaan-m/ECC/forks"><img src="https://img.shields.io/github/forks/affaan-m/ECC?style=flat" alt="GitHub forks" /></a>
  47. <a href="https://github.com/affaan-m/ECC/graphs/contributors"><img src="https://img.shields.io/github/contributors/affaan-m/ECC?style=flat" alt="Contributors" /></a>
  48. <a href="https://github.com/marketplace/ecc-tools"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Finstalls&logo=github" alt="GitHub App installs" /></a>
  49. </p>
  50. <p align="center">
  51. <a href="https://www.npmjs.com/package/ecc-universal"><img src="https://img.shields.io/npm/dw/ecc-universal?label=ecc-universal&logo=npm" alt="ecc-universal npm downloads" /></a>
  52. <a href="https://www.npmjs.com/package/ecc-agentshield"><img src="https://img.shields.io/npm/dw/ecc-agentshield?label=ecc-agentshield&logo=npm" alt="ecc-agentshield npm downloads" /></a>
  53. </p>
  54. <p align="center">
  55. <img src="https://img.shields.io/badge/-Shell-4EAA25?logo=gnu-bash&logoColor=white" alt="Shell" />
  56. <img src="https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
  57. <img src="https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white" alt="Python" />
  58. <img src="https://img.shields.io/badge/-Go-00ADD8?logo=go&logoColor=white" alt="Go" />
  59. <img src="https://img.shields.io/badge/-Java-ED8B00?logo=openjdk&logoColor=white" alt="Java" />
  60. <img src="https://img.shields.io/badge/-Perl-39457E?logo=perl&logoColor=white" alt="Perl" />
  61. <img src="https://img.shields.io/badge/-Markdown-000000?logo=markdown&logoColor=white" alt="Markdown" />
  62. </p>
  63. > [!WARNING]
  64. > **Official sources only.** Install ECC only from verified channels: the GitHub repository [github.com/affaan-m/ECC](https://github.com/affaan-m/ECC), the npm packages [`ecc-universal`](https://www.npmjs.com/package/ecc-universal) and [`ecc-agentshield`](https://www.npmjs.com/package/ecc-agentshield), the [GitHub App](https://github.com/apps/ecc-tools), the plugin slug `ecc@ecc`, and the project website [ecc.tools](https://ecc.tools). Third-party re-uploads and unofficial mirrors are not maintained or reviewed by the project and may contain malware.
  65. ## Install with Claude Code
  66. Use the [guided setup](#install-ecc) or [native plugin commands](#claude-code-details). Both install the same `ecc@ecc` plugin. Choose one and do not stack a full manual Claude install on top.
  67. <div align="center">
  68. <table aria-label="ECC primary links">
  69. <tr>
  70. <td width="33%" align="center">
  71. <a href="https://ecc.tools/pricing">
  72. <img src="assets/images/community/ecc-tools-mark.svg" height="42" alt="ECC Tools" /><br />
  73. <strong>ECC Pro + GitHub App</strong>
  74. </a><br />
  75. <sub><a href="https://github.com/apps/ecc-tools">Install free</a> · <a href="https://ecc.tools/pricing">Private repos from $19/seat/mo</a></sub>
  76. </td>
  77. <td width="33%" align="center">
  78. <a href="https://github.com/sponsors/affaan-m">
  79. <img src="assets/images/community/heart.svg" height="42" alt="" /><br />
  80. <strong>Sponsor ECC</strong>
  81. </a><br />
  82. <sub>Fund the open-source project</sub>
  83. </td>
  84. <td width="33%" align="center">
  85. <a href="https://discord.gg/36yGMHGFbR">
  86. <img src="assets/images/community/discord.svg" height="42" alt="Discord" /><br />
  87. <strong>Community</strong>
  88. </a><br />
  89. <sub>Discord · Q&amp;A · Show and Tell</sub>
  90. </td>
  91. </tr>
  92. </table>
  93. </div>
  94. <sub>**OSS stays free.** This repo is MIT-licensed forever. ECC Pro is the hosted GitHub App for private repos. <a href="https://github.com/sponsors/affaan-m">Sponsors</a> and <a href="https://ecc.tools/pricing">Pro subscribers</a> fund the work. That's why a single maintainer ships weekly across 7 harnesses.</sub>
  95. <div align="center">
  96. <sub><strong>Partners &amp; sponsors</strong></sub>
  97. <p align="center" aria-label="Partners and sponsors">
  98. <a href="https://www.coderabbit.ai" title="CodeRabbit"><img src="assets/images/sponsors/coderabbit.png" height="54" alt="CodeRabbit" /></a>&nbsp;&nbsp;&nbsp;
  99. <a href="https://www.greptile.com/go/ecc" title="Greptile"><img src="assets/images/sponsors/greptile.png" height="54" alt="Greptile" /></a>&nbsp;&nbsp;&nbsp;
  100. <a href="https://platform.kimi.ai?aff=ecc" title="Moonshot AI - Kimi"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/images/sponsors/moonshot-dark.png" /><img src="assets/images/sponsors/moonshot.png" width="132" alt="Moonshot AI - Kimi" /></picture></a>&nbsp;&nbsp;&nbsp;
  101. <a href="https://compute.itomarkets.com" title="Itô Markets"><picture><source media="(prefers-color-scheme: light)" srcset="assets/images/sponsors/ito-transparent-light.png" /><img src="assets/images/sponsors/ito-transparent.png" width="96" alt="Itô Markets" /></picture></a>&nbsp;&nbsp;&nbsp;
  102. <a href="https://serpapi.com/github-ecc" title="SerpApi: Web Search API"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/images/sponsors/serpapi-logo-dark-mode.svg" /><img src="assets/images/sponsors/serpapi-logo-light-mode.svg" width="200" alt="SerpApi: Web Search API" /></picture></a>
  103. </p>
  104. <sub><strong>Past sponsors:</strong> <a href="https://www.atlascloud.ai/?utm_source=github&amp;utm_medium=link&amp;utm_campaign=ECC">Atlas Cloud</a> · <a href="https://github.com/mikejmorgan-ai">Mike Morgan (inactive)</a></sub>
  105. <sub><strong>Community sponsors:</strong> <a href="https://github.com/jasonwu513">@jasonwu513</a> · <a href="https://github.com/1anter">@1anter</a> · <a href="https://github.com/massimotodaro">@massimotodaro</a> · <a href="https://github.com/meadmccabe">@meadmccabe</a></sub>
  106. <sub><a href="https://github.com/sponsors/affaan-m"><strong>Become a Sponsor</strong></a> · <a href="SPONSORS.md">Sponsor Tiers</a> · <a href="SPONSORING.md">Sponsorship Program</a></sub>
  107. </div>
  108. <p align="center"><a href="#install-ecc">Jump to install ↓</a></p>
  109. # ECC
  110. Your agent can write code, but ECC gives it a coordinated engineering system and toolbox: it plans before it builds, verifies changes with tests, reviews its own work from a fresh context, remembers what matters, and turns repeated wins into reusable skills and workflows.
  111. ```text
  112. plan -> test -> implement -> review -> verify -> remember -> improve
  113. ```
  114. Instead of rebuilding that process in every prompt, you install it once and make it part of how your agent works.
  115. > Optimize the context window. Persist everything else.
  116. ECC is MIT-licensed open source. It works best with Claude Code today, has native Codex and Qoder plugin paths, and provides capability-limited adapters for Cursor, OpenCode, Gemini, Zed, GitHub Copilot, Antigravity, Qwen, and other harnesses. See the [support status matrix](#platform-support) before assuming feature parity.
  117. Access to 72 agents, 327 skills, and 98 legacy command shims, plus hooks, rules, memory, continuous learning, and AgentShield security scanning. The agents are specialized for planning, review, build repair, security, architecture, and domain work.
  118. | Included | Count | What it gives you |
  119. | ---------------- | ----------: | ------------------------------------------------------------------------------------ |
  120. | Agents | 72 agents | Planning, review, build repair, security, architecture, and domain work |
  121. | Skills | 327 skills | TDD, research, security, docs, frontend, data, ML, operations, and more |
  122. | Commands | 98 commands | Convenient entry points while ECC moves to a skills-first surface |
  123. | Hooks and memory | Runtime | Enforcement, session summaries, continuous learning, instincts, and context controls |
  124. | Rules | Selective | Always-loaded standards you choose by language or project |
  125. | AgentShield | Included | Scanning for prompts, hooks, MCP config, permissions, secrets, and agent files |
  126. <p align="center">
  127. <a href="https://www.star-history.com/affaan-m/ecc">
  128. <picture>
  129. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=affaan-m/ECC&type=Date&theme=dark" />
  130. <img src="https://api.star-history.com/svg?repos=affaan-m/ECC&type=Date" alt="Live star history chart for affaan-m/ECC" width="100%" />
  131. </picture>
  132. </a>
  133. </p>
  134. ## Install ECC
  135. > [!IMPORTANT]
  136. > ECC 2.2 includes guided package setup for Claude Code, Codex, and Kimi Code.
  137. > The universal package requires Node.js 18 or newer. Claude plugin setup also
  138. > requires Git and Claude Code 2.1 or newer on `PATH`.
  139. ### Recommended: universal guided setup
  140. For Claude Code plugin setup, updates, scope changes, and hook-profile changes:
  141. ```bash
  142. npx ecc-universal@2.2.3 setup
  143. ```
  144. #### Windows first-time walkthrough
  145. If you are new to command-line tools, use this copy-and-paste path:
  146. 1. Install Node.js 18 or newer, Git, and Claude Code.
  147. 2. Open **PowerShell** from the Windows Start menu.
  148. 3. Confirm that each prerequisite is available:
  149. ```powershell
  150. node --version
  151. git --version
  152. claude --version
  153. ```
  154. 4. Run the guided installer:
  155. ```powershell
  156. npx ecc-universal@2.2.3 setup
  157. ```
  158. 5. For a typical personal setup, choose **Global user**, choose **Standard** hooks, and confirm.
  159. 6. Start a new Claude Code session and run `/plugin list` to verify that `ecc@ecc` is enabled.
  160. This path does not require cloning the repository. If any prerequisite command is not found, install or repair that prerequisite before rerunning ECC setup.
  161. If npm reports a version or cache error, confirm the registry version before retrying:
  162. ```bash
  163. npm view ecc-universal version
  164. ```
  165. ECC 2.2 supports the same guided setup through modern package runners:
  166. | Package runner | Guided setup command |
  167. |---|---|
  168. | npm / npx | `npx ecc-universal@2.2.3 setup` |
  169. | pnpm | `pnpm dlx ecc-universal@2.2.3 setup` |
  170. | Yarn 2+ | `yarn dlx ecc-universal@2.2.3 setup` |
  171. | Bun | `bunx ecc-universal@2.2.3 setup` |
  172. The examples select [the published ECC 2.2.3 release](https://www.npmjs.com/package/ecc-universal/v/2.2.3), matching this repository's release version. A version pin is not a security audit or an integrity check. Review the release source and registry integrity before running package code; use a reviewed checkout for unreleased changes.
  173. Yarn Classic 1 does not provide `yarn dlx`; use `npx`, install the package globally, or upgrade Yarn for a temporary one-shot run.
  174. The wizard inventories the official marketplace and every native Claude install scope before making changes, then installs, updates, or safely moves `ecc@ecc` to the scope you choose. Rerun the same command whenever you want to update ECC, change scope, or change its hook profile. This setup wizard currently configures the Claude Code plugin; use the multi-harness wizard below for Codex or Kimi Code.
  175. To configure more than one coding agent in one reviewed flow, use the multi-harness wizard:
  176. ```bash
  177. npx ecc-universal@2.2.3 install --guided
  178. ```
  179. It lets you select any combination of Claude Code, Codex, and Kimi Code, shows each install channel and destination, preflights every selection before the first write, and asks for one final confirmation.
  180. | Harness | Guided install behavior |
  181. |---|---|
  182. | Claude Code | Native `ecc@ecc` plugin with one `user`, `project`, or `local` scope and an ECC hook profile |
  183. | Codex | Native Codex marketplace/plugin lifecycle; hook review and trust remain Codex-owned |
  184. | Kimi Code | Managed project files under `./.kimi-code`; ECC hooks, model/provider settings, and authentication are not configured |
  185. For automation, make every provider-specific choice explicit:
  186. ```bash
  187. npx ecc-universal@2.2.3 install --guided \
  188. --harness claude --harness codex --harness kimi \
  189. --claude-scope local --claude-hooks standard \
  190. --profile core --yes
  191. ```
  192. Verify the native guided Codex path and managed Kimi path without writing first:
  193. ```bash
  194. npx ecc-universal@2.2.3 install --guided --harness codex --dry-run
  195. npx ecc-universal@2.2.3 install --profile core --target kimi --dry-run
  196. ```
  197. Additional package-name commands are also available through the 2.2 alias:
  198. ```bash
  199. npx ecc-universal@2.2.3 consult "security reviews" --target claude
  200. npx ecc-universal@2.2.3 install --profile minimal --target claude --with capability:machine-learning
  201. npx ecc-universal@2.2.3 doctor --target kimi
  202. ```
  203. Do not use `npx ecc-install --profile minimal --target claude`: `ecc-install` is a binary name inside `ecc-universal`, not a separately published npm package.
  204. ECC also ships advanced managed adapters for `cursor`, `antigravity`, `antigravity-home`, `gemini`, `opencode`, `codebuddy`, `joycode`, `qwen`, `zed`, `hermes`, `openclaw`, and `mistral-vibe`. Those targets still use their documented `ecc install --target ...` paths until each adapter has passed the guided collision, update, repair, and uninstall lifecycle matrix. Neither wizard silently installs into every detected harness.
  205. ### Pick one path only (per harness)
  206. You can use ECC with Claude Code, Codex, and other harnesses at the same time. Choose one install method for each harness:
  207. - **Recommended default:** run the guided Claude plugin setup above
  208. - **Also supported for Claude Code:** use the [native plugin commands](#claude-code-details)
  209. - **Available in release 2.2:** guided package setup for Claude Code, Codex, and Kimi Code
  210. - **Works:** Claude Code plugin + Codex native plugin
  211. - **Works:** Claude Code plugin + the legacy Codex sync flow
  212. - **Avoid:** Claude Code plugin + full Claude manual install
  213. - **Avoid:** Codex sync + Codex marketplace plugin
  214. **Do not stack install methods.** Installing ECC twice into the same harness can duplicate skills, commands, hooks, or configuration; installing it once into multiple harnesses does not.
  215. If you already layered multiple installs and things look duplicated, skip straight to [Reset / Uninstall ECC](#reset--uninstall-ecc).
  216. **Install trouble?** Open the short [install or runtime problem form](https://github.com/affaan-m/ECC/issues/new?template=install-problem.yml), or run `ecc feedback`. ECC never uploads diagnostics automatically.
  217. ### Claude Code details
  218. Alternatively, run Claude Code's native plugin commands inside Claude Code:
  219. ```text
  220. /plugin marketplace add https://github.com/affaan-m/ECC
  221. /plugin install ecc@ecc
  222. ```
  223. The native path installs ECC's skills, agents, commands, and plugin-managed hooks. If you choose it, stop there. Do not also run a full manual install into Claude Code.
  224. Claude Code owns these built-in commands, including their errors when a marketplace, plugin, or conflicting scope already exists. ECC cannot intercept that parser. If either native command reports an existing install or scope conflict, use the 2.2 guided setup or resolve the conflicting Claude plugin scope before retrying; do not layer a manual install on top.
  225. After ECC is installed, `/ecc:configure-ecc` is the namespaced in-Claude reconfiguration skill. It delegates to the same safe setup flow, but it is available only after the plugin is installed and cannot replace Claude Code's built-in `/plugin` command during a first install.
  226. Claude Code plugins cannot distribute `rules`, so add only the rule packs you actually want:
  227. ```bash
  228. git clone https://github.com/affaan-m/ECC.git
  229. cd ECC
  230. mkdir -p ~/.claude/rules/ecc
  231. cp -R rules/common ~/.claude/rules/ecc/
  232. cp -R rules/typescript ~/.claude/rules/ecc/ # replace with your stack
  233. ```
  234. Start with `rules/common` plus one language or framework pack you actually use. If you install the plugin, do not run `./install.sh --profile full` afterward.
  235. <details>
  236. <summary><strong>Prefer settings.json? Add the marketplace declaratively</strong></summary>
  237. Add directly to your `~/.claude/settings.json`:
  238. ```json
  239. {
  240. "extraKnownMarketplaces": {
  241. "ecc": {
  242. "source": {
  243. "source": "github",
  244. "repo": "affaan-m/ECC"
  245. }
  246. }
  247. },
  248. "enabledPlugins": {
  249. "ecc@ecc": true
  250. }
  251. }
  252. ```
  253. This gives you the same result as the two `/plugin` commands above.
  254. </details>
  255. <details>
  256. <summary><strong>Naming + migration note (ecc@ecc, affaan-m/ECC, ecc-universal)</strong></summary>
  257. ECC has three public identifiers, and they are not interchangeable:
  258. - GitHub source repo: `affaan-m/ECC`
  259. - Claude marketplace/plugin identifier: `ecc@ecc`
  260. - npm package: `ecc-universal`
  261. 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.
  262. 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.
  263. 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.
  264. </details>
  265. ### Codex App and CLI
  266. Current Codex releases can install ECC as a native repo-marketplace plugin. The marketplace entry uses the repository root so Codex's cache receives the manifest together with all referenced skills, MCP configuration, hook runtime, scripts, and assets:
  267. ```bash
  268. codex plugin marketplace add affaan-m/ECC
  269. codex plugin add ecc@ecc
  270. codex plugin list --json
  271. node scripts/codex/check-plugin-cache.js
  272. ```
  273. Both add commands are idempotent. To refresh later, run `codex plugin marketplace upgrade ecc` followed by `codex plugin add ecc@ecc`. Codex stores one enabled plugin state in the active `CODEX_HOME`; it does not offer Claude's `user`, `project`, and `local` scopes. Its native hooks require an explicit trust decision and do not use Claude's four ECC hook profiles. Inside Codex, invoke `$configure-ecc` for the guided provider-aware flow.
  274. The older `scripts/sync-ecc-to-codex.sh` path is a deprecated compatibility option for users who intentionally need copied and merged configuration in `~/.codex`; it is not required for the native plugin. New sync runs write an ownership manifest so cleanup can preserve modified user files. Run Codex once first so `~/.codex/config.toml` exists, then:
  275. ```bash
  276. git clone https://github.com/affaan-m/ECC.git
  277. cd ECC
  278. npm install
  279. bash scripts/sync-ecc-to-codex.sh
  280. ```
  281. To inspect or remove that legacy layer without touching Codex conversations or native plugin caches:
  282. ```bash
  283. node scripts/ecc.js uninstall --legacy-codex-sync --dry-run
  284. node scripts/ecc.js uninstall --legacy-codex-sync
  285. ```
  286. Pre-manifest installations are handled conservatively: ECC removes its marked `AGENTS.md` block but preserves copied files it cannot prove it owns and reports them for review.
  287. You can also open the ECC repository directly in Codex for a project-local setup. Codex reads the root `AGENTS.md` and the trusted project configuration in `.codex/` without a global sync. Do not add the native marketplace plugin on top of the sync flow.
  288. For repo navigation, surface ownership, and PR diff packet guidance, read the [Codex ECC Navigation Map](docs/CODEX-NAVIGATION-GUIDE.md). See the [.codex plugin notes](.codex-plugin/README.md) for native lifecycle details.
  289. ### Qoder CLI and IDE
  290. ECC ships a native Qoder plugin that reuses the canonical skills, agents,
  291. 95 legacy command shims, and the pinned `chrome-devtools` MCP definition. From a
  292. reviewed checkout, validate and install it with Qoder CLI:
  293. ```bash
  294. qoder plugins validate . --strict
  295. qoder plugins install .
  296. qoder plugins list
  297. ```
  298. For Qoder IDE, upload a ZIP of the repository root. The ZIP root must contain
  299. `.qoder-plugin/` together with `skills/`, `agents/`, `commands/`, `hooks/`,
  300. `scripts/`, and `.mcp.json`; uploading only the manifest directory or one
  301. `SKILL.md` omits required resources.
  302. The universal Node.js 18+ requirement applies to Qoder's non-interactive hook
  303. environment. The MCP server also requires `npx` and network access on first use.
  304. Qoder receives one reviewed, cross-platform `SessionStart` bootstrap using
  305. `QODER_PLUGIN_ROOT` and exec-form arguments. ECC does not copy the full Claude
  306. hook profile into Qoder: blocking tool hooks, async stop jobs, and
  307. Claude-specific matchers remain outside this initial native integration. See
  308. the [.qoder-plugin notes](.qoder-plugin/README.md) for the exact boundary.
  309. ### Other agents and editors
  310. <details>
  311. <summary><strong>Cursor, OpenCode, Gemini, Zed, Antigravity, Qwen, Hermes, OpenClaw, Kimi, Mistral Vibe, CodeBuddy, JoyCode, Copilot</strong></summary>
  312. Clone ECC once, then choose the target that matches your harness:
  313. ```bash
  314. git clone https://github.com/affaan-m/ECC.git
  315. cd ECC
  316. ```
  317. | Harness | Install or setup | Notes |
  318. |---|---|---|
  319. | Cursor | `./install.sh --profile minimal --target cursor` | Project-local `.cursor/` adapter |
  320. | OpenCode | `npm install && npm run build:opencode && ./install.sh --profile full --target opencode --enable-hooks` | Builds the plugin payload before the full install |
  321. | Gemini CLI | `./install.sh --profile minimal --target gemini` | Project-local `.gemini/` config |
  322. | Zed | `./install.sh --profile minimal --target zed` | Project-local `.zed/` adapter |
  323. | Antigravity (Global Plugin) | `./install.sh --target antigravity-home --profile core --enable-hooks` | Experimental global plugin (`~/.gemini/config/plugins/ecc/`) with lifecycle hooks · [Guide](docs/ANTIGRAVITY-GUIDE.md) |
  324. | Antigravity (Project-Local) | `./install.sh --target antigravity --profile minimal` | Project-local `.agents/` adapter · [Guide](docs/ANTIGRAVITY-GUIDE.md) |
  325. | Qwen CLI | `./install.sh --profile minimal --target qwen` | See the [Qwen guide](docs/QWEN-GUIDE.md) |
  326. | Hermes | `./install.sh --profile minimal --target hermes` | See the [Hermes setup guide](docs/HERMES-SETUP.md) |
  327. | OpenClaw | `./install.sh --profile minimal --target openclaw` | Managed home-directory install |
  328. | Kimi Code CLI | `./install.sh --profile minimal --target kimi` | Project-local `.kimi-code/` install · [Get Kimi Code](https://www.kimi.ai/code?aff=ecc) |
  329. | Mistral Vibe | `./install.sh --target mistral-vibe --skills tdd-workflow` | Project-local `.vibe/skills/` install · [Mistral Vibe guide](docs/MISTRAL-VIBE-GUIDE.md) |
  330. | CodeBuddy | `./install.sh --profile minimal --target codebuddy` | Project-local `.codebuddy/` install |
  331. | JoyCode | `./install.sh --profile minimal --target joycode` | Project-local `.joycode/` install |
  332. | GitHub Copilot | `./install.sh --profile full --target copilot` | Installs skills to `.github/skills/` and agents to `.github/agents/` for Copilot CLI |
  333. 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`. GitHub Copilot CLI additionally discovers the `.agents/skills/` subset from a plain clone with no setup; see [Platform Support](#platform-support) for the full catalog and agents.
  334. For a harness without a native ECC target, use the [manual adaptation guide](docs/MANUAL-ADAPTATION-GUIDE.md). 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.
  335. 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.
  336. Deep per-harness notes (feature parity, hook adapters, limitations) live in [Platform Support](#platform-support) below.
  337. </details>
  338. ## Advanced Install Options
  339. <details>
  340. <summary><strong>Low-context install with no hook runtime</strong></summary>
  341. ### Low-context / no-hooks path
  342. Use this when you want ECC's rules, agents, commands, platform config, and core workflows without runtime hooks:
  343. ```bash
  344. npx ecc-universal@2.2.3 install --profile minimal --target claude
  345. ```
  346. From a source checkout, the equivalent command is:
  347. ```bash
  348. ./install.sh --profile minimal --target claude
  349. ```
  350. Windows:
  351. ```powershell
  352. .\install.ps1 --profile minimal --target claude
  353. ```
  354. This profile intentionally excludes `hooks-runtime`.
  355. 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.
  356. For the normal core profile with hooks disabled:
  357. ```bash
  358. ./install.sh --profile core --without baseline:hooks --target claude
  359. ./install.sh --profile core --no-hooks --target claude
  360. ```
  361. Add the hook runtime later only if you want it:
  362. ```bash
  363. ./install.sh --target claude --modules hooks-runtime --enable-hooks
  364. ```
  365. Any install whose profile or modules would materialize the hook runtime requires
  366. an explicit decision. Without `--enable-hooks` or `--no-hooks`, the installer
  367. prints what the hooks can do and stops before writing anything. The guided
  368. installer (`ecc install --guided`) asks for this choice interactively.
  369. </details>
  370. <details>
  371. <summary><strong>Choose only the components you need</strong></summary>
  372. ### Find the right components first
  373. Ask the packaged advisor which components match your work:
  374. ```bash
  375. node scripts/ecc.js consult "security reviews" --target claude
  376. ```
  377. 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.
  378. You can also install explicit skills or capabilities:
  379. ```bash
  380. ./install.sh --target claude --skills tdd-workflow,security-review
  381. node scripts/ecc.js install --profile minimal --target claude --with capability:machine-learning
  382. ```
  383. Manual component-by-component copying also works. Each component is fully independent:
  384. ```bash
  385. # Just agents
  386. mkdir -p ~/.claude/agents
  387. cp agents/*.md ~/.claude/agents/
  388. # Rules directories (common + language-specific)
  389. mkdir -p ~/.claude/rules/ecc
  390. cp -r rules/common ~/.claude/rules/ecc/
  391. cp -r rules/typescript ~/.claude/rules/ecc/ # pick your stack
  392. # Core/general skills only (Claude Code loads skills from direct children
  393. # of ~/.claude/skills; do not nest manual installs under ~/.claude/skills/ecc/)
  394. mkdir -p ~/.claude/skills
  395. cp -r .agents/skills/* ~/.claude/skills/
  396. cp -r skills/search-first ~/.claude/skills/
  397. # Optional: maintained slash-command compatibility during migration
  398. mkdir -p ~/.claude/commands
  399. cp commands/*.md ~/.claude/commands/
  400. ```
  401. Retired shims live in `legacy-command-shims/`. Copy individual files from there only if you still need old names such as `/tdd`.
  402. </details>
  403. <details>
  404. <summary><strong>Project-local rules instead of global rules</strong></summary>
  405. Use project-local rules when ECC's standards should apply to one repository rather than every Claude Code session:
  406. ```bash
  407. cd your-project
  408. mkdir -p .claude/rules/ecc
  409. cp -R /path/to/ECC/rules/common .claude/rules/ecc/
  410. cp -R /path/to/ECC/rules/typescript .claude/rules/ecc/
  411. ```
  412. 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.
  413. </details>
  414. <details>
  415. <summary><strong>Fully manual Claude install</strong></summary>
  416. Use this only when you are intentionally skipping the plugin path:
  417. ```bash
  418. git clone https://github.com/affaan-m/ECC.git
  419. cd ECC
  420. ./install.sh --profile full --enable-hooks
  421. ```
  422. Windows:
  423. ```powershell
  424. git clone https://github.com/affaan-m/ECC.git
  425. cd ECC
  426. .\install.ps1 --profile full --enable-hooks
  427. ```
  428. These examples enable the automatic hook runtime. To install without hooks, replace `--enable-hooks` with `--no-hooks`.
  429. If you choose this path, stop there. Do not also run `/plugin install`.
  430. For hand-picked manual installs, Claude discovers skills as direct children of `~/.claude/skills/`; do not nest them under `~/.claude/skills/ecc/`.
  431. #### Install hooks
  432. 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:
  433. ```bash
  434. bash ./install.sh --target claude --modules hooks-runtime --enable-hooks
  435. ```
  436. That installs the hook scripts under `~/.claude/` and registers the resolved
  437. hook entries in `~/.claude/settings.json`. Existing user settings and hooks are
  438. preserved; ECC-owned entries are tracked by stable ID for idempotent updates
  439. and safe uninstall.
  440. 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.
  441. On Windows, Claude's config root is `%USERPROFILE%\.claude`; install the hook runtime with:
  442. ```powershell
  443. pwsh -File .\install.ps1 --target claude --modules hooks-runtime --enable-hooks
  444. ```
  445. #### Configure MCPs
  446. 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.
  447. 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`.
  448. 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](docs/MCP-CONNECTOR-POLICY.md).
  449. If you already run your own copies of ECC-bundled MCPs, set:
  450. ```bash
  451. export ECC_DISABLED_MCPS="chrome-devtools"
  452. ```
  453. 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.
  454. **Important:** Replace `YOUR_*_HERE` placeholders with your actual API keys.
  455. </details>
  456. <details>
  457. <summary><strong>Multi-model commands require additional setup</strong></summary>
  458. `multi-*` commands are **not** covered by the base plugin/rules install.
  459. 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](https://github.com/fengshao1227/ccg-workflow#readme), 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.
  460. That runtime provides the external dependencies these commands expect, including:
  461. - `~/.claude/bin/codeagent-wrapper`
  462. - `~/.claude/.ccg/prompts/*`
  463. Without `ccg-workflow`, these `multi-*` commands will not run correctly.
  464. </details>
  465. <details>
  466. <summary><strong>Astra review requires the Codex CLI</strong></summary>
  467. `/astra-review` sends Claude-written code to GPT-6-Astra for an independent cross-provider review. It runs the locally installed [Codex CLI](https://github.com/openai/codex) with your ChatGPT login (`codex login`); no OpenAI API key is needed, and API keys in your environment are not forwarded. Invoking the command is your consent to send that diff to OpenAI. Setup, scopes, push gating, and troubleshooting are in the [Astra Review Guide](docs/ASTRA-REVIEW-GUIDE.md).
  468. </details>
  469. <details>
  470. <summary><strong>Reset, repair, or uninstall</strong></summary>
  471. ### Reset / Uninstall ECC
  472. If you installed from the universal package, run these commands from the same
  473. project directory used for installation:
  474. ```bash
  475. npx ecc-universal@2.2.3 list-installed
  476. npx ecc-universal@2.2.3 doctor
  477. npx ecc-universal@2.2.3 repair
  478. npx ecc-universal@2.2.3 uninstall --dry-run
  479. npx ecc-universal@2.2.3 uninstall
  480. ```
  481. From a source checkout, inspect the managed state before reinstalling:
  482. ```bash
  483. node scripts/ecc.js list-installed
  484. node scripts/ecc.js doctor
  485. node scripts/ecc.js repair
  486. node scripts/ecc.js uninstall --dry-run
  487. ```
  488. For a direct source-checkout uninstall:
  489. ```bash
  490. node scripts/uninstall.js --dry-run
  491. node scripts/uninstall.js
  492. ```
  493. If you are leaving, the uninstall command prints an optional [20-second feedback form](https://github.com/affaan-m/ECC/issues/new?template=quick-feedback.yml). 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.
  494. 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.
  495. If you stacked methods, clean up in this order:
  496. 1. Remove the Claude Code plugin install.
  497. 2. Run the ECC uninstall command from the project directory that contains the managed install-state.
  498. 3. Delete any extra rule folders you copied manually and no longer want.
  499. 4. Reinstall once, using a single path.
  500. </details>
  501. ## Start Using ECC
  502. Start with the workflow you need, not the full catalog.
  503. | What you are doing | Start here |
  504. |---|---|
  505. | Building a feature | `/ecc:plan "describe the feature"`, then `tdd-workflow` |
  506. | Fixing a bug | Reproduce it with a failing test, then use `tdd-workflow` |
  507. | Reviewing new code | `/code-review` for a fresh-context review |
  508. | Triaging a GitHub issue | `/ecc:issue-review <number>` (plugin) or `/issue-review <number>` (manual install) to verify it against the code and draft a reply |
  509. | Repairing a build | `/build-fix` |
  510. | Cleaning a codebase | `/refactor-clean` |
  511. | Checking context pressure | `/context-budget` |
  512. | Ending a long session | `/save-session` or `/learn-eval` |
  513. | Resuming later | `/resume-session` |
  514. | Auditing agent config | `/security-scan` with a reviewed scanner, or installed `agentshield scan --path .` |
  515. <details>
  516. <summary><strong>Plugin commands and manual commands</strong></summary>
  517. Claude Code plugin commands use the namespaced form:
  518. ```text
  519. /ecc:plan "Add authentication"
  520. ```
  521. Manual installs may expose the shorter compatibility form:
  522. ```text
  523. /plan "Add authentication"
  524. ```
  525. Skills are the primary workflow surface. Commands remain convenient entry points and compatibility shims. Check what is installed with:
  526. ```bash
  527. /plugin list ecc@ecc
  528. ```
  529. </details>
  530. <details>
  531. <summary><strong>Which agent should I use?</strong></summary>
  532. Skills are the canonical workflow surface; maintained slash entries stay available for command-first workflows.
  533. | I want to... | Use this surface | Agent used |
  534. |--------------|-----------------|------------|
  535. | Plan a new feature | `/ecc:plan "Add auth"` | planner |
  536. | Design system architecture | `/ecc:plan` + architect agent | architect |
  537. | Write code with tests first | `tdd-workflow` skill | tdd-guide |
  538. | Review code I just wrote | `/code-review` | code-reviewer |
  539. | Review a GitHub issue | `/ecc:issue-review` (plugin), `/issue-review` (manual install) | — (issue-review skill) |
  540. | Fix a failing build | `/build-fix` | build-error-resolver |
  541. | Run end-to-end tests | `e2e-testing` skill | e2e-runner |
  542. | Find security vulnerabilities | `/security-scan` | security-reviewer |
  543. | Remove dead code | `/refactor-clean` | refactor-cleaner |
  544. | Update documentation | `/update-docs` | doc-updater |
  545. | Review Go code | `/go-review` | go-reviewer |
  546. | Review Python code | `/python-review` | python-reviewer |
  547. | Review F# code | *(invoke `fsharp-reviewer` directly)* | fsharp-reviewer |
  548. | Review TypeScript/JavaScript code | *(invoke `typescript-reviewer` directly)* | typescript-reviewer |
  549. | Develop HarmonyOS apps | *(invoke `harmonyos-app-resolver` directly)* | harmonyos-app-resolver |
  550. | Audit database queries | *(auto-delegated)* | database-reviewer |
  551. | Review production ML changes | `mle-workflow` skill + `mle-reviewer` agent | mle-reviewer |
  552. </details>
  553. <details>
  554. <summary><strong>Common workflows</strong></summary>
  555. 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.
  556. **Starting a new feature:**
  557. ```
  558. /ecc:plan "Add user authentication with OAuth"
  559. -> planner creates implementation blueprint
  560. tdd-workflow skill -> tdd-guide enforces write-tests-first
  561. /code-review -> code-reviewer checks your work
  562. ```
  563. **Fixing a bug:**
  564. ```
  565. tdd-workflow skill -> tdd-guide: write a failing test that reproduces it
  566. -> implement the fix, verify test passes
  567. /code-review -> code-reviewer: catch regressions
  568. ```
  569. **Preparing for production:**
  570. ```
  571. /security-scan -> security-reviewer: OWASP Top 10 audit
  572. e2e-testing skill -> e2e-runner: critical user flow tests
  573. /test-coverage -> verify 80%+ coverage
  574. ```
  575. </details>
  576. ## Self-Hosted Models and Custom Endpoints
  577. ECC works through each harness's normal configuration, so you can use an official provider, a compatible custom API endpoint or model gateway, or a self-hosted model without changing ECC's workflows.
  578. For Claude Code, ECC does not hardcode Anthropic-hosted transport settings. Minimal gateway example:
  579. ```bash
  580. export ANTHROPIC_BASE_URL=https://your-gateway.example.com
  581. export ANTHROPIC_AUTH_TOKEN=your-token
  582. claude
  583. ```
  584. If your gateway remaps model names, configure that in Claude Code rather than in ECC. ECC's hooks, skills, commands, and rules are model-provider agnostic once the `claude` CLI is already working. See Anthropic's [LLM gateway documentation](https://docs.anthropic.com/en/docs/claude-code/llm-gateway) and [model configuration documentation](https://docs.anthropic.com/en/docs/claude-code/model-config).
  585. Run or self-host any open-source model behind that gateway using separate compute and serving setup. If you need GPU capacity, [Itô](https://compute.itomarkets.com) is ECC's preferred compute sponsor; any GPU provider works. The sponsorship link is passive: it does not invoke an RFQ, reserve capacity, provision compute, or configure serving. Separately, `ecc ito find` invokes the explicitly configured canonical Itô CLI and submits a live authenticated RFQ; it does not reserve capacity. Managed inference through Itô is not live yet.
  586. ### Self-host Kimi with ECC + Itô compute
  587. The Kimi Code harness and the model-serving layer are separate. ECC configures the agent harness; you bring an API endpoint ([get a Kimi API key](https://platform.kimi.ai?aff=ecc)) or self-host an open-weight Kimi model on your own GPU capacity. This adapter is verified against Kimi Code 0.31.x (`@moonshot-ai/kimi-code`):
  588. <table aria-label="Local Kimi model path" width="100%">
  589. <tr>
  590. <td width="33%" align="center">
  591. <a href="https://compute.itomarkets.com">
  592. <picture><source media="(prefers-color-scheme: light)" srcset="assets/images/sponsors/ito-transparent-light.png" /><img src="assets/images/sponsors/ito-transparent.png" width="92" alt="Itô Markets" /></picture><br />
  593. <strong>1. Get GPU capacity</strong>
  594. </a><br />
  595. <sub>Use Itô or any GPU provider.</sub>
  596. </td>
  597. <td width="33%" align="center">
  598. <a href="https://www.moonshot.ai">
  599. <picture><source media="(prefers-color-scheme: dark)" srcset="assets/images/sponsors/moonshot-dark.png" /><img src="assets/images/sponsors/moonshot.png" width="126" alt="Moonshot AI - Kimi" /></picture><br />
  600. <strong>2. Serve Kimi</strong>
  601. </a><br />
  602. <sub>Expose the chosen checkpoint through a compatible endpoint.</sub>
  603. </td>
  604. <td width="33%" align="center">
  605. <a href=".kimi/README.md">
  606. <img src="assets/images/community/ecc-tools-mark.svg" height="52" alt="ECC Tools" /><br />
  607. <strong>3. Run Kimi Code with ECC</strong>
  608. </a><br />
  609. <sub>Install project instructions and skills, then start Kimi Code.</sub>
  610. </td>
  611. </tr>
  612. </table>
  613. Configure the endpoint with Kimi Code's <a href="https://moonshotai.github.io/kimi-cli/en/configuration/providers.html">official provider guide</a>, then install ECC:
  614. ```bash
  615. bash ./install.sh --target kimi --profile minimal
  616. node scripts/ecc.js doctor --target kimi
  617. kimi
  618. ```
  619. Kimi Code discovers the installed `.kimi-code/AGENTS.md` instructions and `.kimi-code/skills/` workflows natively; project-level `.agents/skills/` is also an official discovery location. ECC safely merges project MCP entries into `.kimi-code/mcp.json` and does not change the user-level `~/.kimi-code/config.toml`. Kimi Code supports native hooks, but ECC's current managed-project adapter does not configure them, so this installer does not offer Kimi hook profiles. The installer dry-run and regression suite verify that every managed Kimi write stays inside the project-local `.kimi-code/` root.
  620. ### Itô compute CLI bridge
  621. `ecc ito` delegates to the separately installed canonical Itô client; ECC does not maintain a second API client. `ecc ito login [--no-browser]` performs device authorization, opens the Itô verification page by default, and persists a device token in macOS Keychain; `--no-browser` suppresses the page handoff. ECC itself does no browser automation. `ecc ito auth` is validation-only and rejects `--no-browser`. The available operations are `ecc ito login`, `ecc ito auth`, `ecc ito find`, `ecc ito status`, and the separately gated `ecc ito evals`. The matching MCP tools remain `ito_auth`, `ito_find`, and `ito_status`; `ito_auth` validates existing credentials and node qualification is CLI-only.
  622. The `ito-compute-cli` package is currently unpublished. Build it locally from the Itô runtime repo (private while the desk hardens; design partners get access) under `cli/ito-compute-cli`, run `npm ci` and `npm run check`, then set `ECC_ITO_CLI_EXECUTABLE` to that build's absolute `dist/bin/ito.js` path. Login never inherits `ITO_API_KEY`; auth, find, and status forward `ITO_API_KEY` directly when configured, and `ITO_AUTH_MODE=legacy` is not required. `ecc ito logout` revokes the current device credential and retains its local copy if remote revocation cannot be confirmed. Device tokens use macOS Keychain by default; explicit file fallback must retain owner-only directory/file permissions. ECC does not discover this credential-bearing client through `PATH`. See the [`ito-compute` skill](skills/ito-compute/SKILL.md) for the full RFQ authority and MCP setup contract.
  623. `find` submits a live authenticated RFQ. It does not reserve capacity. `evals` requires both `ITO_ENABLE_SIXTYTWO_LIVE=1` and `--live-sixtytwo`, a separately installed `sixtytwo-cli==0.3.33`, an explicit node list, and an existing absolute configuration directory. It cannot rent, launch, recover, repair, or purchase. ECC exposes no quote lock, purchase, workload, or inference path, and it never replaces a missing client or failed live call with a local result.
  624. ## What's New
  625. Current release: **2.2.3** (2026-10-01). Highlights of the 2.2 line:
  626. - Guided, manifest-driven setup across Claude Code, Codex, and Kimi Code, with install-state ownership, doctor, repair, and uninstall.
  627. - Native Antigravity install, a thin Pi adapter, and the packed-artifact release gate tested on Linux, macOS, and Windows.
  628. - Plan Canvas browser review, the unified memory vault (`ecc memory`), and the Itô compute skill family.
  629. Full history: [CHANGELOG.md](CHANGELOG.md). Per-release notes and evidence live under [docs/releases/](docs/releases/).
  630. ### v2.0.0: The Agent Harness Operating System (Jun 2026)
  631. Stable graduation of the 2.0 line: control-pane substrate, worktree lifecycle service, the `orch-*` orchestrator family, and the Discord community. Notes: [docs/releases/2.0.0/release-notes.md](docs/releases/2.0.0/release-notes.md).
  632. ## What's Inside
  633. ```text
  634. ECC/
  635. |-- agents/ # 72 specialized subagents for delegation
  636. |-- skills/ # 327 reusable workflows loaded on demand
  637. |-- commands/ # 98 maintained slash-command shims
  638. |-- rules/ # opt-in common and language standards
  639. |-- hooks/ # runtime automation and enforcement
  640. |-- scripts/ # install, repair, sync, orchestration, and checks
  641. |-- .claude-plugin/ # Claude Code marketplace manifest
  642. |-- .codex/ # Codex reference configuration and agent roles
  643. |-- .opencode/ # OpenCode plugin, commands, and instructions
  644. |-- .cursor/ # Cursor rules and hook adapter
  645. |-- docs/ # public setup, architecture, and operating guides
  646. ```
  647. The root is the source of truth. Platform adapters package or map these same workflows instead of maintaining separate copies.
  648. <details>
  649. <summary><strong>Annotated component catalog</strong></summary>
  650. ```
  651. ECC/
  652. |-- .claude-plugin/ # Plugin and marketplace manifests
  653. | |-- plugin.json # Plugin metadata and component paths
  654. | |-- marketplace.json # Marketplace catalog for /plugin marketplace add
  655. |
  656. |-- agents/ # 72 specialized subagents for delegation
  657. | |-- planner.md # Feature implementation planning
  658. | |-- architect.md # System design decisions
  659. | |-- tdd-guide.md # Test-driven development
  660. | |-- code-reviewer.md # Quality and security review
  661. | |-- security-reviewer.md # Vulnerability analysis
  662. | |-- build-error-resolver.md
  663. | |-- e2e-runner.md # Playwright E2E testing
  664. | |-- refactor-cleaner.md # Dead code cleanup
  665. | |-- doc-updater.md # Documentation sync
  666. | |-- docs-lookup.md # Documentation/API lookup
  667. | |-- chief-of-staff.md # Communication triage and drafts
  668. | |-- loop-operator.md # Autonomous loop execution
  669. | |-- harness-optimizer.md # Harness config tuning
  670. | |-- cpp-reviewer.md # C++ code review
  671. | |-- cpp-build-resolver.md # C++ build error resolution
  672. | |-- fsharp-reviewer.md # F# functional code review
  673. | |-- go-reviewer.md # Go code review
  674. | |-- go-build-resolver.md # Go build error resolution
  675. | |-- python-reviewer.md # Python code review
  676. | |-- database-reviewer.md # Database/Supabase review
  677. | |-- typescript-reviewer.md # TypeScript/JavaScript code review
  678. | |-- java-reviewer.md # Java/Spring Boot code review
  679. | |-- java-build-resolver.md # Java/Maven/Gradle build errors
  680. | |-- kotlin-reviewer.md # Kotlin/Android/KMP code review
  681. | |-- kotlin-build-resolver.md # Kotlin/Gradle build errors
  682. | |-- harmonyos-app-resolver.md # HarmonyOS/ArkTS app development
  683. | |-- ruby-reviewer.md # Ruby/Rails code review
  684. | |-- rust-reviewer.md # Rust code review
  685. | |-- rust-build-resolver.md # Rust build error resolution
  686. | |-- pytorch-build-resolver.md # PyTorch/CUDA training errors
  687. | |-- mle-reviewer.md # Production ML pipeline, eval, serving, and monitoring review
  688. |
  689. |-- skills/ # Workflow definitions and domain knowledge
  690. | |-- coding-standards/ # Language best practices
  691. | |-- clickhouse-io/ # ClickHouse analytics, queries, data engineering
  692. | |-- backend-patterns/ # API, database, caching patterns
  693. | |-- frontend-patterns/ # React, Next.js patterns
  694. | |-- frontend-slides/ # HTML slide decks and PPTX-to-web presentation workflows
  695. | |-- article-writing/ # Long-form writing in a supplied voice without generic AI tone
  696. | |-- content-engine/ # Multi-platform social content and repurposing workflows
  697. | |-- market-research/ # Source-attributed market, competitor, and investor research
  698. | |-- osint-investigation/ # OSINT methodology: competing hypotheses, falsification, visual and evidence verification
  699. | |-- investor-materials/ # Pitch decks, one-pagers, memos, and financial models
  700. | |-- investor-outreach/ # Personalized fundraising outreach and follow-up
  701. | |-- continuous-learning/ # Legacy v1 Stop-hook pattern extraction
  702. | |-- continuous-learning-v2/ # Instinct-based learning with confidence scoring
  703. | |-- iterative-retrieval/ # Progressive context refinement for subagents
  704. | |-- strategic-compact/ # Manual compaction suggestions (Longform Guide)
  705. | |-- tdd-workflow/ # TDD methodology
  706. | |-- security-review/ # Security checklist
  707. | |-- eval-harness/ # Verification loop evaluation (Longform Guide)
  708. | |-- verification-loop/ # Continuous verification (Longform Guide)
  709. | |-- videodb/ # Video and audio: ingest, search, edit, generate, stream
  710. | |-- golang-patterns/ # Go idioms and best practices
  711. | |-- golang-testing/ # Go testing patterns, TDD, benchmarks
  712. | |-- cpp-coding-standards/ # C++ coding standards from C++ Core Guidelines
  713. | |-- cpp-testing/ # C++ testing with GoogleTest, CMake/CTest
  714. | |-- django-patterns/ # Django patterns, models, views
  715. | |-- django-security/ # Django security best practices
  716. | |-- django-tdd/ # Django TDD workflow
  717. | |-- django-verification/ # Django verification loops
  718. | |-- laravel-patterns/ # Laravel architecture patterns
  719. | |-- laravel-security/ # Laravel security best practices
  720. | |-- laravel-tdd/ # Laravel TDD workflow
  721. | |-- laravel-verification/ # Laravel verification loops
  722. | |-- python-patterns/ # Python idioms and best practices
  723. | |-- python-testing/ # Python testing with pytest
  724. | |-- quarkus-patterns/ # Java Quarkus patterns
  725. | |-- quarkus-security/ # Quarkus security
  726. | |-- quarkus-tdd/ # Quarkus TDD
  727. | |-- quarkus-verification/ # Quarkus verification
  728. | |-- rails-patterns/ # Rails architecture patterns
  729. | |-- rails-security/ # Rails security practices
  730. | |-- springboot-patterns/ # Java Spring Boot patterns
  731. | |-- springboot-security/ # Spring Boot security
  732. | |-- springboot-tdd/ # Spring Boot TDD
  733. | |-- springboot-verification/ # Spring Boot verification
  734. | |-- configure-ecc/ # Interactive installation wizard
  735. | |-- security-scan/ # AgentShield security auditor integration
  736. | |-- issue-review/ # GitHub issue review: verify, dedupe, severity, draft reply
  737. | |-- java-coding-standards/ # Java coding standards
  738. | |-- jpa-patterns/ # JPA/Hibernate patterns
  739. | |-- postgres-patterns/ # PostgreSQL optimization patterns
  740. | |-- nutrient-document-processing/ # Document processing with Nutrient API
  741. | |-- database-migrations/ # Migration patterns (Prisma, Drizzle, Django, Go)
  742. | |-- api-design/ # REST API design, pagination, error responses
  743. | |-- deployment-patterns/ # CI/CD, Docker, health checks, rollbacks
  744. | |-- docker-patterns/ # Docker Compose, networking, volumes, container security
  745. | |-- e2e-testing/ # Playwright E2E patterns and Page Object Model
  746. | |-- content-hash-cache-pattern/ # SHA-256 content hash caching for file processing
  747. | |-- cost-aware-llm-pipeline/ # LLM cost optimization, model routing, budget tracking
  748. | |-- regex-vs-llm-structured-text/ # Decision framework: regex vs LLM for text parsing
  749. | |-- swift-actor-persistence/ # Thread-safe Swift data persistence with actors
  750. | |-- swift-protocol-di-testing/ # Protocol-based DI for testable Swift code
  751. | |-- search-first/ # Research-before-coding workflow
  752. | |-- skill-stocktake/ # Audit skills and commands for quality
  753. | |-- liquid-glass-design/ # iOS 26 Liquid Glass design system
  754. | |-- foundation-models-on-device/ # Apple on-device LLM with FoundationModels
  755. | |-- swift-concurrency-6-2/ # Swift 6.2 Approachable Concurrency
  756. | |-- mle-workflow/ # Production ML data contracts, evals, deployment, monitoring
  757. | |-- perl-patterns/ # Modern Perl 5.36+ idioms and best practices
  758. | |-- perl-security/ # Perl security patterns, taint mode, safe I/O
  759. | |-- perl-testing/ # Perl TDD with Test2::V0, prove, Devel::Cover
  760. | |-- autonomous-loops/ # Autonomous loop patterns: sequential pipelines, PR loops, DAG orchestration
  761. | |-- plankton-code-quality/ # Write-time code quality enforcement with Plankton hooks
  762. | |-- codehealth-mcp/ # Optional CodeScene Code Health MCP skill (opt-in)
  763. | |-- docs/examples/project-guidelines-template.md # Template for project-specific skills
  764. |
  765. |-- commands/ # Maintained slash-entry compatibility; prefer skills/
  766. | |-- plan.md # /plan - Implementation planning
  767. | |-- code-review.md # /code-review - Quality review
  768. | |-- issue-review.md # /issue-review - GitHub issue review
  769. | |-- build-fix.md # /build-fix - Fix build errors
  770. | |-- refactor-clean.md # /refactor-clean - Dead code removal
  771. | |-- quality-gate.md # /quality-gate - Verification gate
  772. | |-- learn.md # /learn - Extract patterns mid-session (Longform Guide)
  773. | |-- learn-eval.md # /learn-eval - Extract, evaluate, and save patterns
  774. | |-- checkpoint.md # /checkpoint - Save verification state (Longform Guide)
  775. | |-- setup-pm.md # /setup-pm - Configure package manager
  776. | |-- go-review.md # /go-review - Go code review
  777. | |-- go-test.md # /go-test - Go TDD workflow
  778. | |-- go-build.md # /go-build - Fix Go build errors
  779. | |-- skill-create.md # /skill-create - Generate skills from git history
  780. | |-- instinct-status.md # /instinct-status - View learned instincts
  781. | |-- instinct-import.md # /instinct-import - Import instincts
  782. | |-- instinct-export.md # /instinct-export - Export instincts
  783. | |-- evolve.md # /evolve - Cluster instincts into skills
  784. | |-- prune.md # /prune - Delete expired pending instincts
  785. | |-- pm2.md # /pm2 - PM2 service lifecycle management
  786. | |-- multi-plan.md # /multi-plan - Multi-agent task decomposition
  787. | |-- multi-execute.md # /multi-execute - Orchestrated multi-agent workflows
  788. | |-- multi-backend.md # /multi-backend - Backend multi-service orchestration
  789. | |-- multi-frontend.md # /multi-frontend - Frontend multi-service orchestration
  790. | |-- multi-workflow.md # /multi-workflow - General multi-service workflows
  791. | |-- sessions.md # /sessions - Session history management
  792. | |-- test-coverage.md # /test-coverage - Test coverage analysis
  793. | |-- update-docs.md # /update-docs - Update documentation
  794. | |-- update-codemaps.md # /update-codemaps - Update codemaps
  795. | |-- python-review.md # /python-review - Python code review
  796. |-- legacy-command-shims/ # Opt-in archive for retired shims such as /tdd and /eval
  797. | |-- tdd.md # /tdd - Prefer the tdd-workflow skill
  798. | |-- e2e.md # /e2e - Prefer the e2e-testing skill
  799. | |-- eval.md # /eval - Prefer the eval-harness skill
  800. | |-- verify.md # /verify - Prefer the verification-loop skill
  801. | |-- orchestrate.md # /orchestrate - Prefer dmux-workflows or multi-workflow
  802. |
  803. |-- rules/ # Always-follow guidelines (copy to ~/.claude/rules/ecc/)
  804. | |-- README.md # Structure overview and installation guide
  805. | |-- common/ # Language-agnostic principles
  806. | | |-- coding-style.md # Immutability, file organization
  807. | | |-- git-workflow.md # Commit format, PR process
  808. | | |-- testing.md # TDD, 80% coverage requirement
  809. | | |-- performance.md # Model selection, context management
  810. | | |-- patterns.md # Design patterns, skeleton projects
  811. | | |-- hooks.md # Hook architecture, TodoWrite
  812. | | |-- agents.md # When to delegate to subagents
  813. | | |-- security.md # Mandatory security checks
  814. | |-- typescript/ # TypeScript/JavaScript specific
  815. | |-- python/ # Python specific
  816. | |-- golang/ # Go specific
  817. | |-- swift/ # Swift specific
  818. | |-- php/ # PHP specific
  819. | |-- arkts/ # HarmonyOS / ArkTS specific
  820. |
  821. |-- hooks/ # Trigger-based automations
  822. | |-- README.md # Hook documentation, recipes, and customization guide
  823. | |-- hooks.json # All hooks config (PreToolUse, PostToolUse, Stop, etc.)
  824. | |-- memory-persistence/ # Session lifecycle hooks (Longform Guide)
  825. | |-- strategic-compact/ # Compaction suggestions (Longform Guide)
  826. |
  827. |-- scripts/ # Cross-platform Node.js scripts
  828. | |-- lib/ # Shared utilities
  829. | | |-- utils.js # Cross-platform file/path/system utilities
  830. | | |-- package-manager.js # Package manager detection and selection
  831. | |-- hooks/ # Hook implementations
  832. | | |-- session-start.js # Load context on session start
  833. | | |-- session-end.js # Save state on session end
  834. | | |-- pre-compact.js # Pre-compaction state saving
  835. | | |-- suggest-compact.js # Strategic compaction suggestions
  836. | | |-- context-gate.js # Opt-in checkpoint-and-restart gate at 90% context (ECC_CONTEXT_GATE_MODE=enforce; advisory by default)
  837. | | |-- evaluate-session.js # Extract patterns from sessions
  838. | |-- setup-package-manager.js # Interactive PM setup
  839. |
  840. |-- tests/ # Test suite
  841. | |-- lib/ # Library tests
  842. | |-- hooks/ # Hook tests
  843. | |-- run-all.js # Run all tests
  844. |
  845. |-- contexts/ # Dynamic system prompt injection contexts (Longform Guide)
  846. | |-- dev.md # Development mode context
  847. | |-- review.md # Code review mode context
  848. | |-- research.md # Research/exploration mode context
  849. |
  850. |-- examples/ # Example configurations and sessions
  851. | |-- CLAUDE.md # Example project-level config
  852. | |-- user-CLAUDE.md # Example user-level config
  853. | |-- saas-nextjs-CLAUDE.md # Real-world SaaS (Next.js + Supabase + Stripe)
  854. | |-- go-microservice-CLAUDE.md # Real-world Go microservice (gRPC + PostgreSQL)
  855. | |-- django-api-CLAUDE.md # Real-world Django REST API (DRF + Celery)
  856. | |-- laravel-api-CLAUDE.md # Real-world Laravel API (PostgreSQL + Redis)
  857. | |-- rust-api-CLAUDE.md # Real-world Rust API (Axum + SQLx + PostgreSQL)
  858. |
  859. |-- mcp-configs/ # MCP server configurations
  860. | |-- mcp-servers.json # GitHub, Supabase, Vercel, Railway, etc.
  861. |
  862. |-- ecc_dashboard.py # Desktop GUI dashboard (Tkinter)
  863. |
  864. |-- marketplace.json # Self-hosted marketplace config (for /plugin marketplace add)
  865. ```
  866. </details>
  867. <details>
  868. <summary><strong>Dashboard GUI</strong></summary>
  869. Launch the desktop dashboard to visually explore ECC components:
  870. ```bash
  871. npm run dashboard
  872. # or
  873. python3 ./ecc_dashboard.py
  874. ```
  875. **Features:**
  876. - Tabbed interface: Agents, Skills, Commands, Rules, Settings
  877. - Dark/Light theme toggle
  878. - Font customization (family and size)
  879. - Project logo in header and taskbar
  880. - Search and filter across all components
  881. </details>
  882. ## Key Concepts
  883. <details>
  884. <summary><strong>Agents, skills, hooks, and rules explained</strong></summary>
  885. ### Agents
  886. Subagents handle delegated tasks with limited scope. Example:
  887. ```markdown
  888. ---
  889. name: code-reviewer
  890. description: Reviews code for quality, security, and maintainability
  891. tools: Read, Grep, Glob, Bash
  892. model: opus
  893. ---
  894. You are a senior code reviewer...
  895. ```
  896. ### Skills
  897. 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.
  898. ```markdown
  899. # TDD Workflow
  900. 1. Define interfaces first
  901. 2. Write failing tests (RED)
  902. 3. Implement minimal code (GREEN)
  903. 4. Refactor (IMPROVE)
  904. 5. Verify 80%+ coverage
  905. ```
  906. ### Hooks
  907. Hooks fire on tool events. Example: warn about console.log:
  908. ```json
  909. {
  910. "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"",
  911. "hooks": [{
  912. "type": "command",
  913. "command": "#!/bin/bash\ngrep -n 'console\\.log' \"$file_path\" && echo '[Hook] Remove console.log' >&2"
  914. }]
  915. }
  916. ```
  917. ### Rules
  918. Rules are always-follow guidelines, organized into `common/` (language-agnostic) + language-specific directories:
  919. ```
  920. rules/
  921. common/ # Universal principles (always install)
  922. typescript/ # TS/JS specific patterns and tools
  923. python/ # Python specific patterns and tools
  924. golang/ # Go specific patterns and tools
  925. swift/ # Swift specific patterns and tools
  926. php/ # PHP specific patterns and tools
  927. arkts/ # HarmonyOS / ArkTS patterns and constraints
  928. ```
  929. See [`rules/README.md`](rules/README.md) for installation and structure details.
  930. </details>
  931. ## Guides
  932. This repo is the raw code. The guides explain everything.
  933. <table aria-label="ECC guides" width="100%">
  934. <tr>
  935. <td width="33%" align="center">
  936. <a href="./the-shortform-guide.md">
  937. <img src="assets/images/guides/shorthand-guide.png" width="213" height="120" alt="The Shorthand Guide to ECC" /><br />
  938. <strong>The Shorthand Guide</strong>
  939. </a>
  940. <br /><sub>Setup, foundations, and day-one use. <b>Read this first.</b> (<a href="https://x.com/affaan/status/2012378465664745795">thread</a>)</sub>
  941. </td>
  942. <td width="33%" align="center">
  943. <a href="./the-longform-guide.md">
  944. <img src="assets/images/guides/longform-guide.png" width="213" height="120" alt="The Longform Guide to ECC" /><br />
  945. <strong>The Longform Guide</strong>
  946. </a>
  947. <br /><sub>Context economics, memory, evals, and parallel agents. (<a href="https://x.com/affaan/status/2014040193557471352">thread</a>)</sub>
  948. </td>
  949. <td width="33%" align="center">
  950. <a href="./the-security-guide.md">
  951. <img src="assets/images/guides/security-guide.png" width="213" height="120" alt="The Security Guide to ECC" /><br />
  952. <strong>The Security Guide</strong>
  953. </a>
  954. <br /><sub>Prompt injection, hooks, MCP, and AgentShield. (<a href="https://x.com/affaan/status/2033263813387223421">thread</a>)</sub>
  955. </td>
  956. </tr>
  957. </table>
  958. | Topic | What You'll Learn |
  959. |-------|-------------------|
  960. | Token Optimization | Model selection, system prompt slimming, background processes |
  961. | Memory Persistence | Hooks that save/load context across sessions automatically |
  962. | Continuous Learning | Auto-extract patterns from sessions into reusable skills |
  963. | Verification Loops | Checkpoint vs continuous evals, grader types, pass@k metrics |
  964. | Parallelization | Git worktrees, cascade method, when to scale instances |
  965. | Subagent Orchestration | The context problem, iterative retrieval pattern |
  966. [Commands Quick Reference](./COMMANDS-QUICK-REF.md) | [Manual Adaptation Guide](docs/MANUAL-ADAPTATION-GUIDE.md) | [Astra Review Guide](docs/ASTRA-REVIEW-GUIDE.md) | [Troubleshooting FAQ](./TROUBLESHOOTING.md) | [Roadmap](docs/ROADMAP.md)
  967. ## Why Choose ECC?
  968. | Without a system | With ECC |
  969. | ------------------------------------------------------- | --------------------------------------------------------------------- |
  970. | Plans disappear into chat history | Plans become editable artifacts before implementation starts |
  971. | "Please use TDD" is an instruction the model may forget | TDD becomes a gated RED -> GREEN -> REFACTOR workflow with evidence |
  972. | The same context writes and reviews the code | A fresh-context reviewer looks for regressions and blind spots |
  973. | Memory means saving an enormous transcript | Sessions are distilled into summaries, instincts, and reusable skills |
  974. | Quality checks depend on reminders | Hooks can enforce deterministic checks outside the prompt |
  975. | Agent configuration is trusted by default | AgentShield scans the harness itself as an attack surface |
  976. ### TDD: Test-Driven Development
  977. ```text
  978. /ecc:plan "Add usage-based billing alerts"
  979. -> confirm or edit the plan
  980. -> activate tdd-workflow
  981. -> capture RED evidence before implementation
  982. -> implement until GREEN
  983. -> review from fresh context
  984. -> fix findings with regression tests
  985. -> verify build, lint, types, and tests
  986. ```
  987. A result is not just code. It's a trail of evidence: the plan, the failing test, the passing test, the review findings, and the final verification.
  988. ### Skills keep the context focused
  989. Rules, skills, agents, and hooks solve different problems. Keeping those jobs separate is how ECC adds capability without dumping the entire repository into every session.
  990. | Concept | What it does | Context behavior |
  991. |---|---|---|
  992. | Skills | Reusable workflows such as TDD, security review, or deep research | Loaded when the task needs them |
  993. | Agents | Scoped workers with their own context and tool permissions | Isolate planning, implementation, and review |
  994. | Rules | Durable project or language standards | Always loaded, so install them selectively |
  995. | Hooks | Scripts triggered by harness events | Run outside the model context |
  996. | Instincts | Patterns learned from real sessions with confidence scores | Recalled when relevant |
  997. ### Share context between harnesses
  998. ECC's Memory Vault gives Claude, Codex, Hermes, OpenClaw, Kimi, and other harnesses one local, inspectable Markdown format for durable context and handoffs. Project and team memories live under `.ecc/memory/`; user memories live under `~/.ecc/memory/`.
  999. Skill-only, minimal, manual, and Claude plugin installs do not put the Memory Vault runtime on `PATH`. Install the npm runtime separately before using the CLI or optional MCP server:
  1000. ```bash
  1001. npm install -g ecc-universal@2.2.3
  1002. ecc memory init --scope project
  1003. ecc memory search "authentication migration" --target-harness codex
  1004. ecc memory doctor
  1005. ```
  1006. Memory is unreviewed context, not executable policy. Verify important claims against authoritative sources and promote accepted knowledge into governed project documentation. The optional `ecc-memory-mcp` server exposes the same bounded save, search, read, and doctor surface without enabling itself by default.
  1007. [Open the Unified Memory workflow →](skills/unified-memory/SKILL.md)
  1008. <details>
  1009. <summary><strong>Memory Vault in depth: scopes, handoffs, and trust boundaries</strong></summary>
  1010. 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.
  1011. After installing the runtime above, check that the CLI and optional MCP entry point are available:
  1012. ```bash
  1013. ecc memory --help
  1014. command -v ecc-memory-mcp
  1015. ```
  1016. ```bash
  1017. # Initialize the project vault.
  1018. ecc memory init --scope project
  1019. # Write a handoff body to a regular file, then target the next harness.
  1020. ecc memory handoff \
  1021. --from hermes \
  1022. --target codex \
  1023. --title "Continue authentication migration" \
  1024. --body-file ./handoff.md
  1025. # Recall it from another harness.
  1026. ecc memory search "authentication migration" --target-harness codex
  1027. ecc memory read <memory-id>
  1028. # Validate the vault before sharing team memories.
  1029. ecc memory doctor
  1030. ```
  1031. 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.
  1032. For opt-in MCP access, add the `ecc-memory-vault` entry from [`mcp-configs/mcp-servers.json`](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`](skills/unified-memory/SKILL.md) for the workflow and trust boundaries, and [`docs/design/ecc-memory-vault.md`](docs/design/ecc-memory-vault.md) for the capability contract.
  1033. </details>
  1034. ## Platform Support
  1035. ECC's core Node.js CLI and managed installers run on **Windows, macOS, and Linux**, but optional capabilities are not at full parity. Some continuous-learning, GAN, and orchestration paths still require Bash or Python; harnesses also expose different hook, agent, and skill APIs.
  1036. | Platform | Status | Current limitation |
  1037. |---|---|---|
  1038. | Linux | Supported core | Optional features may require Bash, Python, or provider-specific tools. |
  1039. | macOS | Supported core | The standalone GAN shell path is not compatible with the system Bash 3.2 and currently has a score-parsing defect ([#2674](https://github.com/affaan-m/ECC/issues/2674)). |
  1040. | Windows + WSL | Supported core | WSL follows the Linux paths; Windows host integrations still vary by harness. |
  1041. | Windows native | Supported with limitations | Continuous-learning v2's observer daemon and memory-vault writes have open native-Windows defects ([#2489](https://github.com/affaan-m/ECC/issues/2489), [#2626](https://github.com/affaan-m/ECC/issues/2626)). Shell-backed optional features require Git Bash/WSL or are unavailable. |
  1042. Treat `stable`, `beta`, `experimental`, and `instruction-only` below as capability statements, not marketing tiers.
  1043. | Harness | Status | Recommended distribution | Important limitation |
  1044. |---|---|---|---|
  1045. | Claude Code | Stable primary | Plugin or selective installer | The plugin advertises the installed catalog to the model; use a selective/manual profile when context footprint matters. Optional shell-backed skills are not portable to every OS. |
  1046. | Codex | Supported native plugin | Codex marketplace plugin or repo config | Native hooks require an explicit trust decision and do not use Claude's hook profiles. The legacy sync is compatibility-only. |
  1047. | Antigravity | Experimental native plugin adapter | Antigravity 2.0/IDE plugin (`~/.gemini/config/plugins/ecc`) or project `.agents/` | Profile-gated lifecycle hooks, rules, workflows, skills, and memory MCP. CLI 1.3.5 validates local import; authenticated native tool and Stop execution remain unverified. |
  1048. | Qoder | Supported native plugin | Local plugin directory in Qoder CLI or ZIP upload in Qoder IDE | Loads the canonical skills, agents, commands, and MCP config; only the reviewed SessionStart hook is enabled, and Node.js 18+ must be on the non-interactive PATH. |
  1049. | Cursor | Beta project adapter | Selective installer into `.cursor/` | Agent discovery varies by Cursor build; hook events use profile-gated dispatchers, but full Claude feature parity is not claimed. |
  1050. | OpenCode | Beta built plugin | Build plugin, then selective installer | ECC ships a subset of the catalog; connect a provider and select a model in OpenCode ([#2617](https://github.com/affaan-m/ECC/issues/2617)). |
  1051. | GitHub Copilot Chat | Instruction-only | Checked-in instructions and prompt files | ECC hooks are not adapted. |
  1052. | GitHub Copilot CLI | Beta project adapter | `--target copilot` places skills, adapted agents, and converted rules in `.github/` | ECC hooks and command shims are not installed by this target. |
  1053. | Gemini, Zed, Qwen, Hermes, OpenClaw, Kimi, Mistral Vibe, CodeBuddy, JoyCode | Experimental/minimal adapters | Harness-specific selective target | File placement and instruction portability are tested; full Claude feature parity is not claimed. |
  1054. <details>
  1055. <summary><strong>Package manager detection</strong></summary>
  1056. The plugin automatically detects your preferred package manager (npm, pnpm, yarn, or bun) with the following priority:
  1057. 1. **Environment variable**: `CLAUDE_PACKAGE_MANAGER`
  1058. 2. **Project config**: `.claude/package-manager.json`
  1059. 3. **package.json**: `packageManager` field
  1060. 4. **Lock file**: Detection from package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb
  1061. 5. **Global config**: `~/.claude/package-manager.json`
  1062. 6. **Fallback**: npm
  1063. To set your preferred package manager:
  1064. ```bash
  1065. # Via environment variable
  1066. export CLAUDE_PACKAGE_MANAGER=pnpm
  1067. # Via global config
  1068. node scripts/setup-package-manager.js --global pnpm
  1069. # Via project config
  1070. node scripts/setup-package-manager.js --project bun
  1071. # Detect current setting
  1072. node scripts/setup-package-manager.js --detect
  1073. ```
  1074. Or use the `/setup-pm` command.
  1075. </details>
  1076. <details>
  1077. <summary><strong>Hook runtime controls (env vars)</strong></summary>
  1078. Use runtime flags to tune strictness or disable specific hooks temporarily:
  1079. ```bash
  1080. # Hook strictness profile (default: standard)
  1081. export ECC_HOOK_PROFILE=standard
  1082. # Comma-separated hook IDs to disable
  1083. export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
  1084. # Cap SessionStart additional context (default: 8000 chars)
  1085. export ECC_SESSION_START_MAX_CHARS=4000
  1086. # Disable SessionStart additional context entirely for low-context/local-model setups
  1087. export ECC_SESSION_START_CONTEXT=off
  1088. # Session-tmp retention window in days (default: 30).
  1089. # Set to 0, off, false, disabled, never, or none to keep all sessions (disable pruning).
  1090. export ECC_SESSION_RETENTION_DAYS=14
  1091. # Cap how many learned instincts SessionStart injects into context (default: 6)
  1092. export ECC_MAX_INJECTED_INSTINCTS=6
  1093. # Minimum confidence an instinct needs to be injected, 0-1 (default: 0.7)
  1094. export ECC_INSTINCT_CONFIDENCE_THRESHOLD=0.7
  1095. # SessionStart ranks injected instincts by confidence + project/stack relevance
  1096. # (default: on). Project-scoped instincts, and instincts whose domain/trigger
  1097. # matches the detected stack (languages, frameworks, plus terraform/dbt markers),
  1098. # get a small ranking boost so they surface above unrelated higher-confidence
  1099. # ones. Set to off/false/0/no to rank by confidence alone.
  1100. export ECC_INSTINCT_RELEVANCE_RANKING=on
  1101. # Keep context/scope/loop warnings but suppress API-rate cost estimates
  1102. export ECC_CONTEXT_MONITOR_COST_WARNINGS=off
  1103. ```
  1104. Windows PowerShell:
  1105. ```powershell
  1106. [Environment]::SetEnvironmentVariable('ECC_CONTEXT_MONITOR_COST_WARNINGS', 'off', 'User')
  1107. [Environment]::SetEnvironmentVariable('ECC_SESSION_RETENTION_DAYS', '14', 'User')
  1108. ```
  1109. </details>
  1110. <details>
  1111. <summary><strong>Agent data home (multi-harness isolation)</strong></summary>
  1112. 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:
  1113. ```bash
  1114. # Cursor-only boundary (Claude Code keeps the default ~/.claude)
  1115. export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc"
  1116. ```
  1117. Paths resolved under that root include:
  1118. - `$ECC_AGENT_DATA_HOME/session-data/`: session summaries
  1119. - `$ECC_AGENT_DATA_HOME/skills/learned/`: learned skills from evaluate-session
  1120. - `$ECC_AGENT_DATA_HOME/session-aliases.json`: session aliases
  1121. - `$ECC_AGENT_DATA_HOME/metrics/`: cost and activity metrics
  1122. See [affaan-m/ECC#2065](https://github.com/affaan-m/ECC/issues/2065).
  1123. </details>
  1124. <details>
  1125. <summary><strong>Cross-tool capability map and per-harness notes</strong></summary>
  1126. ### Cross-tool capability map
  1127. | Capability | Claude Code | Codex | Cursor | OpenCode | GitHub Copilot |
  1128. |---|---|---|---|---|---|
  1129. | Instructions | Native | Native `AGENTS.md` | Project rules | Plugin instructions | Native instruction file |
  1130. | Skills | Native installed set | Native plugin set | Build-dependent/project set | Built subset | Native discovery (Copilot CLI) from `.github/skills/`, `.agents/skills/`, `.claude/skills/` |
  1131. | Agents/delegation | Native agents | Codex multi-agent roles; Claude agent files are not installed as roles | Build-dependent project agents | Plugin agents | Copilot CLI custom agents via `.github/agents/` and `--agent` |
  1132. | ECC hooks | Native plugin hooks | Native reviewed subset with explicit trust | Cursor hook adapter; install-path differences remain | Plugin events | Not ported; Copilot CLI has its own plugin hook system |
  1133. | MCP configuration | Available, explicit activation | Native plugin manifest; legacy sync can merge TOML | Explicit project/user config | Provider/plugin config | Not supplied by ECC |
  1134. | Parity with Claude Code | Primary reference | Partial | Partial | Partial | Partial |
  1135. **Key architectural decisions:**
  1136. - **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)
  1137. - **DRY adapter pattern** lets Cursor reuse Claude Code's hook scripts without duplication
  1138. - **Skills format** (SKILL.md with YAML frontmatter) works across Claude Code, Codex, OpenCode, and GitHub Copilot CLI
  1139. - Codex's narrower native hook set is supplemented by `AGENTS.md`, optional `model_instructions_file` overrides, and sandbox permissions
  1140. <details>
  1141. <summary><strong>Cursor IDE support in depth</strong></summary>
  1142. ECC provides Cursor IDE support with hooks, rules, agents, skills, commands, and MCP configs adapted for Cursor's project layout.
  1143. ```bash
  1144. # macOS/Linux
  1145. ./install.sh --target cursor typescript
  1146. ./install.sh --target cursor python golang swift php
  1147. ```
  1148. ```powershell
  1149. # Windows PowerShell
  1150. .\install.ps1 --target cursor typescript
  1151. .\install.ps1 --target cursor python golang swift php
  1152. ```
  1153. #### What's included for Cursor
  1154. | Component | Count | Details |
  1155. |-----------|-------|---------|
  1156. | Hook Events | 15 | sessionStart, beforeShellExecution, afterFileEdit, beforeMCPExecution, beforeSubmitPrompt, and 10 more |
  1157. | Hook Entrypoints | 15 | Thin Node.js event dispatchers delegating to `scripts/hooks/` via shared adapter |
  1158. | Rules | 34 | 9 common (alwaysApply) + 25 language-specific (TypeScript, Python, Go, Swift, PHP) |
  1159. | Agents | 48 | `.cursor/agents/ecc-*.md` when installed; prefixed to avoid collisions with user or marketplace agents |
  1160. | Skills | Shared + Bundled | `.cursor/skills/` for translated additions |
  1161. | Commands | Shared | `.cursor/commands/` if installed |
  1162. | MCP Config | Shared | `.cursor/mcp.json` if installed |
  1163. #### Cursor loading notes
  1164. ECC does not install root `AGENTS.md` into `.cursor/`. Cursor treats nested `AGENTS.md` files as directory context, so copying ECC's repo identity into a host project would pollute that project.
  1165. Cursor-native loading behavior can vary by Cursor build. ECC installs agents as `.cursor/agents/ecc-*.md`; if your Cursor build does not expose project agents, those files still work as explicit reference definitions instead of hidden global prompt context.
  1166. #### Memory and data isolation (Cursor + Claude Code)
  1167. ECC memory hooks reuse the same `scripts/hooks/*.js` as Claude Code. For Cursor, ECC tries to keep memory **out of `~/.claude` automatically**:
  1168. 1. **Cursor `sessionStart` hook** (installed to `.cursor/hooks.json` on `--target cursor`) injects `ECC_AGENT_DATA_HOME` for the whole composer session.
  1169. 2. **Hook runtime default**: when `CURSOR_VERSION` or `CURSOR_PROJECT_DIR` is present, hooks default to `~/.cursor/ecc` if the env var is unset.
  1170. 3. **Project config**: `.cursor/ecc-agent-data.json` documents and overrides the path (`agentDataHome`).
  1171. 4. **Always-on rule**: `.cursor/rules/ecc-agent-data-home.mdc` reminds the agent where memory lives.
  1172. You can still override explicitly:
  1173. ```bash
  1174. export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc"
  1175. ```
  1176. To **share** memory with Claude Code on purpose, set `ECC_AGENT_DATA_HOME=~/.claude` in the shell or in `.cursor/ecc-agent-data.json`.
  1177. Continuous learning v2 instincts remain separate under `CLV2_HOMUNCULUS_DIR` (default `~/.local/share/ecc-homunculus`).
  1178. #### Hook architecture (DRY adapter pattern)
  1179. Cursor has **more hook events than Claude Code** (20 vs 8). The `.cursor/hooks/adapter.js` module transforms Cursor's stdin JSON to Claude Code's format, allowing existing `scripts/hooks/*.js` to be reused without duplication. Each Cursor event is registered with one event-level dispatcher so enabled checks run in a deterministic order and remain compatible with Cursor versions that execute only the first matching entry. The adapter resolves the shared runtime from both the ECC checkout and an installed project's `.cursor/scripts/` tree.
  1180. ```
  1181. Cursor stdin JSON -> adapter.js -> transforms -> scripts/hooks/*.js
  1182. (shared with Claude Code)
  1183. ```
  1184. Key hooks:
  1185. - **beforeShellExecution**: Blocks git hook bypasses and dev servers outside tmux (exit 2), then adds profile-gated shell reminders
  1186. - **afterFileEdit / stop**: Accumulates edited JS/TS files and runs one profile-gated format/typecheck batch at Stop, alongside the console.log audit
  1187. - **beforeSubmitPrompt**: Detects secrets (sk-, ghp_, AKIA patterns) in prompts
  1188. - **beforeTabFileRead**: Blocks Tab from reading .env, .key, .pem files (exit 2)
  1189. - **beforeMCPExecution / afterMCPExecution**: MCP audit logging
  1190. #### Rules format
  1191. Cursor rules use YAML frontmatter with `description`, `globs`, and `alwaysApply`:
  1192. ```yaml
  1193. ---
  1194. description: "TypeScript coding style extending common rules"
  1195. globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
  1196. alwaysApply: false
  1197. ---
  1198. ```
  1199. </details>
  1200. <details>
  1201. <summary><strong>Codex macOS app + CLI support in depth</strong></summary>
  1202. ECC provides a supported native Codex marketplace plugin and repo-local configuration for the macOS app and CLI. The native plugin carries shared skills, MCP configuration, and a reviewed hook subset; Codex keeps hook trust under explicit user control. The older sync path remains compatibility-only. For repo navigation, surface ownership, and PR diff packet guidance, start with [`docs/CODEX-NAVIGATION-GUIDE.md`](docs/CODEX-NAVIGATION-GUIDE.md).
  1203. ```bash
  1204. # Recommended current install: add ECC's native plugin from the repo marketplace
  1205. codex plugin marketplace add affaan-m/ECC
  1206. codex plugin add ecc@ecc
  1207. codex plugin list --json
  1208. # Or run Codex CLI in the repo: AGENTS.md and .codex/ are auto-detected
  1209. codex
  1210. ```
  1211. Legacy copied-configuration compatibility is still available when you intentionally need it:
  1212. ```bash
  1213. # Compatibility-only managed sync into ~/.codex
  1214. npm install && bash scripts/sync-ecc-to-codex.sh
  1215. # Or copy only the reference config manually
  1216. cp .codex/config.toml ~/.codex/config.toml
  1217. ```
  1218. Normal MCP sync preserves existing server settings and warns when they differ from ECC's recommendation. An existing `chrome-devtools-mcp@latest` entry therefore stays unchanged; updating the repository alone does not adopt the recommended `chrome-devtools-mcp@1.10.1` pin. Existing legacy-sync users can preview and explicitly apply the refresh from the updated ECC checkout:
  1219. ```bash
  1220. bash scripts/sync-ecc-to-codex.sh --dry-run --update-mcp
  1221. bash scripts/sync-ecc-to-codex.sh --update-mcp
  1222. ```
  1223. Review the preview before applying: `--update-mcp` replaces the entire recommended `chrome-devtools` server section, including custom command arguments and nested settings. Unrelated user-managed servers remain in place. Retired defaults such as Context7 are not refreshed or migrated by this flag.
  1224. Codex macOS app:
  1225. - Open this repository as your workspace.
  1226. - The root `AGENTS.md` is auto-detected.
  1227. - `.codex/config.toml` and `.codex/agents/*.toml` work best when kept project-local.
  1228. - The reference `.codex/config.toml` intentionally does not pin `model` or `model_provider`, so Codex uses its own current default unless you override it.
  1229. - Optional: copy `.codex/config.toml` to `~/.codex/config.toml` for global defaults; keep the multi-agent role files project-local unless you also copy `.codex/agents/`.
  1230. #### What's included in the repo and legacy configuration layer
  1231. | Component | Count | Details |
  1232. |-----------|-------|---------|
  1233. | Config | 1 | `.codex/config.toml`: top-level approvals/sandbox/web_search, MCP servers, notifications, profiles |
  1234. | AGENTS.md | 2 | Root (universal) + `.codex/AGENTS.md` (Codex-specific supplement) |
  1235. | Skills | 32 | `.agents/skills/`: SKILL.md + agents/openai.yaml per skill |
  1236. | MCP Servers | 6 legacy reference entries | GitHub, Context7, Exa, Memory, Playwright, Sequential Thinking. Current managed sync recommends `chrome-devtools`; see the explicit refresh instructions above. |
  1237. | Profiles | 2 | `strict` (read-only sandbox) and `yolo` (full auto-approve) |
  1238. | Agent Roles | 3 | `.codex/agents/`: explorer, reviewer, docs-researcher |
  1239. Skills at `.agents/skills/` are auto-loaded by Codex. Canonical Anthropic skills such as `claude-api`, `frontend-design`, and `skill-creator` are intentionally not re-bundled here. Install those from [`anthropics/skills`](https://github.com/anthropics/skills) when you want the official versions.
  1240. #### Key limitation
  1241. Codex does **not provide Claude-style hook execution parity**. The native ECC plugin includes a reviewed hook subset that requires explicit trust in `/hooks`; `AGENTS.md`, optional `model_instructions_file` overrides, and sandbox/approval settings provide the remaining instruction and policy layers.
  1242. #### Multi-agent support
  1243. Current Codex builds support stable multi-agent workflows.
  1244. - Enable `features.multi_agent = true` in `.codex/config.toml`
  1245. - Define roles under `[agents.<name>]`
  1246. - Point each role at a file under `.codex/agents/`
  1247. - Use `/agent` in the CLI to inspect or steer child agents
  1248. ECC ships three sample role configs:
  1249. | Role | Purpose |
  1250. |------|---------|
  1251. | `explorer` | Read-only codebase evidence gathering before edits |
  1252. | `reviewer` | Correctness, security, and missing-test review |
  1253. | `docs_researcher` | Documentation and API verification before release/docs changes |
  1254. </details>
  1255. <details>
  1256. <summary><strong>Zed support</strong></summary>
  1257. ECC provides Zed project support through a conservative `.zed` adapter for project-local settings, flattened rules, agents, commands, and skills.
  1258. ```bash
  1259. ./install.sh --profile minimal --target zed
  1260. ```
  1261. ```powershell
  1262. .\install.ps1 --profile minimal --target zed
  1263. ```
  1264. The adapter writes ECC-managed files under `.zed/` and keeps BYOK/OpenRouter credentials out of the repo. Configure Zed account or API keys through Zed's own settings UI or your local user settings.
  1265. </details>
  1266. <details>
  1267. <summary><strong>OpenCode support in depth</strong></summary>
  1268. ECC provides a beta OpenCode plugin integration with instructions, a catalog subset, commands, custom tools, and hook events. It does not provide feature parity with Claude Code. The reference config inherits the user's OpenCode model selection instead of pinning a provider-specific model.
  1269. ```bash
  1270. # Run your reviewed OpenCode installation in the repository root
  1271. opencode
  1272. ```
  1273. For installation, use the [official OpenCode instructions](https://opencode.ai/docs/), select an exact release, and verify it before execution. The upstream npm package is `opencode-ai`, not `opencode`. ECC does not attest to an audited OpenCode runtime version.
  1274. The configuration is automatically detected from `.opencode/opencode.json`.
  1275. #### Hook support via plugins
  1276. OpenCode's plugin system has 20+ event types:
  1277. | Claude Code Hook | OpenCode Plugin Event |
  1278. |-----------------|----------------------|
  1279. | PreToolUse | `tool.execute.before` |
  1280. | PostToolUse | `tool.execute.after` |
  1281. | Stop | `session.idle` |
  1282. | SessionStart | `session.created` |
  1283. | SessionEnd | `session.deleted` |
  1284. **Additional OpenCode events**: `file.edited`, `file.watcher.updated`, `message.updated`, `lsp.client.diagnostics`, `tui.toast.show`, and more.
  1285. #### Plugin installation
  1286. **Option 1: Use directly**
  1287. ```bash
  1288. cd ECC
  1289. opencode
  1290. ```
  1291. **Option 2: Install as npm package**
  1292. ```bash
  1293. npm install ecc-universal@2.2.3
  1294. ```
  1295. Then add to your `opencode.json`:
  1296. ```json
  1297. {
  1298. "plugin": ["ecc-universal"]
  1299. }
  1300. ```
  1301. That npm plugin entry enables ECC's published OpenCode plugin module (hooks/events and plugin tools). It does **not** automatically add ECC's full command/agent/instruction catalog to your project config.
  1302. For the full ECC OpenCode setup, either:
  1303. - run OpenCode inside this repository, or
  1304. - copy the bundled `.opencode/` config assets into your project and wire the `instructions`, `agent`, and `command` entries in `opencode.json`
  1305. #### Documentation
  1306. - **Migration Guide**: `.opencode/MIGRATION.md`
  1307. - **OpenCode Plugin README**: `.opencode/README.md`
  1308. - **Consolidated Rules**: `.opencode/instructions/INSTRUCTIONS.md`
  1309. - **LLM Documentation**: `llms.txt` (complete OpenCode docs for LLMs)
  1310. </details>
  1311. <details>
  1312. <summary><strong>GitHub Copilot support in depth</strong></summary>
  1313. ECC supports **GitHub Copilot** on two surfaces: Copilot Chat in VS Code, via its native instruction and prompt file system, and **GitHub Copilot CLI**, which discovers the shared skills already present in this repository. The optional `copilot` install target places canonical skills and adapted agents in the CLI's native project directories.
  1314. #### What's included for GitHub Copilot
  1315. | Component | File | Purpose |
  1316. |-----------|------|---------|
  1317. | Core instructions | `.github/copilot-instructions.md` | Always-loaded rules: coding style, security, testing, git workflow |
  1318. | VS Code settings | `.vscode/settings.json` | Per-task instruction files for code gen, test gen, and commit messages |
  1319. | Plan prompt | `.github/prompts/plan.prompt.md` | Phased implementation planning |
  1320. | TDD prompt | `.github/prompts/tdd.prompt.md` | Red-Green-Improve cycle |
  1321. | Security review prompt | `.github/prompts/security-review.prompt.md` | Deep OWASP-aligned security analysis |
  1322. | Build fix prompt | `.github/prompts/build-fix.prompt.md` | Systematic build and CI error resolution |
  1323. | Refactor prompt | `.github/prompts/refactor.prompt.md` | Dead code cleanup and simplification |
  1324. The files are already in place: open any repo that contains this project and GitHub Copilot Chat will automatically pick up `.github/copilot-instructions.md`. The committed `.vscode/settings.json` enables `chat.promptFiles` so VS Code can load the reusable prompts from `.github/prompts/`.
  1325. To use the workflow prompts in Copilot Chat:
  1326. 1. Open the Copilot Chat panel in VS Code.
  1327. 2. Click the **paperclip / attach** icon and select **Prompt...**, or type `/` and choose a prompt.
  1328. 3. Select the prompt (e.g. `plan`, `tdd`, `security-review`).
  1329. #### Copilot CLI: skills and agents
  1330. GitHub Copilot CLI discovers `SKILL.md` skills from `.github/skills/`,
  1331. `.agents/skills/`, `.claude/skills/`, `~/.copilot/skills/`, and
  1332. `~/.agents/skills/`, and custom agents from `.github/agents/`. ECC's skill and
  1333. skill frontmatter is compatible. The managed `copilot` target adapts agent
  1334. frontmatter to `name` and `description`, removing Claude-specific model and
  1335. tool keys. Raw manual agent copies can retain unsupported metadata.
  1336. Because ECC ships a skill subset in `.agents/skills/`, a plain clone of this
  1337. repository is picked up by Copilot CLI with no configuration at all:
  1338. ```bash
  1339. git clone https://github.com/affaan-m/ECC.git && cd ECC
  1340. copilot skill list
  1341. # The inventory depends on the checkout and CLI version.
  1342. ```
  1343. In the contributor's September 2026 checkout, Copilot CLI 1.0.83 reported all 42 under `Project skills` with `source:
  1344. "project"` and `enabled: true`. The three from `.claude/commands/` are Claude
  1345. command files that Copilot surfaces as skills; they are reported with `path`
  1346. set to the `.claude/commands` directory rather than to a per-skill subdirectory.
  1347. To check this with a temporary npm-distributed CLI, run the pinned build
  1348. against a throwaway clone:
  1349. ```bash
  1350. git clone --depth 1 https://github.com/affaan-m/ECC.git && cd ECC
  1351. npx -y @github/copilot@1.0.82 skill list --json | jq '[.[] | select(.source=="project")] | length'
  1352. # Count the current inventory rather than assuming a fixed total.
  1353. ```
  1354. That checkout's 39 + 3 split was reported by 1.0.82 from npm and by 1.0.83 installed
  1355. locally, so the behaviour is not specific to one build or install method.
  1356. To expose the full catalog, place `skills/` where Copilot CLI looks:
  1357. ```bash
  1358. mkdir -p .github/skills
  1359. cp -r skills/. .github/skills/
  1360. copilot skill list --json > copilot-skills.json
  1361. jq '[.[] | select(.path | contains(".github/skills"))] | length' copilot-skills.json
  1362. # Compare with the current canonical skill catalog.
  1363. ```
  1364. Filter on the path rather than on `source`: the CLI can also discover skills
  1365. from other project locations and de-duplicates entries with the same skill
  1366. name. Counts depend on the checkout and CLI version. The file redirection also
  1367. avoids truncated large JSON output observed with Copilot CLI 1.0.82 on macOS.
  1368. Copilot registers a skill under the `name` in its `SKILL.md` frontmatter, not
  1369. its directory name, so catalog folders whose names differ from their frontmatter
  1370. (for example `scientific-db-pubmed-database`, which declares
  1371. `name: pubmed-database`) still load — they are just listed under the frontmatter
  1372. name.
  1373. Agents work the same way:
  1374. ```bash
  1375. ./install.sh --profile full --target copilot
  1376. copilot --agent architect -p "Review this module's boundaries"
  1377. ```
  1378. The contributor verified native discovery with Copilot CLI 1.0.83. Manually
  1379. copied agent files that declare a Claude model
  1380. name (`model: opus`, `model: sonnet`) emit a warning and fall back to the
  1381. session's default model, so remove or remap `model:` if you want to pin one.
  1382. #### Installing with the `copilot` target
  1383. The steps above copy files by hand. The `copilot` install target does the same
  1384. placement and additionally rewrites agent frontmatter so no warning is emitted:
  1385. ```bash
  1386. ./install.sh --profile full --target copilot
  1387. # Windows: ./install.ps1 --profile full --target copilot
  1388. ```
  1389. That writes skills to `.github/skills/`, agents to `.github/agents/`, and an
  1390. install-state file to `.github/ecc-install-state.json`. Nothing is written
  1391. outside `.github/`.
  1392. The `full` profile selects the modules declared for Copilot. It can place fewer
  1393. skills than a manual copy of the entire canonical catalog because modules
  1394. that require another host's runtime are excluded. List the resulting native
  1395. inventory to see what this checkout installs; a count is not a capability grant.
  1396. Claude-only agent frontmatter (`model`, `tools`, `color`) is dropped during the
  1397. copy: Copilot resolves the model from your own configuration, and it governs
  1398. tool access per session through `--allow-tool`/`--deny-tool` rather than through
  1399. agent frontmatter. Rules are installed under `.github/instructions/ecc/` as
  1400. `.instructions.md` files, with the Claude-style `paths:` frontmatter converted
  1401. to Copilot's `applyTo:` glob list (rules without `paths` become `applyTo:
  1402. "**"`). ECC's commands and hooks are not installed by this target.
  1403. #### Feature coverage
  1404. | ECC Feature | Copilot equivalent |
  1405. |-------------|-------------------|
  1406. | Coding standards | Always-on via `copilot-instructions.md` |
  1407. | Security checklist | Always-on + `security-review` prompt |
  1408. | Testing / TDD | Always-on + `tdd` prompt |
  1409. | Implementation planning | `plan` prompt |
  1410. | Code review | External PR review via CodeRabbit + Greptile |
  1411. | Build error resolution | `build-fix` prompt |
  1412. | Refactoring | `refactor` prompt |
  1413. | Commit message format | Per-task instruction in `settings.json` |
  1414. | Skills | Native discovery in Copilot CLI (`.github/skills/`, `.agents/skills/`) |
  1415. | Agents / delegation | Copilot CLI custom agents (`.github/agents/`, `--agent`) |
  1416. | Rules | Path-specific instructions (`.github/instructions/ecc/`, `applyTo:` globs) |
  1417. | Hooks / automation | ECC's hooks are not ported (Copilot CLI has its own plugin hook system) |
  1418. #### Limitations
  1419. ECC's hook automations (auto-format, TypeScript check, session persistence,
  1420. dev-server guard) are written against Claude Code's hook event model and are
  1421. not ported to Copilot. Copilot CLI does expose a hook system through its plugin
  1422. format, but ECC does not currently ship a Copilot plugin, so none of ECC's hooks
  1423. run there.
  1424. ECC also does not install rules, commands, or hooks for Copilot. The `copilot`
  1425. target installs skills and agents only. Skills that shell out to bundled
  1426. scripts assume the same interpreters as on Claude Code. Copilot Chat in VS Code
  1427. does not read `.github/skills/` or `.github/agents/`; those paths are Copilot
  1428. CLI surfaces. The instruction and prompt layer is what carries ECC's coding
  1429. philosophy into Copilot Chat sessions.
  1430. </details>
  1431. <details>
  1432. <summary><strong>What changed in v2.0.0</strong></summary>
  1433. ECC v2.0.0 stabilizes the 2.0 line with the public Hermes operator story, 281 skills, 67 agents, 94 command shims, session adapters, MCP inventory, worktree lifecycle services, orchestrator workflows, and the ECC Discord community.
  1434. - [v2.0.0 release notes](docs/releases/2.0.0/release-notes.md)
  1435. - [ECC 2.0 reference architecture](docs/ECC-2.0-REFERENCE-ARCHITECTURE.md)
  1436. - [Hermes setup guide](docs/HERMES-SETUP.md)
  1437. - [Migration guide from 1.x](docs/MIGRATION-1X-TO-2.0.md)
  1438. </details>
  1439. </details>
  1440. ## Token Optimization
  1441. Agent usage can be expensive if you don't manage token consumption. These settings significantly reduce costs without sacrificing quality. Full guide: [docs/token-optimization.md](docs/token-optimization.md).
  1442. <details>
  1443. <summary><strong>Recommended settings</strong></summary>
  1444. Add to `~/.claude/settings.json`:
  1445. ```json
  1446. {
  1447. "model": "sonnet",
  1448. "env": {
  1449. "CLAUDE_CODE_EFFORT_LEVEL": "medium",
  1450. "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
  1451. "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  1452. }
  1453. }
  1454. ```
  1455. The effort setting requires a model that supports effort controls. On Amazon Bedrock,
  1456. Google Cloud's Agent Platform, and Microsoft Foundry, the `sonnet` alias currently
  1457. resolves to Sonnet 4.5, which does not support effort controls. Select an effort-capable
  1458. model available from your provider, or omit `CLAUDE_CODE_EFFORT_LEVEL`.
  1459. | Setting | Default | Recommended | Impact |
  1460. |---------|---------|-------------|--------|
  1461. | `model` | opus | **sonnet** | ~60% cost reduction; handles 80%+ of coding tasks |
  1462. | `CLAUDE_CODE_EFFORT_LEVEL` | Model-dependent | **medium**, if supported | Controls adaptive reasoning depth on models that support effort controls; lower effort trades reasoning depth for latency and cost |
  1463. | `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 95 | **50** | Compacts earlier, better quality in long sessions |
  1464. | `ECC_CONTEXT_MONITOR_COST_WARNINGS` | on | **off for subscription users** | Suppresses agent-facing API-rate estimate warnings while keeping context/scope/loop warnings |
  1465. For fixed-budget models, `MAX_THINKING_TOKENS` controls the thinking budget. On Opus 4.6 or Sonnet 4.6, also set `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` to use that mode. A positive token value does not cap adaptive reasoning; see the [performance rule](rules/common/performance.md#extended-thinking--plan-mode).
  1466. Switch to Opus only when you need deep architectural reasoning:
  1467. ```
  1468. /model opus
  1469. ```
  1470. </details>
  1471. <details>
  1472. <summary><strong>Daily workflow commands</strong></summary>
  1473. | Command | When to Use |
  1474. |---------|-------------|
  1475. | `/model sonnet` | Default for most tasks |
  1476. | `/model opus` | Complex architecture, debugging, deep reasoning |
  1477. | `/clear` | Between unrelated tasks (free, instant reset) |
  1478. | `/compact` | At logical task breakpoints (research done, milestone complete) |
  1479. | `/cost` | Monitor token spending during session |
  1480. 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.
  1481. </details>
  1482. <details>
  1483. <summary><strong>Strategic compaction</strong></summary>
  1484. 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.
  1485. **When to compact:**
  1486. - After research/exploration, before implementation
  1487. - After completing a milestone, before starting the next
  1488. - After debugging, before continuing feature work
  1489. - After a failed approach, before trying a new one
  1490. **When NOT to compact:**
  1491. - Mid-implementation (you'll lose variable names, file paths, partial state)
  1492. </details>
  1493. <details>
  1494. <summary><strong>Context window management</strong></summary>
  1495. **Critical:** Don't enable all MCPs at once. Each MCP tool description consumes tokens from your 200k window, potentially reducing it to ~70k.
  1496. - Keep under 10 MCPs enabled per project
  1497. - Keep under 80 tools active
  1498. - Use `/mcp` to disable unused Claude Code MCP servers; those runtime choices persist in `~/.claude.json`
  1499. - Use `ECC_DISABLED_MCPS` only to filter ECC-generated MCP configs during install/sync flows
  1500. - If context is getting heavy, run `/context-budget` and remove rules you do not need
  1501. **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.
  1502. </details>
  1503. ## Requirements
  1504. <details>
  1505. <summary><strong>Claude Code CLI version + hooks auto-loading behavior</strong></summary>
  1506. ### Claude Code CLI version
  1507. **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.
  1508. Check your version:
  1509. ```bash
  1510. claude --version
  1511. ```
  1512. ### Important: hooks auto-loading behavior
  1513. > WARNING: **For Contributors:** Do NOT add a `"hooks"` field to `.claude-plugin/plugin.json`. This is enforced by a regression test.
  1514. 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:
  1515. ```
  1516. Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file
  1517. ```
  1518. **History:** This has caused repeated fix/revert cycles in this repo ([#29](https://github.com/affaan-m/ECC/issues/29), [#52](https://github.com/affaan-m/ECC/issues/52), [#103](https://github.com/affaan-m/ECC/issues/103)). The behavior changed between Claude Code versions, leading to confusion. There is now a regression test to prevent this from being reintroduced.
  1519. </details>
  1520. ## Security
  1521. Install ECC only from official sources:
  1522. - GitHub repository: <https://github.com/affaan-m/ECC>
  1523. - Claude Code plugin: `ecc@ecc`
  1524. - npm packages: [`ecc-universal`](https://www.npmjs.com/package/ecc-universal) and [`ecc-agentshield`](https://www.npmjs.com/package/ecc-agentshield)
  1525. - GitHub App: <https://github.com/apps/ecc-tools>
  1526. - Website: <https://ecc.tools>
  1527. Scan a project with an already installed, reviewed AgentShield binary (see [runner provenance](#agentshield-runner-provenance)):
  1528. ```bash
  1529. agentshield scan --path .
  1530. ```
  1531. - **Report a vulnerability.** Use the private process in [SECURITY.md](SECURITY.md) (GitHub private vulnerability reporting). Please do not open public issues for security reports.
  1532. - **Built-in guardrails.** GateGuard gates destructive shell commands (including `rm`, force/path `git checkout`, and destructive `find -exec`) before they run; the supply-chain IOC scanner runs in CI; and AgentShield audits your own agent, hook, MCP, permission, and secret surfaces (`/security-scan`).
  1533. <details>
  1534. <summary><strong>Hooks, MCP servers, and context controls</strong></summary>
  1535. 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.
  1536. 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.
  1537. Use `/mcp` for Claude Code runtime disables; Claude Code persists those choices in `~/.claude.json`.

Lines 2,001–2,215 are not shown. The link to the file on GitHub has every line.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.