From 41441427b95eb94c3ac9e385b959f5dd7d89ce58 Mon Sep 17 00:00:00 2001 From: haelyra <49814733+haelyra@users.noreply.github.com> Date: Mon, 27 Jul 2026 15:17:36 -0400 Subject: [PATCH] docs: refresh README for ECC 2.1 (#2579) Refresh the main README for ECC 2.1, including the Plan Canvas demo, install paths, harness guidance, security, sponsors, and community sections. --- README.md | 2421 +++++++++++++---------------------------------------- 1 file changed, 561 insertions(+), 1860 deletions(-) diff --git a/README.md b/README.md index 5b4c149a..6716ed67 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,31 @@ -**Language:** English | [Português (Brasil)](docs/pt-BR/README.md) | [简体中文](README.zh-CN.md) | [繁體中文](docs/zh-TW/README.md) | [日本語](docs/ja-JP/README.md) | [한국어](docs/ko-KR/README.md) | [Türkçe](docs/tr/README.md) | [Русский](docs/ru/README.md) | [Tiếng Việt](docs/vi-VN/README.md) | [ไทย](docs/th/README.md) | [Deutsch](docs/de-DE/README.md) | [Español](docs/es/README.md) +

+ ECC - the agent harness operating system +

-![ECC — the agent harness operating system](assets/hero.png) +

+ Language: + English | + Português (Brasil) | + 简体中文 | + 繁體中文 | + 日本語 | + 한국어 | + Türkçe | + Русский | + Tiếng Việt | + ไทย | + Deutsch | + Español +

-[![Discord](https://img.shields.io/discord/1496644400590094540?logo=discord&logoColor=white&label=Join%20the%20Discord&color=5865F2)](https://discord.gg/36yGMHGFbR) -[![Website](https://img.shields.io/badge/Website-ecc.tools-E07856?logo=googlechrome&logoColor=white)](https://ecc.tools) -[![GitHub App](https://img.shields.io/badge/GitHub%20App-ECC%20Tools-181717?logo=github&logoColor=white)](https://github.com/apps/ecc-tools) -[![Guides](https://img.shields.io/badge/Guides-Start%20here-1f6feb?logo=readme&logoColor=white)](#the-guides) - -[![Stars](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Fstars&style=flat)](https://github.com/affaan-m/ECC/stargazers) -[![Forks](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Fforks&style=flat)](https://github.com/affaan-m/ECC/network/members) -[![Contributors](https://img.shields.io/github/contributors/affaan-m/ECC?style=flat)](https://github.com/affaan-m/ECC/graphs/contributors) -[![npm ecc-universal](https://img.shields.io/npm/dw/ecc-universal?label=ecc-universal%20weekly%20downloads&logo=npm)](https://www.npmjs.com/package/ecc-universal) -[![npm ecc-agentshield](https://img.shields.io/npm/dw/ecc-agentshield?label=ecc-agentshield%20weekly%20downloads&logo=npm)](https://www.npmjs.com/package/ecc-agentshield) -[![GitHub App Install](https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Finstalls&logo=github)](https://github.com/marketplace/ecc-tools) -[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) -![Shell](https://img.shields.io/badge/-Shell-4EAA25?logo=gnu-bash&logoColor=white) -![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white) -![Python](https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white) -![Go](https://img.shields.io/badge/-Go-00ADD8?logo=go&logoColor=white) -![Java](https://img.shields.io/badge/-Java-ED8B00?logo=openjdk&logoColor=white) -![Perl](https://img.shields.io/badge/-Perl-39457E?logo=perl&logoColor=white) -![Markdown](https://img.shields.io/badge/-Markdown-000000?logo=markdown&logoColor=white) - -> [!WARNING] -> **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. - -**211.9K+ stars** | **32.5K+ forks** | **230+ contributors** | **12+ language ecosystems** | **Cross-harness agent workflows** - ---- - -
- -**Language / 语言 / 語言 / Dil / Язык / Ngôn ngữ / Idioma** - -[**English**](README.md) | [Português (Brasil)](docs/pt-BR/README.md) | [简体中文](README.zh-CN.md) | [繁體中文](docs/zh-TW/README.md) | [日本語](docs/ja-JP/README.md) | [한국어](docs/ko-KR/README.md) - | [Türkçe](docs/tr/README.md) | [Русский](docs/ru/README.md) | [Tiếng Việt](docs/vi-VN/README.md) | [ไทย](docs/th/README.md) | [Deutsch](docs/de-DE/README.md) | [Español](docs/es/README.md) - -
- ---- - -**The harness-native operator system for agentic work. Built from real-world multi-harness engineering workflows.** - -Not just configs. A complete system: skills, instincts, memory optimization, continuous learning, security scanning, and research-first development. Production-ready agents, skills, hooks, rules, MCP configurations, and legacy command shims evolved over 10+ months of intensive daily use building real products. - -Works across **Codex**, **Claude Code**, **Cursor**, **OpenCode**, **Gemini**, **Zed**, **GitHub Copilot**, and other AI agent harnesses. - -ECC v2.0.0 adds the public Hermes operator story on top of that reusable layer: start with the [Hermes setup guide](docs/HERMES-SETUP.md), then review the [2.0.0 release notes](docs/releases/2.0.0/release-notes.md) and [cross-harness architecture](docs/architecture/cross-harness.md). - ---- +

+ Discord + Website + GitHub App + MIT license + ecc-universal npm downloads + ecc-agentshield npm downloads +

@@ -73,79 +50,354 @@ ECC v2.0.0 adds the public Hermes operator story on top of that reusable layer: Discord
Community
- Discord · Q&A · Show & Tell + Discord · Q&A · Show and Tell
-**OSS stays free.** This repo is MIT-licensed forever. ECC Pro is the hosted GitHub App for private repos. Sponsors and Pro subscribers fund the work. That's why a single maintainer ships weekly across 7 harnesses. +# Everything Claude Code -
+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. -Partners & sponsors +```text +plan -> test -> implement -> review -> verify -> remember -> improve +``` -

- CodeRabbit    - Greptile    - Atlas Cloud    - Moonshot AI — Kimi    - Itô Markets -

+Instead of rebuilding that process in every prompt, you install it once and make it part of how your agent works. -Community sponsors: Mike Morgan · @jasonwu513 · @1anter · @massimotodaro · @meadmccabe +> Optimize the context window. Persist everything else. -Become a Sponsor · Sponsor Tiers · Sponsorship Program +ECC is MIT-licensed open source. It works best with Claude Code today, with first-class Codex support and adapters for Cursor, OpenCode, Gemini, Zed, GitHub Copilot, Antigravity, Qwen, and other harnesses. -
+Access to 67 agents, 281 skills, and 94 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. ---- +| Included | Count | What it gives you | +| ---------------- | ----------: | ------------------------------------------------------------------------------------ | +| Agents | 67 agents | Planning, review, build repair, security, architecture, and domain work | +| Skills | 281 skills | TDD, research, security, docs, frontend, data, ML, operations, and more | +| Commands | 94 commands | Convenient entry points while ECC moves to a skills-first surface | +| Hooks and memory | Runtime | Enforcement, session summaries, continuous learning, instincts, and context controls | +| Rules | Selective | Always-loaded standards you choose by language or project | +| AgentShield | Included | Scanning for prompts, hooks, MCP config, permissions, secrets, and agent files | -## The Guides +## Why It Feels Different -This repo is the raw code only. The guides explain everything. +| Without a system | With ECC | +| ------------------------------------------------------- | --------------------------------------------------------------------- | +| Plans disappear into chat history | Plans become editable artifacts before implementation starts | +| "Please use TDD" is an instruction the model may forget | TDD becomes a gated RED -> GREEN -> REFACTOR workflow with evidence | +| The same context writes and reviews the code | A fresh-context reviewer looks for regressions and blind spots | +| Memory means saving an enormous transcript | Sessions are distilled into summaries, instincts, and reusable skills | +| Quality checks depend on reminders | Hooks can enforce deterministic checks outside the prompt | +| Agent configuration is trusted by default | AgentShield scans the harness itself as an attack surface | - - - - - - -
- -The Shorthand Guide to ECC
-The Shorthand Guide - -
Setup, foundations, philosophy. Read this first. (thread) -		 - -The Longform Guide to ECC
-The Longform Guide - -
Token optimization, memory persistence, evals, parallelization. (thread) -		 - -The Shorthand Guide to Everything Agentic Security
-The Security Guide - -
Attack vectors, sandboxing, sanitization, CVEs, AgentShield. (thread) -
+### TDD is a principle, not a suggestion -| Topic | What You'll Learn | -|-------|-------------------| -| Token Optimization | Model selection, system prompt slimming, background processes | -| Memory Persistence | Hooks that save/load context across sessions automatically | -| Continuous Learning | Auto-extract patterns from sessions into reusable skills | -| Verification Loops | Checkpoint vs continuous evals, grader types, pass@k metrics | -| Parallelization | Git worktrees, cascade method, when to scale instances | -| Subagent Orchestration | The context problem, iterative retrieval pattern | +```text +/ecc:plan "Add usage-based billing alerts" + -> confirm or edit the plan + -> activate tdd-workflow + -> capture RED evidence before implementation + -> implement until GREEN + -> review from fresh context + -> fix findings with regression tests + -> verify build, lint, types, and tests +``` ---- +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. -## Self-host Kimi with ECC + Itô compute +### Skills keep the context focused -The Kimi Code harness and the model-serving layer are separate. ECC configures the agent harness; you bring an API endpoint or self-host an open-weight Kimi model on your own GPU capacity. +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. + +| Concept | What it does | Context behavior | +|---|---|---| +| Skills | Reusable workflows such as TDD, security review, or deep research | Loaded when the task needs them | +| Agents | Scoped workers with their own context and tool permissions | Isolate planning, implementation, and review | +| Rules | Durable project or language standards | Always loaded, so install them selectively | +| Hooks | Scripts triggered by harness events | Run outside the model context | +| Instincts | Patterns learned from real sessions with confidence scores | Recalled when relevant | + +### Share context between harnesses + +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/`. + +```bash +npm install -g ecc-universal +ecc memory init --scope project +ecc memory search "authentication migration" --target-harness codex +ecc memory doctor +``` + +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. + +[Open the Unified Memory workflow →](skills/unified-memory/SKILL.md) + +## What's New: ECC 2.1 + +> [!IMPORTANT] +> **NEW IN ECC 2.1: Plan Canvas · Kimi harness · self-hosted compute on Itô GPUs.** +> [See the full release notes →](https://github.com/affaan-m/ECC/blob/main/docs/releases/2.1.0/release-notes.md) + +### Plan Canvas: review plans by pointing, not retyping + +Your agent writes a plan, then opens it in a loopback-only browser canvas. Click the part you mean, attach numbered annotations, chat from a side rail, and hit **Approve plan** or **Request changes**. The verdict maps straight onto `/plan`'s CONFIRM gate. Mermaid diagrams render live, and edits to the plan file reload the page. + +![Plan Canvas demo: reviewing an ECC plan in the browser, scrolling diagrams, attaching an anchored annotation, chatting with the agent, and approving the plan](https://raw.githubusercontent.com/affaan-m/ECC/main/docs/releases/2.1.0/assets/ecc-plan-canvas-demo.gif) + +It's harness- and model-agnostic: a plain CLI (`ecc-plan-canvas`) speaking JSON, so any agent can drive it. Try it: ask your agent to `/ecc:plan` anything, then review from the page instead of the terminal. + +[Open the plan used in this demo →](https://github.com/affaan-m/ECC/blob/main/docs/releases/2.1.0/plan-canvas-demo.plan.md) + +### Also in 2.1 + +- **Kimi Code install target** (`--target kimi`): ECC installs natively into [Moonshot AI](https://www.moonshot.ai)'s Kimi Code CLI +- **Self-host on GPUs**: a verified path with [Itô](https://compute.itomarkets.com), ECC's preferred compute sponsor, including the opt-in `ecc ito find` RFQ bridge (details and disclosures below) +- **Moonshot AI (Kimi), Itô, and Atlas Cloud** are now public sponsors +- **Hermes + OpenClaw install targets**, a Codex navigation guide, consolidated PostToolUse hooks, and supply-chain hardening + +
+Previous releases + +| Version | Highlights | +|---|---| +| [v2.0.0](https://github.com/affaan-m/ECC/releases/tag/v2.0.0) | The Agent Harness Operating System: cross-harness graduation, control-pane substrate, `orch-*` orchestrators, Discord + ECC bot, single-connector MCP policy | +| [v1.10.0](https://github.com/affaan-m/ECC/releases/tag/v1.10.0) | Surface refresh, operator workflows, ECC 2.0 alpha | +| [v1.9.0](https://github.com/affaan-m/ECC/releases/tag/v1.9.0) | Selective install, ECC Tools Pro, 12 language ecosystems | +| [v1.8.0](https://github.com/affaan-m/ECC/releases/tag/v1.8.0) | Harness performance and cross-platform reliability | +| [v1.7.0](https://github.com/affaan-m/ECC/releases/tag/v1.7.0) | Cross-platform expansion and presentation builder | +| [v1.6.0](https://github.com/affaan-m/ECC/releases/tag/v1.6.0) | Codex Edition and the ECC Tools GitHub App | +| [v1.5.0](https://github.com/affaan-m/ECC/releases/tag/v1.5.0) | Universal Edition | +| [v1.4.0](https://github.com/affaan-m/ECC/releases/tag/v1.4.0) | Multi-language rules, installation wizard, PM2 orchestration | +| [v1.3.0](https://github.com/affaan-m/ECC/releases/tag/v1.3.0) | Complete OpenCode plugin support | +| [v1.2.0](https://github.com/affaan-m/ECC/releases/tag/v1.2.0) | Unified commands and skills | +| [v1.1.0](https://github.com/affaan-m/ECC/releases/tag/v1.1.0) | Cross-platform support and community fixes | +| [v1.0.0](https://github.com/affaan-m/ECC/releases/tag/v1.0.0) | Official plugin release | + +
+ +## Install ECC + +### Pick one path only (per harness) + +You can use ECC with Claude Code, Codex, and other harnesses at the same time. Choose one install method for each harness: + +- **Works:** Claude Code plugin + Codex sync +- **Avoid:** Claude Code plugin + full Claude manual install +- **Avoid:** Codex sync + Codex marketplace plugin + +**Recommended default:** install the Claude Code plugin for Claude Code and use the supported sync flow for Codex. **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. + +### Claude Code + +Run these commands inside Claude Code: + +```text +/plugin marketplace add https://github.com/affaan-m/ECC +/plugin install ecc@ecc +``` + +That installs ECC's skills, agents, commands, and plugin-managed hooks. Claude Code plugins cannot distribute `rules`, so add only the rule packs you actually want: + +```bash +git clone https://github.com/affaan-m/ECC.git +cd ECC +mkdir -p ~/.claude/rules/ecc +cp -R rules/common ~/.claude/rules/ecc/ +cp -R rules/typescript ~/.claude/rules/ecc/ # replace with your stack +``` + +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. + +### Codex App and CLI + +The reliable ECC setup for Codex is the sync flow. Run Codex once first so `~/.codex/config.toml` exists. The sync preserves your existing Codex files, creates timestamped backups, and merges ECC's `AGENTS.md`, skills, prompts, agents, and reference config into `~/.codex`: + +```bash +git clone https://github.com/affaan-m/ECC.git +cd ECC +npm install +bash scripts/sync-ecc-to-codex.sh +``` + +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. + +For repo navigation, surface ownership, and PR diff packet guidance, read the [Codex ECC Navigation Map](docs/CODEX-NAVIGATION-GUIDE.md). + +
+Codex plugin marketplace (experimental for ECC) + +Codex officially supports plugin marketplaces, and ECC publishes a repo marketplace: + +```bash +codex plugin marketplace add affaan-m/ECC +codex plugin marketplace list +``` + +Restart Codex, then install or enable `ecc` from the Plugins directory. Do not add the marketplace plugin on top of the Codex sync flow. Marketplace registration is stable in Codex, but ECC's current plugin package references shared repository content that may not be copied into Codex's install cache. Until that upstream cache behavior is resolved, use the sync flow above when you need all ECC skills reliably. + +From an ECC checkout, verify the installed plugin cache with: + +```bash +node scripts/codex/check-plugin-cache.js +``` + +See the [.codex plugin notes](.codex-plugin/README.md) for the current limitation and tracking issues. +
+ +
+Other agents and editors + +Clone ECC once, then choose the target that matches your harness: + +```bash +git clone https://github.com/affaan-m/ECC.git +cd ECC +``` + +| Harness | Install or setup | Notes | +|---|---|---| +| Cursor | `./install.sh --profile minimal --target cursor` | Project-local `.cursor/` adapter | +| OpenCode | `npm install && npm run build:opencode && ./install.sh --profile full --target opencode` | Builds the plugin payload before the full install | +| Gemini CLI | `./install.sh --profile minimal --target gemini` | Project-local `.gemini/` config | +| Zed | `./install.sh --profile minimal --target zed` | Project-local `.zed/` adapter | +| Antigravity | `./install.sh --profile minimal --target antigravity` | See the [Antigravity guide](docs/ANTIGRAVITY-GUIDE.md) | +| Qwen CLI | `./install.sh --profile minimal --target qwen` | See the [Qwen guide](docs/QWEN-GUIDE.md) | +| Hermes | `./install.sh --profile minimal --target hermes` | See the [Hermes setup guide](docs/HERMES-SETUP.md) | +| OpenClaw | `./install.sh --profile minimal --target openclaw` | Managed home-directory install | +| Kimi Code CLI | `./install.sh --profile minimal --target kimi` | Project-local `.kimi/` install | +| CodeBuddy | `./install.sh --profile minimal --target codebuddy` | Project-local `.codebuddy/` install | +| JoyCode | `./install.sh --profile minimal --target joycode` | Project-local `.joycode/` install | + +GitHub Copilot support is already included in this repository. `.github/copilot-instructions.md` provides the instruction layer, `.github/prompts/` contains the reusable `/plan`, `/tdd`, `/security-review`, `/build-fix`, and `/refactor` prompts, and `.vscode/settings.json` enables `chat.promptFiles`. + +For a harness without a native ECC target, use the [manual adaptation guide](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. + +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. +
+ +## Advanced Install Options + +The options stay here, directly under the main install paths, so you do not have to hunt through the README when the default setup is not the right fit. + +
+Low-context install with no hook runtime + +### Low-context / no-hooks path + +Use this when you want ECC's rules, agents, commands, platform config, and core workflows without runtime hooks: + +```bash +./install.sh --profile minimal --target claude +# or, without cloning first +npx ecc-install --profile minimal --target claude +``` + +Windows: + +```powershell +.\install.ps1 --profile minimal --target claude +``` + +This profile intentionally excludes `hooks-runtime`. + +For the normal core profile with hooks disabled: + +```bash +./install.sh --profile core --without baseline:hooks --target claude +``` + +Add the hook runtime later only if you want it: + +```bash +./install.sh --target claude --modules hooks-runtime +``` +
+ +
+Choose only the components you need + +### Find the right components first + +Ask the packaged advisor which components match your work: + +```bash +npx ecc consult "security reviews" --target claude +``` + +It returns matching components, related profiles, and preview/install commands. + +You can also install explicit skills or capabilities: + +```bash +./install.sh --target claude --skills tdd-workflow,security-review +npx ecc install --profile minimal --target claude --with capability:machine-learning +``` +
+ +
+Project-local rules instead of global rules + +Use project-local rules when ECC's standards should apply to one repository rather than every Claude Code session: + +```bash +cd your-project +mkdir -p .claude/rules/ecc +cp -R /path/to/ECC/rules/common .claude/rules/ecc/ +cp -R /path/to/ECC/rules/typescript .claude/rules/ecc/ +``` + +Rules are always-loaded context, so begin with `common` and one pack for the stack you actually use. +
+ +
+Fully manual Claude install + +Use this only when you are intentionally skipping the plugin path: + +```bash +git clone https://github.com/affaan-m/ECC.git +cd ECC +./install.sh --profile full +``` + +Windows: + +```powershell +git clone https://github.com/affaan-m/ECC.git +cd ECC +.\install.ps1 --profile full +``` + +If you choose this path, stop there. Do not also run `/plugin install`. + +For hand-picked manual installs, Claude discovers skills as direct children of `~/.claude/skills/`; do not nest them under `~/.claude/skills/ecc/`. + +Do not copy the raw repo `hooks/hooks.json` into `~/.claude/settings.json` or `~/.claude/hooks/hooks.json`. Use the installer so hook command paths are rewritten correctly: + +```bash +bash ./install.sh --target claude --modules hooks-runtime +``` + +On Windows, Claude's config root is `%USERPROFILE%\\.claude`; install the hook runtime with: + +```powershell +pwsh -File .\install.ps1 --target claude --modules hooks-runtime +``` +
+ +
+Custom API endpoints, model gateways, and self-hosted models + +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. + +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. + +For Claude Code, 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). + +For a local Kimi setup, keep the harness, model-serving endpoint, and GPU provider as separate choices: @@ -158,22 +410,22 @@ The Kimi Code harness and the model-serving layer are separate. ECC configures t
- Moonshot AI — Kimi
+ Moonshot AI - Kimi
2. Serve Kimi
- Expose the chosen checkpoint through a Kimi- or OpenAI-compatible endpoint. + Expose the chosen checkpoint through a compatible endpoint. 		ECC Tools
3. Run Kimi Code with ECC
- Install project instructions and skills, then start kimi. + Install project instructions and skills, then start Kimi Code.
-Configure the endpoint using Kimi Code's official provider guide, then install the ECC project surface: +Configure the endpoint with Kimi Code's official provider guide, then install ECC: ```bash bash ./install.sh --target kimi --profile minimal @@ -181,337 +433,15 @@ npx ecc doctor --target kimi kimi ``` -Kimi Code discovers the installed `.kimi/AGENTS.md` instructions and `.kimi/skills/` workflows natively. The installer dry-run and regression suite verify that the Kimi target stays inside the project-local `.kimi/` root. +Kimi Code discovers the installed `.kimi/AGENTS.md` instructions and `.kimi/skills/` workflows natively. +
-Run or self-host any open-source model on owned or rented GPUs. Itô 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. - -This three-beat strip is also the video outline: capacity → serving endpoint → Kimi Code with ECC. - ---- - -## What's New - -### Current Development — Unified Memory Vault - -`ecc memory` gives Claude, Codex, Hermes, OpenClaw, Kimi, and other harnesses -one local, inspectable Markdown format for durable context and handoffs. The -optional `ecc-memory-mcp` stdio server exposes the same bounded -save/search/read/doctor surface without enabling itself by default. - -### v2.1.0 — The Agent Harness Operating System (Jun 2026) - -Stable graduation of the 2.0 line: 261 skills, the control-pane substrate (session adapters + MCP inventory), the worktree-lifecycle service, the `orch-*` orchestrator family, and the launch of the [ECC Discord community](https://discord.gg/36yGMHGFbR). Full notes: [docs/releases/2.0.0/release-notes.md](docs/releases/2.0.0/release-notes.md). - -### v2.0.0-rc.1 — Surface Refresh, Operator Workflows, and ECC 2.0 Alpha (Apr 2026) - -- **Dashboard GUI** — New Tkinter-based desktop application (`ecc_dashboard.py` or `npm run dashboard`) with dark/light theme toggle, font customization, and project logo in header and taskbar. -- **Public surface synced to the live repo** — metadata, catalog counts, plugin manifests, and install-facing docs now match the actual OSS surface: 66 agents, 268 skills, and 84 legacy command shims. -- **Operator and outbound workflow expansion** — `brand-voice`, `social-graph-ranker`, `connections-optimizer`, `customer-billing-ops`, `ecc-tools-cost-audit`, `google-workspace-ops`, `project-flow-ops`, and `workspace-surface-audit` round out the operator lane. -- **Media and launch tooling** — `manim-video`, `remotion-video-creation`, and upgraded social publishing surfaces make technical explainers and launch content part of the same system. -- **Framework and product surface growth** — `nestjs-patterns`, richer Codex/OpenCode install surfaces, and expanded cross-harness packaging keep the repo usable beyond Claude Code alone. -- **Itô prediction-market skill pack** — `ito-market-intelligence`, `ito-basket-compare`, `ito-trade-planner`, `ito-data-atlas-agent`, `prediction-market-oracle-research`, and `prediction-market-risk-review` add public, non-advisory market/basket workflows while keeping live Itô API access gated and separate from ECC Tools billing. -- **Optimization skill pack** — `parallel-execution-optimizer`, `benchmark-optimization-loop`, `data-throughput-accelerator`, `latency-critical-systems`, and `recursive-decision-ledger` turn repeated speed/recursion prompts into bounded benchmark, throughput, and decision-ledger workflows. -- **ECC 2.0 alpha is in-tree** — the Rust control-plane prototype in `ecc2/` now builds locally and exposes `dashboard`, `start`, `sessions`, `status`, `stop`, `resume`, and `daemon` commands. It is usable as an alpha, not yet a general release. -- **Operator status snapshots** — `ecc status --markdown --write status.md` turns the local state store into a portable handoff covering readiness, active sessions, skill-run health, install health, pending governance events, and linked work items from Linear/GitHub/handoffs. Use `ecc work-items upsert ...` for manual entries, `ecc work-items sync-github --repo owner/repo` for PR/issue queue state, and `ecc status --exit-code` to fail automation when readiness needs attention. -- **Ecosystem hardening** — AgentShield, ECC Tools cost controls, billing portal work, and website refreshes continue to ship around the core plugin instead of drifting into separate silos. - -### v1.9.0 — Selective Install & Language Expansion (Mar 2026) - -- **Selective install architecture** — Manifest-driven install pipeline with `install-plan.js` and `install-apply.js` for targeted component installation. State store tracks what's installed and enables incremental updates. -- **6 new agents** — `typescript-reviewer`, `pytorch-build-resolver`, `java-build-resolver`, `java-reviewer`, `kotlin-reviewer`, `kotlin-build-resolver` expand language coverage to 10 languages. -- **New skills** — `pytorch-patterns` for deep learning workflows, `documentation-lookup` for API reference research, `bun-runtime` and `nextjs-turbopack` for modern JS toolchains, plus 8 operational domain skills and `mcp-server-patterns`. -- **Session & state infrastructure** — SQLite state store with query CLI, session adapters for structured recording, skill evolution foundation for self-improving skills. -- **Orchestration overhaul** — Harness audit scoring made deterministic, orchestration status and launcher compatibility hardened, observer loop prevention with 5-layer guard. -- **Observer reliability** — Memory explosion fix with throttling and tail sampling, sandbox access fix, lazy-start logic, and re-entrancy guard. -- **12 language ecosystems** — New rules for Java, PHP, Perl, Kotlin/Android/KMP, C++, and Rust join existing TypeScript, Python, Go, and common rules. -- **Community contributions** — Korean and Chinese translations, biome hook optimization, video processing skills, operational skills, PowerShell installer, Antigravity IDE support. -- **CI hardening** — 19 test failure fixes, catalog count enforcement, install manifest validation, and full test suite green. - -### v1.8.0 — Harness Performance System (Mar 2026) - -- **Harness-first release** — ECC is now explicitly framed as an agent harness performance system, not just a config pack. -- **Hook reliability overhaul** — SessionStart root fallback, Stop-phase session summaries, and script-based hooks replacing fragile inline one-liners. -- **Hook runtime controls** — `ECC_HOOK_PROFILE=minimal|standard|strict` and `ECC_DISABLED_HOOKS=...` for runtime gating without editing hook files. -- **New harness commands** — `/harness-audit`, `/loop-start`, `/loop-status`, `/quality-gate`, `/model-route`. -- **NanoClaw v2** — model routing, skill hot-load, session branch/search/export/compact/metrics. -- **Cross-harness parity** — behavior tightened across Claude Code, Cursor, OpenCode, and Codex app/CLI. -- **997 internal tests passing** — full suite green after hook/runtime refactor and compatibility updates. - -### v1.7.0 — Cross-Platform Expansion & Presentation Builder (Feb 2026) - -- **Codex app + CLI support** — Direct `AGENTS.md`-based Codex support, installer targeting, and Codex docs -- **`frontend-slides` skill** — Zero-dependency HTML presentation builder with PPTX conversion guidance and strict viewport-fit rules -- **5 new generic business/content skills** — `article-writing`, `content-engine`, `market-research`, `investor-materials`, `investor-outreach` -- **Broader tool coverage** — Cursor, Codex, and OpenCode support tightened so the same repo ships cleanly across all major harnesses -- **992 internal tests** — Expanded validation and regression coverage across plugin, hooks, skills, and packaging - -### v1.6.0 — Codex CLI, AgentShield & Marketplace (Feb 2026) - -- **Codex CLI support** — New `/codex-setup` command generates `codex.md` for OpenAI Codex CLI compatibility -- **7 new skills** — `search-first`, `swift-actor-persistence`, `swift-protocol-di-testing`, `regex-vs-llm-structured-text`, `content-hash-cache-pattern`, `cost-aware-llm-pipeline`, `skill-stocktake` -- **AgentShield integration** — `/security-scan` skill runs AgentShield directly from Claude Code; 1282 tests, 102 rules -- **GitHub Marketplace** — ECC Tools GitHub App live at [github.com/marketplace/ecc-tools](https://github.com/marketplace/ecc-tools) with free/pro/enterprise tiers -- **30+ community PRs merged** — Contributions from 30 contributors across 6 languages -- **978 internal tests** — Expanded validation suite across agents, skills, commands, hooks, and rules - -### v1.4.1 — Bug Fix (Feb 2026) - -- **Fixed instinct import content loss** — `parse_instinct_file()` was silently dropping all content after frontmatter (Action, Evidence, Examples sections) during `/instinct-import`. ([#148](https://github.com/affaan-m/ECC/issues/148), [#161](https://github.com/affaan-m/ECC/pull/161)) - -### v1.4.0 — Multi-Language Rules, Installation Wizard & PM2 (Feb 2026) - -- **Interactive installation wizard** — New `configure-ecc` skill provides guided setup with merge/overwrite detection -- **PM2 & multi-agent orchestration** — 6 new commands (`/pm2`, `/multi-plan`, `/multi-execute`, `/multi-backend`, `/multi-frontend`, `/multi-workflow`) for managing complex multi-service workflows -- **Multi-language rules architecture** — Rules restructured from flat files into `common/` + `typescript/` + `python/` + `golang/` directories. Install only the languages you need -- **Chinese (zh-CN) translations** — Complete translation of all agents, commands, skills, and rules (80+ files) -- **GitHub Sponsors support** — Sponsor the project via GitHub Sponsors -- **Enhanced CONTRIBUTING.md** — Detailed PR templates for each contribution type - -### v1.3.0 — OpenCode Plugin Support (Feb 2026) - -- **Full OpenCode integration** — 12 agents, 24 commands, 16 skills with hook support via OpenCode's plugin system (20+ event types) -- **3 native custom tools** — run-tests, check-coverage, security-audit -- **LLM documentation** — `llms.txt` for comprehensive OpenCode docs - -### v1.2.0 — Unified Commands & Skills (Feb 2026) - -- **Python/Django support** — Django patterns, security, TDD, and verification skills -- **Java Spring Boot skills** — Patterns, security, TDD, and verification for Spring Boot -- **Session management** — `/sessions` command for session history -- **Continuous learning v2** — Instinct-based learning with confidence scoring, import/export, evolution - -See the full changelog in [Releases](https://github.com/affaan-m/ECC/releases). - ---- - -## Share Context Between Agent Harnesses - -ECC's Memory Vault stores portable `ecc.memory.v1` Markdown documents instead -of copying vendor transcripts or emailing context between agents. Project and -team scopes live under `.ecc/memory/`; user scope lives under -`~/.ecc/memory/`. 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. - -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: - -```bash -npm install -g ecc-universal -ecc memory --help -command -v ecc-memory-mcp -``` - -```bash -# Initialize the project vault. -ecc memory init --scope project - -# Write a handoff body to a regular file, then target the next harness. -ecc memory handoff \ - --from hermes \ - --target codex \ - --title "Continue authentication migration" \ - --body-file ./handoff.md - -# Recall it from another harness. -ecc memory search "authentication migration" --target-harness codex -ecc memory read - -# Validate the vault before sharing team memories. -ecc memory doctor -``` - -Memory bodies are accepted only through `--stdin` or `--body-file`, not as -command-line values. The first release keeps every vault entry unreviewed and -create-only; human review promotes accepted knowledge into governed project -documentation rather than changing memory trust. Normal search recall returns -active project and team memories. A direct ID read may inspect a non-active -entry. User-scope recall must be requested explicitly. -Agents must verify important claims against authoritative sources and must -never treat recalled bodies as executable instructions or policy. - -For opt-in MCP access, add the `ecc-memory-vault` entry from -[`mcp-configs/mcp-servers.json`](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. - ---- - -## Quick Start - -Get up and running in under 2 minutes: - -### Pick one path only - -Most Claude Code users should use exactly one install path: - -- **Recommended default:** install the Claude Code plugin, then copy only the rule folders you actually want. -- **Use the manual installer only if** you want finer-grained control, want to avoid the plugin path entirely, or your Claude Code build has trouble resolving the self-hosted marketplace entry. -- **Do not stack install methods.** The most common broken setup is: `/plugin install` first, then `install.sh --profile full` or `npx ecc-install --profile full` afterward. - -If you already layered multiple installs and things look duplicated, skip straight to [Reset / Uninstall ECC](#reset--uninstall-ecc). - -### Low-context / no-hooks path - -If hooks feel too global or you only want ECC's rules, agents, commands, and core workflow skills, skip the plugin and use the minimal manual profile: - -```bash -./install.sh --profile minimal --target claude -``` - -```powershell -.\install.ps1 --profile minimal --target claude -# or -npx ecc-install --profile minimal --target claude -``` - -This profile intentionally excludes `hooks-runtime`. - -Claude manual installs place each skill directly under -`~/.claude/skills//` (or `.claude/skills//` 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. - -If you want the normal core profile but need hooks off, use: - -```bash -./install.sh --profile core --without baseline:hooks --target claude -``` - -Add hooks later only if you want runtime enforcement: - -```bash -./install.sh --target claude --modules hooks-runtime -``` - -### Find the right components first - -If you are not sure which ECC profile or component to install, ask the packaged advisor from any project: - -```bash -npx ecc consult "security reviews" --target claude -``` - -It returns matching components, related profiles, and preview/install commands. Use the preview command before installing if you want to inspect the exact file plan. - -For production ML/MLOps workflows, keep the install opt-in and component-scoped: - -```bash -npx ecc consult "mlops training model deployment" --target claude -npx ecc install --profile minimal --target claude --with capability:machine-learning -``` - -### Step 1: Install the Plugin (Recommended) - -> NOTE: The plugin is convenient, but the OSS installer below is still the most reliable path if your Claude Code build has trouble resolving self-hosted marketplace entries. - -```bash -# Add marketplace -/plugin marketplace add https://github.com/affaan-m/ECC - -# Install plugin -/plugin install ecc@ecc -``` - -### Naming + Migration Note - -ECC now has three public identifiers, and they are not interchangeable: - -- GitHub source repo: `affaan-m/ECC` -- Claude marketplace/plugin identifier: `ecc@ecc` -- npm package: `ecc-universal` - -This is intentional. Anthropic marketplace/plugin installs are keyed by a canonical plugin identifier, so ECC uses `ecc@ecc` to keep tool names and slash-command namespaces short enough for strict Desktop/API validators. Older posts may still show the former long marketplace identifier; treat that as a legacy alias only. Separately, the npm package stayed on `ecc-universal`, so npm installs and marketplace installs intentionally use different names. - -### Step 2: Install Rules Only If You Need Them - -> WARNING: **Important:** Claude Code plugins cannot distribute `rules` automatically. -> -> If you already installed ECC via `/plugin install`, **do not run `./install.sh --profile full`, `.\install.ps1 --profile full`, or `npx ecc-install --profile full` afterward**. The plugin already loads ECC skills, commands, and hooks. Running the full installer after a plugin install copies those same surfaces into your user directories and can create duplicate skills plus duplicate runtime behavior. -> -> For plugin installs, manually copy only the `rules/` directories you want under `~/.claude/rules/ecc/`. Start with `rules/common` plus one language or framework pack you actually use. Do not copy every rules directory unless you explicitly want all of that context in Claude. -> -> Use the full installer only when you are doing a fully manual ECC install instead of the plugin path. -> -> If your local Claude setup was wiped or reset, that does not mean you need to repurchase ECC. Start with `node scripts/ecc.js list-installed`, then run `node scripts/ecc.js doctor` and `node scripts/ecc.js repair` before reinstalling anything. That usually restores ECC-managed files without rebuilding your setup. If the problem is account or marketplace access for ECC Tools, handle billing/account recovery separately. - -```bash -# Clone the repo first -git clone https://github.com/affaan-m/ECC.git -cd ECC - -# Install dependencies (pick your package manager) -npm install # or: pnpm install | yarn install | bun install - -# Plugin install path: copy only ECC rules into an ECC-owned namespace -mkdir -p ~/.claude/rules/ecc -cp -R rules/common ~/.claude/rules/ecc/ -cp -R rules/typescript ~/.claude/rules/ecc/ - -# Fully manual ECC install path (use this instead of /plugin install) -# ./install.sh --profile full -``` - -```powershell -# Windows PowerShell - -# Plugin install path: copy only ECC rules into an ECC-owned namespace -New-Item -ItemType Directory -Force -Path "$HOME/.claude/rules/ecc" | Out-Null -Copy-Item -Recurse rules/common "$HOME/.claude/rules/ecc/" -Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/ecc/" - -# Fully manual ECC install path (use this instead of /plugin install) -# .\install.ps1 --profile full -# npx ecc-install --profile full -``` - -For manual install instructions see the README in the `rules/` folder. When copying rules manually, copy the whole language directory (for example `rules/common` or `rules/golang`), not the files inside it, so relative references keep working and filenames do not collide. - -### Fully manual install (Fallback) - -Use this only if you are intentionally skipping the plugin path: - -```bash -./install.sh --profile full -``` - -```powershell -.\install.ps1 --profile full -# or -npx ecc-install --profile full -``` - -If you choose this path, stop there. Do not also run `/plugin install`. +
+Reset, repair, or uninstall ### Reset / Uninstall ECC -If ECC feels duplicated, intrusive, or broken, do not keep reinstalling it on top of itself. - -- **Plugin path:** remove the plugin from Claude Code, then delete the specific rule folders you manually copied under `~/.claude/rules/ecc/`. -- **Manual installer / CLI path:** from the repo root, preview removal first: - -```bash -node scripts/uninstall.js --dry-run -``` - -Then remove ECC-managed files: - -```bash -node scripts/uninstall.js -``` - -You can also use the lifecycle wrapper: +If ECC feels duplicated, intrusive, or broken, inspect the managed state before reinstalling: ```bash node scripts/ecc.js list-installed @@ -520,1473 +450,244 @@ node scripts/ecc.js repair node scripts/ecc.js uninstall --dry-run ``` -ECC only removes files recorded in its install-state. It will not delete unrelated files it did not install. - -If you stacked methods, clean up in this order: - -1. Remove the Claude Code plugin install. -2. Run the ECC uninstall command from the repo root to remove install-state-managed files. -3. Delete any extra rule folders you copied manually and no longer want. -4. Reinstall once, using a single path. - -### Step 3: Start Using +For direct uninstall: ```bash -# Skills are the primary workflow surface. -# Existing slash-style command names still work while ECC migrates off commands/. - -# Plugin install uses the canonical namespaced form -/ecc:plan "Add user authentication" - -# Manual install keeps the shorter slash form: -# /plan "Add user authentication" - -# Check available commands -/plugin list ecc@ecc +node scripts/uninstall.js --dry-run +node scripts/uninstall.js ``` -**That's it!** You now have access to 67 agents, 281 skills, and 94 legacy command shims. +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. +
-### Dashboard GUI +## Start Using ECC -Launch the desktop dashboard to visually explore ECC components: +Start with the workflow you need, not the full catalog. -```bash -npm run dashboard -# or -python3 ./ecc_dashboard.py +| What you are doing | Start here | +|---|---| +| Building a feature | `/ecc:plan "describe the feature"`, then `tdd-workflow` | +| Fixing a bug | Reproduce it with a failing test, then use `tdd-workflow` | +| Reviewing new code | `/code-review` for a fresh-context review | +| Repairing a build | `/build-fix` | +| Cleaning a codebase | `/refactor-clean` | +| Checking context pressure | `/context-budget` | +| Ending a long session | `/save-session` or `/learn-eval` | +| Resuming later | `/resume-session` | +| Auditing agent config | `/security-scan` or `npx -y ecc-agentshield scan --path .` | + +
+Plugin commands and manual commands + +Claude Code plugin commands use the namespaced form: + +```text +/ecc:plan "Add authentication" ``` -**Features:** -- Tabbed interface: Agents, Skills, Commands, Rules, Settings -- Dark/Light theme toggle -- Font customization (family & size) -- Project logo in header and taskbar -- Search and filter across all components +Manual installs may expose the shorter compatibility form: -### Multi-model commands require additional setup - -> WARNING: `multi-*` commands are **not** covered by the base plugin/rules install above. -> -> To use `/multi-plan`, `/multi-execute`, `/multi-backend`, `/multi-frontend`, and `/multi-workflow`, you must also install the `ccg-workflow` runtime. -> -> Initialize it with `npx ccg-workflow`. -> -> That runtime provides the external dependencies these commands expect, including: -> - `~/.claude/bin/codeagent-wrapper` -> - `~/.claude/.ccg/prompts/*` -> -> Without `ccg-workflow`, these `multi-*` commands will not run correctly. - ---- - -## Cross-Platform Support - -This plugin now fully supports **Windows, macOS, and Linux**, alongside tight integration across major IDEs (Cursor, Zed, OpenCode, Antigravity) and CLI harnesses. All hooks and scripts have been rewritten in Node.js for maximum compatibility. - -### Package Manager Detection - -The plugin automatically detects your preferred package manager (npm, pnpm, yarn, or bun) with the following priority: - -1. **Environment variable**: `CLAUDE_PACKAGE_MANAGER` -2. **Project config**: `.claude/package-manager.json` -3. **package.json**: `packageManager` field -4. **Lock file**: Detection from package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb -5. **Global config**: `~/.claude/package-manager.json` -6. **Fallback**: First available package manager - -To set your preferred package manager: - -```bash -# Via environment variable -export CLAUDE_PACKAGE_MANAGER=pnpm - -# Via global config -node scripts/setup-package-manager.js --global pnpm - -# Via project config -node scripts/setup-package-manager.js --project bun - -# Detect current setting -node scripts/setup-package-manager.js --detect +```text +/plan "Add authentication" ``` -Or use the `/setup-pm` command in Claude Code. +Skills are the primary workflow surface. Commands remain convenient entry points and compatibility shims. +
-### Hook Runtime Controls +## Guides -Use runtime flags to tune strictness or disable specific hooks temporarily: + + + + + + +
+ +The Shorthand Guide to ECC
+The Shorthand Guide + +
Setup, foundations, and day-one use. +		 + +The Longform Guide to ECC
+The Longform Guide + +
Context economics, memory, evals, and parallel agents. +		 + +The Security Guide to ECC
+The Security Guide + +
Prompt injection, hooks, MCP, and AgentShield. +
-```bash -# Hook strictness profile (default: standard) -export ECC_HOOK_PROFILE=standard +[Commands Quick Reference](./COMMANDS-QUICK-REF.md) | [Manual Adaptation Guide](docs/MANUAL-ADAPTATION-GUIDE.md) -# Comma-separated hook IDs to disable -export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck" +
+What is inside the repository -# Cap SessionStart additional context (default: 8000 chars) -export ECC_SESSION_START_MAX_CHARS=4000 - -# Disable SessionStart additional context entirely for low-context/local-model setups -export ECC_SESSION_START_CONTEXT=off - -# Session-tmp retention window in days (default: 30). -# Set to 0, off, false, disabled, never, or none to keep all sessions (disable pruning). -export ECC_SESSION_RETENTION_DAYS=14 - -# Cap how many learned instincts SessionStart injects into context (default: 6) -export ECC_MAX_INJECTED_INSTINCTS=6 - -# Minimum confidence an instinct needs to be injected, 0-1 (default: 0.7) -export ECC_INSTINCT_CONFIDENCE_THRESHOLD=0.7 - -# Keep context/scope/loop warnings but suppress API-rate cost estimates -export ECC_CONTEXT_MONITOR_COST_WARNINGS=off -``` - -Windows PowerShell: - -```powershell -[Environment]::SetEnvironmentVariable('ECC_CONTEXT_MONITOR_COST_WARNINGS', 'off', 'User') -[Environment]::SetEnvironmentVariable('ECC_SESSION_RETENTION_DAYS', '14', 'User') -``` - -### Agent data home (multi-harness isolation) - -Memory persistence hooks (session summaries, learned skills, session aliases, metrics) store data under a single agent data root. By default that root is `~/.claude`. When you use ECC in both Claude Code and Cursor on the same machine, set a separate root for Cursor so the two environments do not overwrite each other's session files: - -```bash -# Cursor-only boundary (Claude Code keeps the default ~/.claude) -export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc" -``` - -Paths resolved under that root include: - -- `$ECC_AGENT_DATA_HOME/session-data/` — session summaries -- `$ECC_AGENT_DATA_HOME/skills/learned/` — learned skills from evaluate-session -- `$ECC_AGENT_DATA_HOME/session-aliases.json` — session aliases -- `$ECC_AGENT_DATA_HOME/metrics/` — cost and activity metrics - -See [affaan-m/ECC#2065](https://github.com/affaan-m/ECC/issues/2065). - ---- - -## What's Inside - -This repo is a **Claude Code plugin** - install it directly or copy components manually. - -``` +```text ECC/ -|-- .claude-plugin/ # Plugin and marketplace manifests -| |-- plugin.json # Plugin metadata and component paths -| |-- marketplace.json # Marketplace catalog for /plugin marketplace add -| |-- agents/ # 67 specialized subagents for delegation -| |-- planner.md # Feature implementation planning -| |-- architect.md # System design decisions -| |-- tdd-guide.md # Test-driven development -| |-- code-reviewer.md # Quality and security review -| |-- security-reviewer.md # Vulnerability analysis -| |-- build-error-resolver.md -| |-- e2e-runner.md # Playwright E2E testing -| |-- refactor-cleaner.md # Dead code cleanup -| |-- doc-updater.md # Documentation sync -| |-- docs-lookup.md # Documentation/API lookup -| |-- chief-of-staff.md # Communication triage and drafts -| |-- loop-operator.md # Autonomous loop execution -| |-- harness-optimizer.md # Harness config tuning -| |-- cpp-reviewer.md # C++ code review -| |-- cpp-build-resolver.md # C++ build error resolution -| |-- fsharp-reviewer.md # F# functional code review -| |-- go-reviewer.md # Go code review -| |-- go-build-resolver.md # Go build error resolution -| |-- python-reviewer.md # Python code review -| |-- database-reviewer.md # Database/Supabase review -| |-- typescript-reviewer.md # TypeScript/JavaScript code review -| |-- java-reviewer.md # Java/Spring Boot code review -| |-- java-build-resolver.md # Java/Maven/Gradle build errors -| |-- kotlin-reviewer.md # Kotlin/Android/KMP code review -| |-- kotlin-build-resolver.md # Kotlin/Gradle build errors -| |-- harmonyos-app-resolver.md # HarmonyOS/ArkTS app development -| |-- rust-reviewer.md # Rust code review -| |-- rust-build-resolver.md # Rust build error resolution -| |-- pytorch-build-resolver.md # PyTorch/CUDA training errors -| |-- mle-reviewer.md # Production ML pipeline, eval, serving, and monitoring review -| -|-- skills/ # Workflow definitions and domain knowledge -| |-- coding-standards/ # Language best practices -| |-- clickhouse-io/ # ClickHouse analytics, queries, data engineering -| |-- backend-patterns/ # API, database, caching patterns -| |-- frontend-patterns/ # React, Next.js patterns -| |-- frontend-slides/ # HTML slide decks and PPTX-to-web presentation workflows (NEW) -| |-- article-writing/ # Long-form writing in a supplied voice without generic AI tone (NEW) -| |-- content-engine/ # Multi-platform social content and repurposing workflows (NEW) -| |-- market-research/ # Source-attributed market, competitor, and investor research (NEW) -| |-- investor-materials/ # Pitch decks, one-pagers, memos, and financial models (NEW) -| |-- investor-outreach/ # Personalized fundraising outreach and follow-up (NEW) -| |-- continuous-learning/ # Legacy v1 Stop-hook pattern extraction -| |-- continuous-learning-v2/ # Instinct-based learning with confidence scoring -| |-- iterative-retrieval/ # Progressive context refinement for subagents -| |-- strategic-compact/ # Manual compaction suggestions (Longform Guide) -| |-- tdd-workflow/ # TDD methodology -| |-- security-review/ # Security checklist -| |-- eval-harness/ # Verification loop evaluation (Longform Guide) -| |-- verification-loop/ # Continuous verification (Longform Guide) -| |-- videodb/ # Video and audio: ingest, search, edit, generate, stream (NEW) -| |-- golang-patterns/ # Go idioms and best practices -| |-- golang-testing/ # Go testing patterns, TDD, benchmarks -| |-- cpp-coding-standards/ # C++ coding standards from C++ Core Guidelines (NEW) -| |-- cpp-testing/ # C++ testing with GoogleTest, CMake/CTest (NEW) -| |-- django-patterns/ # Django patterns, models, views (NEW) -| |-- django-security/ # Django security best practices (NEW) -| |-- django-tdd/ # Django TDD workflow (NEW) -| |-- django-verification/ # Django verification loops (NEW) -| |-- laravel-patterns/ # Laravel architecture patterns (NEW) -| |-- laravel-security/ # Laravel security best practices (NEW) -| |-- laravel-tdd/ # Laravel TDD workflow (NEW) -| |-- laravel-verification/ # Laravel verification loops (NEW) -| |-- python-patterns/ # Python idioms and best practices (NEW) -| |-- python-testing/ # Python testing with pytest (NEW) -| |-- quarkus-patterns/ # Java Quarkus patterns (NEW) -| |-- quarkus-security/ # Quarkus security (NEW) -| |-- quarkus-tdd/ # Quarkus TDD (NEW) -| |-- quarkus-verification/ # Quarkus verification (NEW) -| |-- springboot-patterns/ # Java Spring Boot patterns (NEW) -| |-- springboot-security/ # Spring Boot security (NEW) -| |-- springboot-tdd/ # Spring Boot TDD (NEW) -| |-- springboot-verification/ # Spring Boot verification (NEW) -| |-- configure-ecc/ # Interactive installation wizard (NEW) -| |-- security-scan/ # AgentShield security auditor integration (NEW) -| |-- java-coding-standards/ # Java coding standards (NEW) -| |-- jpa-patterns/ # JPA/Hibernate patterns (NEW) -| |-- postgres-patterns/ # PostgreSQL optimization patterns (NEW) -| |-- nutrient-document-processing/ # Document processing with Nutrient API (NEW) -| |-- docs/examples/project-guidelines-template.md # Template for project-specific skills -| |-- database-migrations/ # Migration patterns (Prisma, Drizzle, Django, Go) (NEW) -| |-- api-design/ # REST API design, pagination, error responses (NEW) -| |-- deployment-patterns/ # CI/CD, Docker, health checks, rollbacks (NEW) -| |-- docker-patterns/ # Docker Compose, networking, volumes, container security (NEW) -| |-- e2e-testing/ # Playwright E2E patterns and Page Object Model (NEW) -| |-- content-hash-cache-pattern/ # SHA-256 content hash caching for file processing (NEW) -| |-- cost-aware-llm-pipeline/ # LLM cost optimization, model routing, budget tracking (NEW) -| |-- regex-vs-llm-structured-text/ # Decision framework: regex vs LLM for text parsing (NEW) -| |-- swift-actor-persistence/ # Thread-safe Swift data persistence with actors (NEW) -| |-- swift-protocol-di-testing/ # Protocol-based DI for testable Swift code (NEW) -| |-- search-first/ # Research-before-coding workflow (NEW) -| |-- skill-stocktake/ # Audit skills and commands for quality (NEW) -| |-- liquid-glass-design/ # iOS 26 Liquid Glass design system (NEW) -| |-- foundation-models-on-device/ # Apple on-device LLM with FoundationModels (NEW) -| |-- swift-concurrency-6-2/ # Swift 6.2 Approachable Concurrency (NEW) -| |-- mle-workflow/ # Production ML data contracts, evals, deployment, monitoring (NEW) -| |-- perl-patterns/ # Modern Perl 5.36+ idioms and best practices (NEW) -| |-- perl-security/ # Perl security patterns, taint mode, safe I/O (NEW) -| |-- perl-testing/ # Perl TDD with Test2::V0, prove, Devel::Cover (NEW) -| |-- autonomous-loops/ # Autonomous loop patterns: sequential pipelines, PR loops, DAG orchestration (NEW) -| |-- plankton-code-quality/ # Write-time code quality enforcement with Plankton hooks (NEW) -| |-- codehealth-mcp/ # Optional CodeScene Code Health MCP skill (opt-in; not enabled by default) (NEW) -| -|-- commands/ # Maintained slash-entry compatibility; prefer skills/ -| |-- plan.md # /plan - Implementation planning -| |-- code-review.md # /code-review - Quality review -| |-- build-fix.md # /build-fix - Fix build errors -| |-- refactor-clean.md # /refactor-clean - Dead code removal -| |-- quality-gate.md # /quality-gate - Verification gate -| |-- learn.md # /learn - Extract patterns mid-session (Longform Guide) -| |-- learn-eval.md # /learn-eval - Extract, evaluate, and save patterns (NEW) -| |-- checkpoint.md # /checkpoint - Save verification state (Longform Guide) -| |-- setup-pm.md # /setup-pm - Configure package manager -| |-- go-review.md # /go-review - Go code review (NEW) -| |-- go-test.md # /go-test - Go TDD workflow (NEW) -| |-- go-build.md # /go-build - Fix Go build errors (NEW) -| |-- skill-create.md # /skill-create - Generate skills from git history (NEW) -| |-- instinct-status.md # /instinct-status - View learned instincts (NEW) -| |-- instinct-import.md # /instinct-import - Import instincts (NEW) -| |-- instinct-export.md # /instinct-export - Export instincts (NEW) -| |-- evolve.md # /evolve - Cluster instincts into skills -| |-- prune.md # /prune - Delete expired pending instincts (NEW) -| |-- pm2.md # /pm2 - PM2 service lifecycle management (NEW) -| |-- multi-plan.md # /multi-plan - Multi-agent task decomposition (NEW) -| |-- multi-execute.md # /multi-execute - Orchestrated multi-agent workflows (NEW) -| |-- multi-backend.md # /multi-backend - Backend multi-service orchestration (NEW) -| |-- multi-frontend.md # /multi-frontend - Frontend multi-service orchestration (NEW) -| |-- multi-workflow.md # /multi-workflow - General multi-service workflows (NEW) -| |-- sessions.md # /sessions - Session history management -| |-- test-coverage.md # /test-coverage - Test coverage analysis -| |-- update-docs.md # /update-docs - Update documentation -| |-- update-codemaps.md # /update-codemaps - Update codemaps -| |-- python-review.md # /python-review - Python code review (NEW) -|-- legacy-command-shims/ # Opt-in archive for retired shims such as /tdd and /eval -| |-- tdd.md # /tdd - Prefer the tdd-workflow skill -| |-- e2e.md # /e2e - Prefer the e2e-testing skill -| |-- eval.md # /eval - Prefer the eval-harness skill -| |-- verify.md # /verify - Prefer the verification-loop skill -| |-- orchestrate.md # /orchestrate - Prefer dmux-workflows or multi-workflow -| -|-- rules/ # Always-follow guidelines (copy to ~/.claude/rules/ecc/) -| |-- README.md # Structure overview and installation guide -| |-- common/ # Language-agnostic principles -| | |-- coding-style.md # Immutability, file organization -| | |-- git-workflow.md # Commit format, PR process -| | |-- testing.md # TDD, 80% coverage requirement -| | |-- performance.md # Model selection, context management -| | |-- patterns.md # Design patterns, skeleton projects -| | |-- hooks.md # Hook architecture, TodoWrite -| | |-- agents.md # When to delegate to subagents -| | |-- security.md # Mandatory security checks -| |-- typescript/ # TypeScript/JavaScript specific -| |-- python/ # Python specific -| |-- golang/ # Go specific -| |-- swift/ # Swift specific -| |-- php/ # PHP specific (NEW) -| |-- arkts/ # HarmonyOS / ArkTS specific -| -|-- hooks/ # Trigger-based automations -| |-- README.md # Hook documentation, recipes, and customization guide -| |-- hooks.json # All hooks config (PreToolUse, PostToolUse, Stop, etc.) -| |-- memory-persistence/ # Session lifecycle hooks (Longform Guide) -| |-- strategic-compact/ # Compaction suggestions (Longform Guide) -| -|-- scripts/ # Cross-platform Node.js scripts (NEW) -| |-- lib/ # Shared utilities -| | |-- utils.js # Cross-platform file/path/system utilities -| | |-- package-manager.js # Package manager detection and selection -| |-- hooks/ # Hook implementations -| | |-- session-start.js # Load context on session start -| | |-- session-end.js # Save state on session end -| | |-- pre-compact.js # Pre-compaction state saving -| | |-- suggest-compact.js # Strategic compaction suggestions -| | |-- evaluate-session.js # Extract patterns from sessions -| |-- setup-package-manager.js # Interactive PM setup -| -|-- tests/ # Test suite (NEW) -| |-- lib/ # Library tests -| |-- hooks/ # Hook tests -| |-- run-all.js # Run all tests -| -|-- contexts/ # Dynamic system prompt injection contexts (Longform Guide) -| |-- dev.md # Development mode context -| |-- review.md # Code review mode context -| |-- research.md # Research/exploration mode context -| -|-- examples/ # Example configurations and sessions -| |-- CLAUDE.md # Example project-level config -| |-- user-CLAUDE.md # Example user-level config -| |-- saas-nextjs-CLAUDE.md # Real-world SaaS (Next.js + Supabase + Stripe) -| |-- go-microservice-CLAUDE.md # Real-world Go microservice (gRPC + PostgreSQL) -| |-- django-api-CLAUDE.md # Real-world Django REST API (DRF + Celery) -| |-- laravel-api-CLAUDE.md # Real-world Laravel API (PostgreSQL + Redis) (NEW) -| |-- rust-api-CLAUDE.md # Real-world Rust API (Axum + SQLx + PostgreSQL) (NEW) -| -|-- mcp-configs/ # MCP server configurations -| |-- mcp-servers.json # GitHub, Supabase, Vercel, Railway, etc. -| -|-- ecc_dashboard.py # Desktop GUI dashboard (Tkinter) -| -|-- assets/ # Assets for dashboard -| |-- images/ -| |-- ecc-logo.png -| -|-- marketplace.json # Self-hosted marketplace config (for /plugin marketplace add) +|-- skills/ # 281 reusable workflows loaded on demand +|-- commands/ # 94 maintained slash-command shims +|-- rules/ # opt-in common and language standards +|-- hooks/ # runtime automation and enforcement +|-- scripts/ # install, repair, sync, orchestration, and checks +|-- .claude-plugin/ # Claude Code marketplace manifest +|-- .codex/ # Codex reference configuration and agent roles +|-- .opencode/ # OpenCode plugin, commands, and instructions +|-- .cursor/ # Cursor rules and hook adapter +|-- docs/ # public setup, architecture, and operating guides ``` ---- - -## Ecosystem Tools - -### Skill Creator - -Two ways to generate Claude Code skills from your repository: - -#### Option A: Local Analysis (Built-in) - -Use the `/skill-create` command for local analysis without external services: - -```bash -/skill-create # Analyze current repo -/skill-create --instincts # Also generate instincts for continuous-learning-v2 -``` - -This analyzes your git history locally and generates SKILL.md files. - -#### Option B: GitHub App (Advanced) - -For advanced features (10k+ commits, auto-PRs, team sharing): - -[Install ECC Tools GitHub App](https://github.com/apps/ecc-tools) | [ecc.tools](https://ecc.tools) - -```bash -# Comment on any issue: -/ecc-tools analyze - -# Or run against a repo from the hosted app -``` - -Both options create: -- **SKILL.md files** - Ready-to-use skills for the active harness -- **Instinct collections** - For continuous-learning-v2 -- **Pattern extraction** - Learns from your commit history - -### AgentShield — Security Auditor - -> Built at the Claude Code Hackathon (Cerebral Valley x Anthropic, Feb 2026). 1282 tests, 98% coverage, 102 static analysis rules. - -Scan your Claude Code configuration for vulnerabilities, misconfigurations, and injection risks. - -```bash -# Quick scan (no install needed) -npx ecc-agentshield scan - -# Auto-fix safe issues -npx ecc-agentshield scan --fix - -# Deep analysis with three Opus 4.6 agents -npx ecc-agentshield scan --opus --stream - -# Generate secure config from scratch -npx ecc-agentshield init -``` - -**What it scans:** CLAUDE.md, settings.json, MCP configs, hooks, agent definitions, and skills across 5 categories — secrets detection (14 patterns), permission auditing, hook injection analysis, MCP server risk profiling, and agent config review. - -**The `--opus` flag** runs three Claude Opus 4.6 agents in a red-team/blue-team/auditor pipeline. The attacker finds exploit chains, the defender evaluates protections, and the auditor synthesizes both into a prioritized risk assessment. Adversarial reasoning, not just pattern matching. - -**Output formats:** Terminal (color-graded A-F), JSON (CI pipelines), Markdown, HTML. Exit code 2 on critical findings for build gates. - -Use `/security-scan` in Claude Code to run it, or add to CI with the [GitHub Action](https://github.com/affaan-m/agentshield). - -[GitHub](https://github.com/affaan-m/agentshield) | [npm](https://www.npmjs.com/package/ecc-agentshield) - -### Continuous Learning v2 - -The instinct-based learning system automatically learns your patterns: - -```bash -/instinct-status # Show learned instincts with confidence -/instinct-import # Import instincts from others -/instinct-export # Export your instincts for sharing -/evolve # Cluster related instincts into skills -``` - -See `skills/continuous-learning-v2/` for full documentation. -Keep `continuous-learning/` only when you explicitly want the legacy v1 Stop-hook learned-skill flow. - ---- - -## Requirements - -### Claude Code CLI Version - -**Minimum version: v2.1.0 or later** - -This plugin requires Claude Code CLI v2.1.0+ due to changes in how the plugin system handles hooks. - -Check your version: -```bash -claude --version -``` - -### Important: Hooks Auto-Loading Behavior - -> WARNING: **For Contributors:** Do NOT add a `"hooks"` field to `.claude-plugin/plugin.json`. This is enforced by a regression test. - -Claude Code v2.1+ **automatically loads** `hooks/hooks.json` from any installed plugin by convention. Explicitly declaring it in `plugin.json` causes a duplicate detection error: - -``` -Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file -``` - -**History:** This has caused repeated fix/revert cycles in this repo ([#29](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. We now have a regression test to prevent this from being reintroduced. - ---- - -## Installation - -### Option 1: Install as Plugin (Recommended) - -The easiest way to use this repo - install as a Claude Code plugin: - -```bash -# Add this repo as a marketplace -/plugin marketplace add https://github.com/affaan-m/ECC - -# Install the plugin -/plugin install ecc@ecc -``` - -Or add directly to your `~/.claude/settings.json`: - -```json -{ - "extraKnownMarketplaces": { - "ecc": { - "source": { - "source": "github", - "repo": "affaan-m/ECC" - } - } - }, - "enabledPlugins": { - "ecc@ecc": true - } -} -``` - -This gives you instant access to all commands, agents, skills, and hooks. - -> **Note:** The Claude Code plugin system does not support distributing `rules` via plugins ([upstream limitation](https://code.claude.com/docs/en/plugins-reference)). You need to install rules manually: -> -> ```bash -> # Clone the repo first -> git clone https://github.com/affaan-m/ECC.git -> cd ECC -> -> # Option A: User-level rules (applies to all projects) -> mkdir -p ~/.claude/rules/ecc -> cp -r rules/common ~/.claude/rules/ecc/ -> cp -r rules/typescript ~/.claude/rules/ecc/ # pick your stack -> cp -r rules/python ~/.claude/rules/ecc/ -> cp -r rules/golang ~/.claude/rules/ecc/ -> cp -r rules/php ~/.claude/rules/ecc/ -> -> # Option B: Project-level rules (applies to current project only) -> mkdir -p .claude/rules/ecc -> cp -r rules/common .claude/rules/ecc/ -> cp -r rules/typescript .claude/rules/ecc/ # pick your stack -> ``` - ---- - -### Option 2: Manual Installation - -If you prefer manual control over what's installed: - -```bash -# Clone the repo -git clone https://github.com/affaan-m/ECC.git -cd ECC - -# Copy agents to your Claude config -cp agents/*.md ~/.claude/agents/ - -# Copy rules directories (common + language-specific) -mkdir -p ~/.claude/rules/ecc -cp -r rules/common ~/.claude/rules/ecc/ -cp -r rules/typescript ~/.claude/rules/ecc/ # pick your stack -cp -r rules/python ~/.claude/rules/ecc/ -cp -r rules/golang ~/.claude/rules/ecc/ -cp -r rules/php ~/.claude/rules/ecc/ -cp -r rules/arkts ~/.claude/rules/ecc/ - -# Copy skills first (primary workflow surface) -# Recommended (new users): core/general skills only -mkdir -p ~/.claude/skills -cp -r .agents/skills/* ~/.claude/skills/ -cp -r skills/search-first ~/.claude/skills/ -# Claude Code loads skills only from direct children of ~/.claude/skills. -# Do not nest manual installs under ~/.claude/skills/ecc/. - -# Optional: add niche/framework-specific skills only when needed -# for s in django-patterns django-tdd laravel-patterns springboot-patterns quarkus-patterns; do -# cp -r skills/$s ~/.claude/skills/ -# done - -# Optional: keep maintained slash-command compatibility during migration -mkdir -p ~/.claude/commands -cp commands/*.md ~/.claude/commands/ - -# Retired shims live in legacy-command-shims/commands/. -# Copy individual files from there only if you still need old names such as /tdd. -``` - -#### Install hooks - -Do not copy the raw repo `hooks/hooks.json` into `~/.claude/settings.json` or `~/.claude/hooks/hooks.json`. That file is plugin/repo-oriented and is meant to be installed through the ECC installer or loaded as a plugin, so raw copying is not a supported manual install path. - -Use the installer to install only the Claude hook runtime so command paths are rewritten correctly: - -```bash -# macOS / Linux -bash ./install.sh --target claude --modules hooks-runtime -``` - -```powershell -# Windows PowerShell -pwsh -File .\install.ps1 --target claude --modules hooks-runtime -``` - -That writes resolved hooks to `~/.claude/hooks/hooks.json` and leaves any existing `~/.claude/settings.json` untouched. - -If you installed ECC via `/plugin install`, do not copy those hooks into `settings.json`. Claude Code v2.1+ already auto-loads plugin `hooks/hooks.json`, and duplicating them in `settings.json` causes duplicate execution and cross-platform hook conflicts. - -Windows note: the Claude config directory is `%USERPROFILE%\\.claude`, not `~/claude`. - -#### Configure MCPs - -Claude plugin installs intentionally do not auto-enable ECC's bundled MCP server definitions. This avoids overlong plugin MCP tool names on strict third-party gateways while keeping manual MCP setup available. - -Use Claude Code's `/mcp` command or CLI-managed MCP setup for live Claude Code server changes. Use `/mcp` for Claude Code runtime disables; Claude Code persists those choices in `~/.claude.json`. - -For repo-local MCP access, copy desired MCP server definitions from `mcp-configs/mcp-servers.json` into a project-scoped `.mcp.json`. - -ECC ships exactly one default connector (`chrome-devtools`); everything else is a skill wrapping a CLI/REST API or an opt-in catalog entry. The rule and the June 2026 audit that retired the previous six defaults live in [docs/MCP-CONNECTOR-POLICY.md](docs/MCP-CONNECTOR-POLICY.md). - -If you already run your own copies of ECC-bundled MCPs, set: - -```bash -export ECC_DISABLED_MCPS="chrome-devtools" -``` - -ECC-managed install and Codex sync flows will skip or remove those bundled servers instead of re-adding duplicates. `ECC_DISABLED_MCPS` is an ECC install/sync filter, not a live Claude Code toggle. - -**Important:** Replace `YOUR_*_HERE` placeholders with your actual API keys. - ---- - -## Key Concepts - -### Agents - -Subagents handle delegated tasks with limited scope. Example: - -```markdown ---- -name: code-reviewer -description: Reviews code for quality, security, and maintainability -tools: Read, Grep, Glob, Bash -model: opus ---- - -You are a senior code reviewer... -``` - -### Skills - -Skills are the primary workflow surface. They can be invoked directly, suggested automatically, and reused by agents. ECC still ships maintained `commands/` during migration, while retired short-name shims live under `legacy-command-shims/` for explicit opt-in only. New workflow development should land in `skills/` first. - -```markdown -# TDD Workflow - -1. Define interfaces first -2. Write failing tests (RED) -3. Implement minimal code (GREEN) -4. Refactor (IMPROVE) -5. Verify 80%+ coverage -``` - -### Hooks - -Hooks fire on tool events. Example - warn about console.log: - -```json -{ - "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"", - "hooks": [{ - "type": "command", - "command": "#!/bin/bash\ngrep -n 'console\\.log' \"$file_path\" && echo '[Hook] Remove console.log' >&2" - }] -} -``` - -### Rules - -Rules are always-follow guidelines, organized into `common/` (language-agnostic) + language-specific directories: - -``` -rules/ - common/ # Universal principles (always install) - typescript/ # TS/JS specific patterns and tools - python/ # Python specific patterns and tools - golang/ # Go specific patterns and tools - swift/ # Swift specific patterns and tools - php/ # PHP specific patterns and tools - arkts/ # HarmonyOS / ArkTS patterns and constraints -``` - -See [`rules/README.md`](rules/README.md) for installation and structure details. - ---- - -## Which Agent Should I Use? - -Not sure where to start? Use this quick reference. Skills are the canonical workflow surface; maintained slash entries stay available for command-first workflows. - -| I want to... | Use this surface | Agent used | -|--------------|-----------------|------------| -| Plan a new feature | `/ecc:plan "Add auth"` | planner | -| Design system architecture | `/ecc:plan` + architect agent | architect | -| Write code with tests first | `tdd-workflow` skill | tdd-guide | -| Review code I just wrote | `/code-review` | code-reviewer | -| Fix a failing build | `/build-fix` | build-error-resolver | -| Run end-to-end tests | `e2e-testing` skill | e2e-runner | -| Find security vulnerabilities | `/security-scan` | security-reviewer | -| Remove dead code | `/refactor-clean` | refactor-cleaner | -| Update documentation | `/update-docs` | doc-updater | -| Review Go code | `/go-review` | go-reviewer | -| Review Python code | `/python-review` | python-reviewer | -| Review F# code | *(invoke `fsharp-reviewer` directly)* | fsharp-reviewer | -| Review TypeScript/JavaScript code | *(invoke `typescript-reviewer` directly)* | typescript-reviewer | -| Develop HarmonyOS apps | *(invoke `harmonyos-app-resolver` directly)* | harmonyos-app-resolver | -| Audit database queries | *(auto-delegated)* | database-reviewer | -| Review production ML changes | `mle-workflow` skill + `mle-reviewer` agent | mle-reviewer | - -### Common Workflows - -Slash forms below are shown where they remain part of the maintained command surface. Retired short-name shims such as `/tdd` and `/eval` live in `legacy-command-shims/` for explicit opt-in only. - -**Starting a new feature:** -``` -/ecc:plan "Add user authentication with OAuth" - → planner creates implementation blueprint -tdd-workflow skill → tdd-guide enforces write-tests-first -/code-review → code-reviewer checks your work -``` - -**Fixing a bug:** -``` -tdd-workflow skill → tdd-guide: write a failing test that reproduces it - → implement the fix, verify test passes -/code-review → code-reviewer: catch regressions -``` - -**Preparing for production:** -``` -/security-scan → security-reviewer: OWASP Top 10 audit -e2e-testing skill → e2e-runner: critical user flow tests -/test-coverage → verify 80%+ coverage -``` - ---- - -## FAQ - -
-How do I check which agents/commands are installed? - -```bash -/plugin list ecc@ecc -``` - -This shows all available agents, commands, and skills from the plugin. +The root is the source of truth. Platform adapters package or map these same workflows instead of maintaining separate copies.
-My hooks aren't working / I see "Duplicate hooks file" errors - -This is the most common issue. **Do NOT add a `"hooks"` field to `.claude-plugin/plugin.json`.** Claude Code v2.1+ automatically loads `hooks/hooks.json` from installed plugins. Explicitly declaring it causes duplicate detection errors. See [#29](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). -
- -
-Can I use ECC with Claude Code on a custom API endpoint or model gateway? - -Yes. ECC does not hardcode Anthropic-hosted transport settings. It runs locally through Claude Code's normal CLI/plugin surface, so it works with: - -- Anthropic-hosted Claude Code -- Official Claude Code gateway setups using `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` -- Compatible custom endpoints that speak the Anthropic API Claude Code expects - -Minimal example: - -```bash -export ANTHROPIC_BASE_URL=https://your-gateway.example.com -export ANTHROPIC_AUTH_TOKEN=your-token -claude -``` - -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. - -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. That sponsorship link is passive: it does not invoke an RFQ, reserve capacity, provision compute, or configure serving. Separately, the opt-in `ecc ito find` bridge 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. - -### Itô compute CLI bridge - -`ecc ito` delegates to the separately installed canonical Itô client; ECC does -not maintain a second API client or browser handoff. The available operations -are `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`; node qualification is CLI-only. - -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. -Inject `ITO_API_KEY` from 1Password or the launching environment. 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. - -`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. - -Official references: -- [Claude Code LLM gateway docs](https://docs.anthropic.com/en/docs/claude-code/llm-gateway) -- [Claude Code model configuration docs](https://docs.anthropic.com/en/docs/claude-code/model-config) - -
- -
-My context window is shrinking / Claude is running out of context - -Too many MCP servers eat your context. Each MCP tool description consumes tokens from your 200k window, potentially reducing it to ~70k. SessionStart context is capped at 8000 characters by default; lower it with `ECC_SESSION_START_MAX_CHARS=4000` or disable it with `ECC_SESSION_START_CONTEXT=off` for local-model or low-context setups. - -**Fix:** Disable unused MCPs from Claude Code with `/mcp`. Claude Code writes those runtime choices to `~/.claude.json`; `.claude/settings.json` and `.claude/settings.local.json` are not reliable toggles for already-loaded MCP servers. - -Keep under 10 MCPs enabled and under 80 tools active. -
- -
-Can I use only some components (e.g., just agents)? - -Yes. Use Option 2 (manual installation) and copy only what you need: - -```bash -# Just agents -cp agents/*.md ~/.claude/agents/ - -# Just rules -mkdir -p ~/.claude/rules/ecc/ -cp -r rules/common ~/.claude/rules/ecc/ -``` - -Each component is fully independent. -
- -
-Does this work with Cursor / OpenCode / Codex / Antigravity / GitHub Copilot? - -Yes. ECC is cross-platform: -- **Cursor**: Pre-translated configs in `.cursor/`. See [Cursor IDE Support](#cursor-ide-support). -- **Gemini CLI**: Experimental project-local support via `.gemini/GEMINI.md` and shared installer plumbing. -- **OpenCode**: Full plugin support in `.opencode/`. See [OpenCode Support](#opencode-support). -- **Codex**: First-class support for both macOS app and CLI, with adapter drift guards and SessionStart fallback. See PR [#257](https://github.com/affaan-m/ECC/pull/257). -- **GitHub Copilot (VS Code)**: Instruction and prompt layer via `.github/copilot-instructions.md`, `.vscode/settings.json`, and `.github/prompts/`. See [GitHub Copilot Support](#github-copilot-support). -- **Antigravity**: Tightly integrated setup for workflows, skills, and flattened rules in `.agent/`. See [Antigravity Guide](docs/ANTIGRAVITY-GUIDE.md). -- **JoyCode / CodeBuddy**: Project-local selective install adapters for commands, agents, skills, and flattened rules. See [JoyCode Adapter Guide](docs/JOYCODE-GUIDE.md). -- **Qwen CLI**: Home-directory selective install adapter for commands, agents, skills, rules, and Qwen config. See [Qwen CLI Adapter Guide](docs/QWEN-GUIDE.md). -- **Zed**: Project-local selective install adapter for `.zed/settings.json`, flattened rules, commands, agents, and skills. -- **Non-native harnesses**: Manual fallback path for Grok and similar interfaces. See [Manual Adaptation Guide](docs/MANUAL-ADAPTATION-GUIDE.md). -- **Claude Code**: Native — this is the primary target. -
- -
-How do I contribute a new skill or agent? - -See [CONTRIBUTING.md](CONTRIBUTING.md). The short version: -1. Fork the repo -2. Create your skill in `skills/your-skill-name/SKILL.md` (with YAML frontmatter) -3. Or create an agent in `agents/your-agent.md` -4. Submit a PR with a clear description of what it does and when to use it -
- ---- - -## Running Tests - -The plugin includes a comprehensive test suite: - -```bash -# Run all tests -node tests/run-all.js - -# Run individual test files -node tests/lib/utils.test.js -node tests/lib/package-manager.test.js -node tests/hooks/hooks.test.js -``` - ---- - -## Contributing - -**Contributions are welcome and encouraged.** - -This repo is meant to be a community resource. If you have: -- Useful agents or skills -- Clever hooks -- Better MCP configurations -- Improved rules - -Please contribute! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. - -### Ideas for Contributions - -- Language-specific skills (Rust, C#, Kotlin, Java) — Go, Python, Perl, Swift, TypeScript, and HarmonyOS/ArkTS already included -- Framework-specific configs (Rails, FastAPI) — Django, NestJS, Spring Boot, and Laravel already included -- DevOps agents (Kubernetes, Terraform, AWS, Docker) -- Testing strategies (different frameworks, visual regression) -- Domain-specific knowledge (ML, data engineering, mobile) - ---- - -## Cursor IDE Support - -ECC provides Cursor IDE support with hooks, rules, agents, skills, commands, and MCP configs adapted for Cursor's project layout. - -### Quick Start (Cursor) - -```bash -# macOS/Linux -./install.sh --target cursor typescript -./install.sh --target cursor python golang swift php -``` - -```powershell -# Windows PowerShell -.\install.ps1 --target cursor typescript -.\install.ps1 --target cursor python golang swift php -``` - -### What's Included - -| Component | Count | Details | -|-----------|-------|---------| -| Hook Events | 15 | sessionStart, beforeShellExecution, afterFileEdit, beforeMCPExecution, beforeSubmitPrompt, and 10 more | -| Hook Scripts | 16 | Thin Node.js scripts delegating to `scripts/hooks/` via shared adapter | -| Rules | 34 | 9 common (alwaysApply) + 25 language-specific (TypeScript, Python, Go, Swift, PHP) | -| Agents | 48 | `.cursor/agents/ecc-*.md` when installed; prefixed to avoid collisions with user or marketplace agents | -| Skills | Shared + Bundled | `.cursor/skills/` for translated additions | -| Commands | Shared | `.cursor/commands/` if installed | -| MCP Config | Shared | `.cursor/mcp.json` if installed | - -### Cursor Loading Notes - -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. - -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. - -### Memory and data isolation (Cursor + Claude Code) - -ECC memory hooks reuse the same `scripts/hooks/*.js` as Claude Code. For Cursor, ECC tries to keep memory **out of `~/.claude` automatically**: - -1. **Cursor `sessionStart` hook** (installed to `.cursor/hooks.json` on `--target cursor`) injects `ECC_AGENT_DATA_HOME` for the whole composer session. -2. **Hook runtime default** — when `CURSOR_VERSION` or `CURSOR_PROJECT_DIR` is present, hooks default to `~/.cursor/ecc` if the env var is unset. -3. **Project config** — `.cursor/ecc-agent-data.json` documents and overrides the path (`agentDataHome`). -4. **Always-on rule** — `.cursor/rules/ecc-agent-data-home.mdc` reminds the agent where memory lives. - -You can still override explicitly: - -```bash -export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc" -``` - -To **share** memory with Claude Code on purpose, set `ECC_AGENT_DATA_HOME=~/.claude` in the shell or in `.cursor/ecc-agent-data.json`. - -Continuous learning v2 instincts remain separate under `CLV2_HOMUNCULUS_DIR` (default `~/.local/share/ecc-homunculus`). - -### Hook Architecture (DRY Adapter Pattern) - -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. - -``` -Cursor stdin JSON → adapter.js → transforms → scripts/hooks/*.js - (shared with Claude Code) -``` - -Key hooks: -- **beforeShellExecution** — Blocks dev servers outside tmux (exit 2), git push review -- **afterFileEdit** — Auto-format + TypeScript check + console.log warning -- **beforeSubmitPrompt** — Detects secrets (sk-, ghp_, AKIA patterns) in prompts -- **beforeTabFileRead** — Blocks Tab from reading .env, .key, .pem files (exit 2) -- **beforeMCPExecution / afterMCPExecution** — MCP audit logging - -### Rules Format - -Cursor rules use YAML frontmatter with `description`, `globs`, and `alwaysApply`: - -```yaml ---- -description: "TypeScript coding style extending common rules" -globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"] -alwaysApply: false ---- -``` - ---- - -## Codex macOS App + CLI Support - -ECC provides **first-class Codex support** for both the macOS app and CLI, with a reference configuration, Codex-specific AGENTS.md supplement, and shared skills. For repo navigation, surface ownership, and PR diff packet guidance, start with [`docs/CODEX-NAVIGATION-GUIDE.md`](docs/CODEX-NAVIGATION-GUIDE.md). - -### Quick Start (Codex App + CLI) - -```bash -# Run Codex CLI in the repo — AGENTS.md and .codex/ are auto-detected -codex - -# Automatic setup: sync ECC assets (AGENTS.md, skills, MCP servers) into ~/.codex -npm install && bash scripts/sync-ecc-to-codex.sh -# or: pnpm install && bash scripts/sync-ecc-to-codex.sh -# or: yarn install && bash scripts/sync-ecc-to-codex.sh -# or: bun install && bash scripts/sync-ecc-to-codex.sh - -# Or manually: copy the reference config to your home directory -cp .codex/config.toml ~/.codex/config.toml -``` - -The sync script safely merges ECC MCP servers into your existing `~/.codex/config.toml` using an **add-only** strategy — it never removes or modifies your existing servers. Run with `--dry-run` to preview changes, or `--update-mcp` to force-refresh ECC servers to the latest recommended config. - -For Context7, ECC uses the canonical Codex section name `[mcp_servers.context7]` while still launching the `@upstash/context7-mcp` package. If you already have a legacy `[mcp_servers.context7-mcp]` entry, `--update-mcp` migrates it to the canonical section name. - -Codex macOS app: -- Open this repository as your workspace. -- The root `AGENTS.md` is auto-detected. -- `.codex/config.toml` and `.codex/agents/*.toml` work best when kept project-local. -- The reference `.codex/config.toml` intentionally does not pin `model` or `model_provider`, so Codex uses its own current default unless you override it. -- 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/`. - -### Codex Plugin Marketplace (experimental) - -The repo also exposes a Codex repo-scoped marketplace (`.agents/plugins/marketplace.json`) whose entry points at the `plugins/ecc/` plugin folder — Codex does not discover plugins whose local marketplace `source.path` is the repository root (`./`), so the entry must target a concrete plugin subdirectory: - -```bash -codex plugin marketplace add affaan-m/ECC -codex plugin list -node scripts/codex/check-plugin-cache.js -``` - -`codex plugin list` only confirms marketplace registration. Run -`node scripts/codex/check-plugin-cache.js` after install to verify that the -installed cache can resolve the manifest's skills, MCP config, and assets. - -**Plugin mode is currently fragile on Codex.** Marketplace discovery and install work with this layout, but runtime skill loading from local/repo marketplaces is still unreliable upstream ([openai/codex#26037](https://github.com/openai/codex/issues/26037)): Codex copies only the plugin folder into its install cache, so plugins that reference shared repo content may not expose skills in a fresh session. If the cache health check reports missing manifest references, treat the plugin path as discovery-only and prefer the manual sync flow above (`scripts/sync-ecc-to-codex.sh`), which is the supported Codex route. See [#2128](https://github.com/affaan-m/ECC/issues/2128) for the full investigation. - -### What's Included - -| Component | Count | Details | -|-----------|-------|---------| -| Config | 1 | `.codex/config.toml` — top-level approvals/sandbox/web_search, MCP servers, notifications, profiles | -| AGENTS.md | 2 | Root (universal) + `.codex/AGENTS.md` (Codex-specific supplement) | -| Skills | 32 | `.agents/skills/` — SKILL.md + agents/openai.yaml per skill | -| MCP Servers | 6 | GitHub, Context7, Exa, Memory, Playwright, Sequential Thinking (7 with Supabase via `--update-mcp` sync) | -| Profiles | 2 | `strict` (read-only sandbox) and `yolo` (full auto-approve) | -| Agent Roles | 3 | `.codex/agents/` — explorer, reviewer, docs-researcher | - -### Skills - -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. - -| Skill | Description | -|-------|-------------| -| agent-introspection-debugging | Debug agent behavior, routing, and prompt boundaries | -| agent-sort | Sort agent catalogs and assignment surfaces | -| api-design | REST API design patterns | -| article-writing | Long-form writing from notes and voice references | -| backend-patterns | API design, database, caching | -| brand-voice | Source-derived writing style profiles from real content | -| bun-runtime | Bun as runtime, package manager, bundler, and test runner | -| coding-standards | Universal coding standards | -| codehealth-mcp | Optional — Code Health MCP (opt-in server + token); structural review and commit/PR gates | -| content-engine | Platform-native social content and repurposing | -| crosspost | Multi-platform content distribution across X, LinkedIn, Threads | -| deep-research | Multi-source research with synthesis and source attribution | -| dmux-workflows | Multi-agent orchestration using tmux pane manager | -| documentation-lookup | Up-to-date library and framework docs via Context7 MCP | -| e2e-testing | Playwright E2E tests | -| eval-harness | Eval-driven development | -| everything-claude-code | Development conventions and patterns for the project | -| exa-search | Neural search via Exa MCP for web, code, company research | -| fal-ai-media | Unified media generation for images, video, and audio | -| frontend-patterns | React/Next.js patterns | -| frontend-slides | HTML presentations, PPTX conversion, visual style exploration | -| investor-materials | Decks, memos, models, and one-pagers | -| investor-outreach | Personalized outreach, follow-ups, and intro blurbs | -| market-research | Source-attributed market and competitor research | -| mcp-server-patterns | Build MCP servers with Node/TypeScript SDK | -| nextjs-turbopack | Next.js 16+ and Turbopack incremental bundling | -| product-capability | Translate product goals into scoped capability maps | -| security-review | Comprehensive security checklist | -| strategic-compact | Context management | -| tdd-workflow | Test-driven development with 80%+ coverage | -| verification-loop | Build, test, lint, typecheck, security | -| video-editing | AI-assisted video editing workflows with FFmpeg and Remotion | -| x-api | X/Twitter API integration for posting and analytics | - -### Key Limitation - -Codex does **not yet provide Claude-style hook execution parity**. ECC enforcement there is instruction-based via `AGENTS.md`, optional `model_instructions_file` overrides, and sandbox/approval settings. - -### Multi-Agent Support - -Current Codex builds support stable multi-agent workflows. - -- Enable `features.multi_agent = true` in `.codex/config.toml` -- Define roles under `[agents.]` -- Point each role at a file under `.codex/agents/` -- Use `/agent` in the CLI to inspect or steer child agents - -ECC ships three sample role configs: - -| Role | Purpose | -|------|---------| -| `explorer` | Read-only codebase evidence gathering before edits | -| `reviewer` | Correctness, security, and missing-test review | -| `docs_researcher` | Documentation and API verification before release/docs changes | - ---- - -## Zed Support - -ECC provides Zed project support through a conservative `.zed` adapter for project-local settings, flattened rules, agents, commands, and skills. - -```bash -./install.sh --profile minimal --target zed -``` - -```powershell -.\install.ps1 --profile minimal --target zed -``` - -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. - ---- - -## OpenCode Support - -ECC provides **full OpenCode support** including plugins and hooks. - -### Quick Start - -```bash -# Install OpenCode -npm install -g opencode - -# Run in the repository root -opencode -``` - -The configuration is automatically detected from `.opencode/opencode.json`. - -### Feature Parity - -| Feature | Claude Code | OpenCode | Status | -|---------|---------------------|----------|--------| -| Agents | PASS: 67 agents | PASS: 12 agents | **Claude Code leads** | -| Commands | PASS: 94 commands | PASS: 35 commands | **Claude Code leads** | -| Skills | PASS: 281 skills | PASS: 37 skills | **Claude Code leads** | -| Hooks | PASS: 8 event types | PASS: 11 events | **OpenCode has more!** | -| Rules | PASS: 29 rules | PASS: 13 instructions | **Claude Code leads** | -| MCP Servers | PASS: 14 servers | PASS: Full | **Full parity** | -| Custom Tools | PASS: Via hooks | PASS: 6 native tools | **OpenCode is better** | - -### Hook Support via Plugins - -OpenCode's plugin system is MORE sophisticated than Claude Code with 20+ event types: - -| Claude Code Hook | OpenCode Plugin Event | -|-----------------|----------------------| -| PreToolUse | `tool.execute.before` | -| PostToolUse | `tool.execute.after` | -| Stop | `session.idle` | -| SessionStart | `session.created` | -| SessionEnd | `session.deleted` | - -**Additional OpenCode events**: `file.edited`, `file.watcher.updated`, `message.updated`, `lsp.client.diagnostics`, `tui.toast.show`, and more. - -### Maintained Slash Entries - -| Command | Description | -|---------|-------------| -| `/plan` | Create implementation plan | -| `/code-review` | Review code changes | -| `/build-fix` | Fix build errors | -| `/refactor-clean` | Remove dead code | -| `/learn` | Extract patterns from session | -| `/checkpoint` | Save verification state | -| `/quality-gate` | Run the maintained verification gate | -| `/update-docs` | Update documentation | -| `/update-codemaps` | Update codemaps | -| `/test-coverage` | Analyze coverage | -| `/go-review` | Go code review | -| `/go-test` | Go TDD workflow | -| `/go-build` | Fix Go build errors | -| `/python-review` | Python code review (PEP 8, type hints, security) | -| `/multi-plan` | Multi-model collaborative planning | -| `/multi-execute` | Multi-model collaborative execution | -| `/multi-backend` | Backend-focused multi-model workflow | -| `/multi-frontend` | Frontend-focused multi-model workflow | -| `/multi-workflow` | Full multi-model development workflow | -| `/pm2` | Auto-generate PM2 service commands | -| `/sessions` | Manage session history | -| `/skill-create` | Generate skills from git | -| `/instinct-status` | View learned instincts | -| `/instinct-import` | Import instincts | -| `/instinct-export` | Export instincts | -| `/evolve` | Cluster instincts into skills | -| `/promote` | Promote project instincts to global scope | -| `/projects` | List known projects and instinct stats | -| `/prune` | Delete expired pending instincts (30d TTL) | -| `/learn-eval` | Extract and evaluate patterns before saving | -| `/setup-pm` | Configure package manager | -| `/harness-audit` | Audit harness reliability, eval readiness, and risk posture | -| `/loop-start` | Start controlled agentic loop execution pattern | -| `/loop-status` | Inspect active loop status and checkpoints | -| `/quality-gate` | Run quality gate checks for paths or entire repo | -| `/model-route` | Route tasks to models by complexity and budget | - -### Plugin Installation - -**Option 1: Use directly** -```bash -cd ECC -opencode -``` - -**Option 2: Install as npm package** -```bash -npm install ecc-universal -``` - -Then add to your `opencode.json`: -```json -{ - "plugin": ["ecc-universal"] -} -``` - -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. - -For the full ECC OpenCode setup, either: -- run OpenCode inside this repository, or -- copy the bundled `.opencode/` config assets into your project and wire the `instructions`, `agent`, and `command` entries in `opencode.json` - -### Documentation - -- **Migration Guide**: `.opencode/MIGRATION.md` -- **OpenCode Plugin README**: `.opencode/README.md` -- **Consolidated Rules**: `.opencode/instructions/INSTRUCTIONS.md` -- **LLM Documentation**: `llms.txt` (complete OpenCode docs for LLMs) - ---- - -## GitHub Copilot Support - -ECC provides **GitHub Copilot support** for VS Code via Copilot Chat's native instruction and prompt file system — no extra tooling required. - -### What's Included - -| Component | File | Purpose | -|-----------|------|---------| -| Core instructions | `.github/copilot-instructions.md` | Always-loaded rules: coding style, security, testing, git workflow | -| VS Code settings | `.vscode/settings.json` | Per-task instruction files for code gen, test gen, and commit messages | -| Plan prompt | `.github/prompts/plan.prompt.md` | Phased implementation planning | -| TDD prompt | `.github/prompts/tdd.prompt.md` | Red-Green-Improve cycle | -| Security review prompt | `.github/prompts/security-review.prompt.md` | Deep OWASP-aligned security analysis | -| Build fix prompt | `.github/prompts/build-fix.prompt.md` | Systematic build and CI error resolution | -| Refactor prompt | `.github/prompts/refactor.prompt.md` | Dead code cleanup and simplification | - -### Quick Start (GitHub Copilot) - -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/`. - -To use the workflow prompts in Copilot Chat: -1. Open the Copilot Chat panel in VS Code. -2. Click the **paperclip / attach** icon and select **Prompt...**, or type `/` and choose a prompt. -3. Select the prompt (e.g. `plan`, `tdd`, `security-review`). - -### How It Works - -GitHub Copilot in VS Code reads two types of files automatically: - -- **`.github/copilot-instructions.md`** — repository-level instructions, always injected into every Copilot Chat request. Contains ECC's core coding standards, security checklist, testing requirements, and git workflow. -- **`.github/prompts/*.prompt.md`** — reusable prompt files users invoke on demand. Each prompt walks Copilot through a specific ECC workflow such as planning, TDD, security review, build-fix, or refactor. - -The **`.vscode/settings.json`** adds per-task instruction overlays so Copilot receives the right context for code generation, test generation, and commit message drafting. - -### Feature Coverage - -| ECC Feature | Copilot equivalent | -|-------------|-------------------| -| Coding standards | Always-on via `copilot-instructions.md` | -| Security checklist | Always-on + `security-review` prompt | -| Testing / TDD | Always-on + `tdd` prompt | -| Implementation planning | `plan` prompt | -| Code review | External PR review via CodeRabbit + Greptile | -| Build error resolution | `build-fix` prompt | -| Refactoring | `refactor` prompt | -| Commit message format | Per-task instruction in `settings.json` | -| Hooks / automation | Not supported (Copilot has no hook system) | -| Agents / delegation | Not supported (Copilot has no subagent API) | - -### Limitations - -GitHub Copilot does not have a hook system or a subagent API, so ECC's hook automations (auto-format, TypeScript check, session persistence, dev-server guard) and agent delegation are unavailable. The instruction and prompt layer still brings the full ECC coding philosophy — standards, security, TDD, and workflow — into every Copilot Chat session. - ---- - -## Cross-Tool Feature Parity - -ECC is the **first plugin to maximize every major AI coding tool**. Here's how each harness compares: - -| Feature | Claude Code | Cursor IDE | Codex CLI | OpenCode | GitHub Copilot | -|---------|-----------------------|------------|-----------|----------|----------------| -| **Agents** | 67 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 | N/A | -| **Commands** | 94 | Shared | Instruction-based | 35 | 5 prompts | -| **Skills** | 281 | Shared | 10 (native format) | 37 | Via instructions | -| **Hook Events** | 8 types | 15 types | None yet | 11 types | None | -| **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks | N/A | -| **Rules** | 34 (common + lang) | 34 (YAML frontmatter) | Instruction-based | 13 instructions | 1 always-on file | -| **Custom Tools** | Via hooks | Via hooks | N/A | 6 native tools | N/A | -| **MCP Servers** | 14 | Shared (mcp.json) | 7 (auto-merged via TOML parser) | Full | N/A | -| **Config Format** | settings.json | hooks.json + rules/ | config.toml | opencode.json | copilot-instructions.md + settings.json | -| **Context File** | CLAUDE.md + AGENTS.md | AGENTS.md | AGENTS.md | AGENTS.md | copilot-instructions.md | -| **Secret Detection** | Hook-based | beforeSubmitPrompt hook | Sandbox-based | Hook-based | Instruction-based | -| **Auto-Format** | PostToolUse hook | afterFileEdit hook | N/A | file.edited hook | N/A | +Platform implementation notes + +| Harness | ECC distribution | Main instruction surface | Automation | +|---|---|---|---| +| Claude Code | Plugin or selective installer | `CLAUDE.md`, rules, skills, agents | Native plugin hooks | +| Codex | Sync flow, repo config, experimental ECC marketplace | `AGENTS.md`, skills, `.codex/config.toml` | Git hooks and Codex-native configuration | +| Cursor | Project adapter | `.cursor/rules/`, scoped agents | Cursor hook adapter | +| OpenCode | Built plugin plus selective installer | `opencode.json`, instructions, commands | OpenCode plugin events | +| GitHub Copilot | Checked-in instruction layer | `copilot-instructions.md`, prompt files | No ECC hook runtime | + +| Feature | Claude Code | Cursor IDE | Codex CLI | OpenCode | GitHub Copilot | +| --- | --- | --- | --- | --- | --- | +| **Agents** | 67 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 | N/A | +| **Commands** | 94 | Shared | Instruction-based | 35 | 5 prompts | +| **Skills** | 281 | Shared | 10 (native format) | 37 | Via instructions | | **Version** | Plugin | Plugin | Reference config | 2.1.0 | Instruction layer | -**Key architectural decisions:** -- **AGENTS.md** at root is the universal cross-tool file (read by Claude Code, Cursor, Codex, and OpenCode — GitHub Copilot uses `.github/copilot-instructions.md` instead) -- **DRY adapter pattern** lets Cursor reuse Claude Code's hook scripts without duplication -- **Skills format** (SKILL.md with YAML frontmatter) works across Claude Code, Codex, and OpenCode -- Codex's lack of hooks is compensated by `AGENTS.md`, optional `model_instructions_file` overrides, and sandbox permissions +
---- +
+What changed in v2.0.0 -## Background +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. -I've been using Claude Code since the experimental rollout. Won the Anthropic x Forum Ventures hackathon in Sep 2025 with [@DRodriguezFX](https://x.com/DRodriguezFX) — built [zenith.chat](https://zenith.chat) entirely using Claude Code. - -These configs are battle-tested across multiple production applications. - ---- - -## Token Optimization - -Claude Code usage can be expensive if you don't manage token consumption. These settings significantly reduce costs without sacrificing quality. - -### Recommended Settings - -Add to `~/.claude/settings.json`: - -```json -{ - "model": "sonnet", - "env": { - "MAX_THINKING_TOKENS": "10000", - "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50" - } -} -``` - -| Setting | Default | Recommended | Impact | -|---------|---------|-------------|--------| -| `model` | opus | **sonnet** | ~60% cost reduction; handles 80%+ of coding tasks | -| `MAX_THINKING_TOKENS` | 31,999 | **10,000** | ~70% reduction in hidden thinking cost per request | -| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 95 | **50** | Compacts earlier — better quality in long sessions | -| `ECC_CONTEXT_MONITOR_COST_WARNINGS` | on | **off for subscription users** | Suppresses agent-facing API-rate estimate warnings while keeping context/scope/loop warnings | - -Switch to Opus only when you need deep architectural reasoning: -``` -/model opus -``` - -### Daily Workflow Commands - -| Command | When to Use | -|---------|-------------| -| `/model sonnet` | Default for most tasks | -| `/model opus` | Complex architecture, debugging, deep reasoning | -| `/clear` | Between unrelated tasks (free, instant reset) | -| `/compact` | At logical task breakpoints (research done, milestone complete) | -| `/cost` | Monitor token spending during session | - -If you use a Claude 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. - -### Strategic Compaction - -The `strategic-compact` skill (included in this plugin) suggests `/compact` at logical breakpoints instead of relying on auto-compaction at 95% context. See `skills/strategic-compact/SKILL.md` for the full decision guide. - -**When to compact:** -- After research/exploration, before implementation -- After completing a milestone, before starting the next -- After debugging, before continuing feature work -- After a failed approach, before trying a new one - -**When NOT to compact:** -- Mid-implementation (you'll lose variable names, file paths, partial state) - -### Context Window Management - -**Critical:** Don't enable all MCPs at once. Each MCP tool description consumes tokens from your 200k window, potentially reducing it to ~70k. - -- Keep under 10 MCPs enabled per project -- Keep under 80 tools active -- Use `/mcp` to disable unused Claude Code MCP servers; those runtime choices persist in `~/.claude.json` -- Use `ECC_DISABLED_MCPS` only to filter ECC-generated MCP configs during install/sync flows - -### 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. - ---- - -## WARNING: Important Notes - -### Token Optimization - -Hitting daily limits? See the **[Token Optimization Guide](docs/token-optimization.md)** for recommended settings and workflow tips. - -Quick wins: - -```json -// ~/.claude/settings.json -{ - "model": "sonnet", - "env": { - "MAX_THINKING_TOKENS": "10000", - "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50", - "CLAUDE_CODE_SUBAGENT_MODEL": "haiku" - } -} -``` - -Use `/clear` between unrelated tasks, `/compact` at logical breakpoints, and `/cost` to monitor spending. - -### Customization - -These configs work for my workflow. You should: -1. Start with what resonates -2. Modify for your stack -3. Remove what you don't use -4. Add your own patterns - ---- +- [v2.0.0 release notes](docs/releases/2.0.0/release-notes.md) +- [ECC 2.0 reference architecture](docs/ECC-2.0-REFERENCE-ARCHITECTURE.md) +- [Hermes setup guide](docs/HERMES-SETUP.md) +- [Migration guide from 1.x](docs/MIGRATION-1X-TO-2.0.md) +
## Security -ECC takes supply-chain and agent safety seriously. +Install ECC only from official sources: -- **Official sources only.** Install ECC only from the verified channels listed in the banner at the top of this README — the [GitHub repo](https://github.com/affaan-m/ECC), the `ecc-universal` / `ecc-agentshield` npm packages, the [GitHub App](https://github.com/apps/ecc-tools), the plugin slug `ecc@ecc`, and [ecc.tools](https://ecc.tools). Third-party re-uploads and mirrors are unreviewed and may ship malware. -- **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. -- **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](#agentshield--security-auditor) audits your own agent, hook, MCP, permission, and secret surfaces (`/security-scan`). -- **Deep dive.** See the [Security Guide](./the-security-guide.md). +- GitHub repository: +- Claude Code plugin: `ecc@ecc` +- npm packages: [`ecc-universal`](https://www.npmjs.com/package/ecc-universal) and [`ecc-agentshield`](https://www.npmjs.com/package/ecc-agentshield) +- GitHub App: +- Website: ---- +Scan a project with AgentShield: -## Sponsors +```bash +npx -y ecc-agentshield scan --path . +``` -Business sponsors: [CodeRabbit](https://www.coderabbit.ai) · [Greptile](https://www.greptile.com/go/ecc) · [Atlas Cloud](https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=ECC) · [Moonshot AI (Kimi)](https://www.moonshot.ai) · [Itô Markets](https://itomarkets.com). Logos are at the top of this README; the full roster and tiers are in [SPONSORS.md](SPONSORS.md). [Become a sponsor](https://github.com/sponsors/affaan-m). +
+Hooks, MCP servers, and context controls ---- +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. -## Links +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. -- **Shorthand Guide (Start Here):** [The Shorthand Guide to ECC](https://x.com/affaan/status/2012378465664745795) -- **Longform Guide (Advanced):** [The Longform Guide to ECC](https://x.com/affaan/status/2014040193557471352) -- **Security Guide:** [Security Guide](./the-security-guide.md) | [Thread](https://x.com/affaan/status/2033263813387223421) -- **Follow:** [@affaan](https://x.com/affaan) +Use `/mcp` for Claude Code runtime disables; Claude Code persists those choices in `~/.claude.json`. ---- +`ECC_DISABLED_MCPS` is an ECC install/sync filter, not a live Claude Code toggle. + +If context is getting heavy, run `/context-budget`, remove rules you do not need, and disable unused MCP servers. See the [token optimization guide](docs/token-optimization.md). +
+ +Security references: + +- [Security policy](SECURITY.md) +- [Security guide](./the-security-guide.md) +- [MCP connector policy](docs/MCP-CONNECTOR-POLICY.md) +- [Supply-chain incident response](docs/security/supply-chain-incident-response.md) + +## Troubleshooting + +
+ECC appears twice or hooks fire twice + +The usual cause is installing the Claude plugin and then running `install.sh --profile full` or `npx ecc-install --profile full` on top of it. + +1. Remove the Claude Code plugin install. +2. Run `node scripts/ecc.js uninstall --dry-run` from the ECC checkout. +3. Remove extra rule folders you manually copied and no longer want. +4. Reinstall once, using one path. + +For hook-specific checks, see the [hooks README](hooks/README.md). +
+ +
+Codex marketplace installs but skills do not load + +Run the cache check from an ECC checkout: + +```bash +node scripts/codex/check-plugin-cache.js +``` + +If it reports unresolved parent references, use `bash scripts/sync-ecc-to-codex.sh`. Registration in `codex plugin list` confirms the marketplace entry, not that every referenced file reached the plugin cache. +
+ +
+My platform is not listed + +Use the [manual adaptation guide](docs/MANUAL-ADAPTATION-GUIDE.md), or open a [GitHub discussion](https://github.com/affaan-m/ECC/discussions) with the harness name and the file, skill, command, and hook formats it supports. +
+ +## Community and Project + +
+Sponsors and ECC Pro + +ECC stays free because sponsors and Pro users fund the work. + +ECC Pro adds private-repo analysis, PR-triggered audits, AgentShield-backed scanning, automatic push and PR checks, pooled team usage, and priority support through the hosted GitHub App. + + + + + + + + +
ECC Pro
Hosted GitHub App for private repos		Sponsor ECC
Fund the OSS work		Community
Q&A, ideas, and Show and Tell		GitHub App
PR audits and hosted workflows
+ +

+ CodeRabbit    + Greptile    + Atlas Cloud    + Moonshot AI - Kimi    + Itô Markets +

+ +**Community sponsors:** [Mike Morgan](https://github.com/mikejmorgan-ai) | [@jasonwu513](https://github.com/jasonwu513) | [@1anter](https://github.com/1anter) | [@massimotodaro](https://github.com/massimotodaro) | [@meadmccabe](https://github.com/meadmccabe) + +[Become a sponsor](https://github.com/sponsors/affaan-m) | [Sponsor tiers](SPONSORS.md) | [Sponsorship program](SPONSORING.md) +
+ +
+Contributing + +Contributions are welcome across skills, agents, rules, hooks, docs, tests, adapters, and security improvements. + +- [Contributing guide](CONTRIBUTING.md) +- [Skill development guide](docs/SKILL-DEVELOPMENT-GUIDE.md) +- [Skill placement policy](docs/SKILL-PLACEMENT-POLICY.md) +- [Command quick reference](COMMANDS-QUICK-REF.md) +
## License -MIT - Use freely, modify as needed, contribute back if you can. - ---- - -**Star this repo if it helps. Read both guides. Build something great.** +MIT. Use it freely, adapt it to your workflow, and contribute back when you can.