ECC - the agent harness operating system

> [!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. ## Install with Claude Code Run the canonical guided setup from your terminal: ```bash npx ecc-universal setup ``` If npm reports a version or cache error, confirm the registry version before retrying: ```bash npm view ecc-universal version ``` This path requires Node.js 18 or newer, Git, and Claude Code 2.1 or newer on `PATH`. It safely installs, updates, or moves one `ecc@ecc` plugin scope and records the hook profile you choose. Alternatively, run Claude Code's native plugin commands inside Claude Code: ```text /plugin marketplace add https://github.com/affaan-m/ECC /plugin install ecc@ecc ``` The native path installs ECC's skills, agents, commands, and plugin-managed hooks. If you choose it, stop there. Do not also run a full manual install into Claude Code. > Both paths install the same `ecc@ecc` plugin. Choose one and do not stack > another manual Claude install on top.

ECC Pro + GitHub App
_{Install free · Private repos from $19/seat/mo}

Sponsor ECC
_{Fund the open-source project}

Community
_{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.}

_{Partners & sponsors}

_{Community sponsors: Mike Morgan · @jasonwu513 · @1anter · @massimotodaro · @meadmccabe} _{Become a Sponsor · Sponsor Tiers · Sponsorship Program}

Jump to install ↓

# ECC 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. ```text plan -> test -> implement -> review -> verify -> remember -> improve ``` Instead of rebuilding that process in every prompt, you install it once and make it part of how your agent works. > Optimize the context window. Persist everything else. ECC is MIT-licensed open source. It works best with Claude Code today, has a supported Codex sync path, and provides capability-limited adapters for Cursor, OpenCode, Gemini, Zed, GitHub Copilot, Antigravity, Qwen, and other harnesses. See the [support status matrix](#platform-support) before assuming feature parity. Access to 68 agents, 286 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 | 68 agents | Planning, review, build repair, security, architecture, and domain work | | Skills | 286 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 |

## Install ECC > [!IMPORTANT] > ECC 2.2 includes guided package setup for Claude Code, Codex, and Kimi Code. > The universal package requires Node.js 18 or newer. Claude plugin setup also > requires Git and Claude Code 2.1 or newer on `PATH`. ### Recommended: universal guided setup Run the package command from your terminal. For Claude Code setup, updates, scope changes, and hook-profile changes: ```bash npx ecc-universal setup ``` To configure Claude Code, Codex, or Kimi Code in one reviewed flow: ```bash npx ecc-universal install --guided ``` ### 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: - **Recommended default:** run the guided Claude plugin setup above - **Also supported for Claude Code:** use the [native plugin commands above](#install-with-claude-code) - **Available in release 2.2:** guided package setup for Claude Code, Codex, and Kimi Code - **Works:** Claude Code plugin + Codex native plugin - **Works:** Claude Code plugin + the legacy Codex sync flow - **Avoid:** Claude Code plugin + full Claude manual install - **Avoid:** Codex sync + Codex marketplace plugin **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. If you already layered multiple installs and things look duplicated, skip straight to [Reset / Uninstall ECC](#reset--uninstall-ecc). **Install trouble?** Open the short [install or runtime problem form](https://github.com/affaan-m/ECC/issues/new?template=install-problem.yml), or run `ecc feedback`. ECC never uploads diagnostics automatically. ### Claude Code details Claude Code owns these built-in commands, including their errors when a marketplace, plugin, or conflicting scope already exists. ECC cannot intercept that parser. If either native command reports an existing install or scope conflict, use the 2.2 guided setup or resolve the conflicting Claude plugin scope before retrying; do not layer a manual install on top. After ECC is installed, `/ecc:configure-ecc` is the namespaced in-Claude reconfiguration skill. It delegates to the same safe setup flow, but it is available only after the plugin is installed and cannot replace Claude Code's built-in `/plugin` command during a first install. 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.

Prefer settings.json? Add the marketplace declaratively

Add directly to your `~/.claude/settings.json`: ```json { "extraKnownMarketplaces": { "ecc": { "source": { "source": "github", "repo": "affaan-m/ECC" } } }, "enabledPlugins": { "ecc@ecc": true } } ``` This gives you the same result as the two `/plugin` commands above.

Naming + migration note (ecc@ecc, affaan-m/ECC, ecc-universal)

ECC has three public identifiers, and they are not interchangeable: - GitHub source repo: `affaan-m/ECC` - Claude marketplace/plugin identifier: `ecc@ecc` - npm package: `ecc-universal` This is intentional. Anthropic marketplace/plugin installs are keyed by a canonical plugin identifier, so ECC uses `ecc@ecc` to keep tool names and slash-command namespaces short enough for strict Desktop/API validators. Older posts may still show the former long marketplace identifier; treat that as a legacy alias only. Separately, the npm package stayed on `ecc-universal`, so npm installs and marketplace installs intentionally use different names. npm releases are cut per version tag, not per commit, so `ecc-universal` tracks releases (2.1, 2.2, ...) rather than every push to `main`. Install from git if you want the bleeding edge. If your local Claude setup was wiped or reset, that does not mean you need to repurchase anything. Start with `node scripts/ecc.js list-installed`, then run `node scripts/ecc.js doctor` and `node scripts/ecc.js repair` before reinstalling. That usually restores ECC-managed files without rebuilding your setup.

### Codex App and CLI Current Codex releases can install ECC as a native repo-marketplace plugin. The marketplace entry uses the repository root so Codex's cache receives the manifest together with all referenced skills, MCP configuration, hook runtime, scripts, and assets: ```bash codex plugin marketplace add affaan-m/ECC codex plugin add ecc@ecc codex plugin list --json node scripts/codex/check-plugin-cache.js ``` Both add commands are idempotent. To refresh later, run `codex plugin marketplace upgrade ecc` followed by `codex plugin add ecc@ecc`. Codex stores one enabled plugin state in the active `CODEX_HOME`; it does not offer Claude's `user`, `project`, and `local` scopes. Its native hooks require an explicit trust decision and do not use Claude's four ECC hook profiles. Inside Codex, invoke `$configure-ecc` for the guided provider-aware flow. The older `scripts/sync-ecc-to-codex.sh` path is a deprecated compatibility option for users who intentionally need copied and merged configuration in `~/.codex`; it is not required for the native plugin. New sync runs write an ownership manifest so cleanup can preserve modified user files. Run Codex once first so `~/.codex/config.toml` exists, then: ```bash git clone https://github.com/affaan-m/ECC.git cd ECC npm install bash scripts/sync-ecc-to-codex.sh ``` To inspect or remove that legacy layer without touching Codex conversations or native plugin caches: ```bash node scripts/ecc.js uninstall --legacy-codex-sync --dry-run node scripts/ecc.js uninstall --legacy-codex-sync ``` Pre-manifest installations are handled conservatively: ECC removes its marked `AGENTS.md` block but preserves copied files it cannot prove it owns and reports them for review. You can also open the ECC repository directly in Codex for a project-local setup. Codex reads the root `AGENTS.md` and the trusted project configuration in `.codex/` without a global sync. Do not add the native marketplace plugin on top of the sync flow. For repo navigation, surface ownership, and PR diff packet guidance, read the [Codex ECC Navigation Map](docs/CODEX-NAVIGATION-GUIDE.md). See the [.codex plugin notes](.codex-plugin/README.md) for native lifecycle details. ### Other agents and editors

Cursor, OpenCode, Gemini, Zed, Antigravity, Qwen, Hermes, OpenClaw, Kimi, CodeBuddy, JoyCode, Copilot

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-code/` 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. Deep per-harness notes (feature parity, hook adapters, limitations) live in [Platform Support](#platform-support) below.

## Self-Hosted Models and Custom Endpoints 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. For Claude Code, ECC does not hardcode Anthropic-hosted transport settings. Minimal gateway 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. 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). 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. ### Self-host Kimi with ECC + Itô compute 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. This adapter is verified against Kimi Code 0.31.x (`@moonshot-ai/kimi-code`):

1. Get GPU capacity
_{Use Itô or any GPU provider.}

2. Serve Kimi
_{Expose the chosen checkpoint through a compatible endpoint.}

3. Run Kimi Code with ECC
_{Install project instructions and skills, then start Kimi Code.}

Configure the endpoint with Kimi Code's official provider guide, then install ECC: ```bash bash ./install.sh --target kimi --profile minimal node scripts/ecc.js doctor --target kimi kimi ``` Kimi Code discovers the installed `.kimi-code/AGENTS.md` instructions and `.kimi-code/skills/` workflows natively; project-level `.agents/skills/` is also an official discovery location. ECC safely merges project MCP entries into `.kimi-code/mcp.json` and does not change the user-level `~/.kimi-code/config.toml`. Kimi Code supports native hooks, but ECC's current managed-project adapter does not configure them, so this installer does not offer Kimi hook profiles. The installer dry-run and regression suite verify that every managed Kimi write stays inside the project-local `.kimi-code/` root. ### Itô compute CLI bridge `ecc ito` delegates to the separately installed canonical Itô client; ECC does not maintain a second API client. `ecc ito login [--no-browser]` performs device authorization, opens the Itô verification page by default, and persists a device token in macOS Keychain; `--no-browser` suppresses the page handoff. ECC itself does no browser automation. `ecc ito auth` is validation-only and rejects `--no-browser`. The available operations are `ecc ito login`, `ecc ito auth`, `ecc ito find`, `ecc ito status`, and the separately gated `ecc ito evals`. The matching MCP tools remain `ito_auth`, `ito_find`, and `ito_status`; `ito_auth` validates existing credentials and node qualification is CLI-only. The `ito-compute-cli` package is currently unpublished. Build it locally from the Itô runtime repo (private while the desk hardens; design partners get access) under `cli/ito-compute-cli`, run `npm ci` and `npm run check`, then set `ECC_ITO_CLI_EXECUTABLE` to that build's absolute `dist/bin/ito.js` path. Login never inherits `ITO_API_KEY`; auth, find, and status forward `ITO_API_KEY` directly when configured, and `ITO_AUTH_MODE=legacy` is not required. `ecc ito logout` revokes the current device credential and retains its local copy if remote revocation cannot be confirmed. Device tokens use macOS Keychain by default; explicit file fallback must retain owner-only directory/file permissions. ECC does not discover this credential-bearing client through `PATH`. See the [`ito-compute` skill](skills/ito-compute/SKILL.md) for the full RFQ authority and MCP setup contract. `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. ## 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 npx ecc-universal install --profile minimal --target claude ``` From a source checkout, the equivalent command is: ```bash ./install.sh --profile minimal --target claude ``` Windows: ```powershell .\install.ps1 --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. For the normal core profile with hooks disabled: ```bash ./install.sh --profile core --without baseline:hooks --target claude ./install.sh --profile core --no-hooks --target claude ``` Add the hook runtime later only if you want it: ```bash ./install.sh --target claude --modules hooks-runtime --enable-hooks ``` Any install whose profile or modules would materialize the hook runtime requires an explicit decision. Without `--enable-hooks` or `--no-hooks`, the installer prints what the hooks can do and stops before writing anything. The guided installer (`ecc install --guided`) asks for this choice interactively.

Choose only the components you need

### Find the right components first Ask the packaged advisor which components match your work: ```bash node scripts/ecc.js consult "security reviews" --target claude ``` It returns matching components, related profiles, and preview/install commands. Use the preview command before installing if you want to inspect the exact file plan. You can also install explicit skills or capabilities: ```bash ./install.sh --target claude --skills tdd-workflow,security-review node scripts/ecc.js install --profile minimal --target claude --with capability:machine-learning ``` Manual component-by-component copying also works. Each component is fully independent: ```bash # Just agents cp agents/*.md ~/.claude/agents/ # Rules directories (common + language-specific) mkdir -p ~/.claude/rules/ecc cp -r rules/common ~/.claude/rules/ecc/ cp -r rules/typescript ~/.claude/rules/ecc/ # pick your stack # Core/general skills only (Claude Code loads skills from direct children # of ~/.claude/skills; do not nest manual installs under ~/.claude/skills/ecc/) mkdir -p ~/.claude/skills cp -r .agents/skills/* ~/.claude/skills/ cp -r skills/search-first ~/.claude/skills/ # Optional: maintained slash-command compatibility during migration mkdir -p ~/.claude/commands cp commands/*.md ~/.claude/commands/ ``` Retired shims live in `legacy-command-shims/`. Copy individual files from there only if you still need old names such as `/tdd`.

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. 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 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/`. #### Install hooks Do not copy the raw repo `hooks/hooks.json` into `~/.claude/settings.json` or `~/.claude/hooks/hooks.json`. That file is plugin/repo-oriented; use the installer so hook command paths are rewritten correctly: ```bash bash ./install.sh --target claude --modules hooks-runtime --enable-hooks ``` 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. On Windows, Claude's config root is `%USERPROFILE%\\.claude`; install the hook runtime with: ```powershell pwsh -File .\install.ps1 --target claude --modules hooks-runtime --enable-hooks ``` #### Configure MCPs Claude plugin installs intentionally do not auto-enable ECC's bundled MCP server definitions. This avoids overlong plugin MCP tool names on strict third-party gateways while keeping manual MCP setup available. Use Claude Code's `/mcp` command or CLI-managed MCP setup for live Claude Code server changes; Claude Code persists those choices in `~/.claude.json`. For repo-local MCP access, copy desired MCP server definitions from `mcp-configs/mcp-servers.json` into a project-scoped `.mcp.json`. ECC ships exactly one default connector (`chrome-devtools`); everything else is a skill wrapping a CLI/REST API or an opt-in catalog entry. The rule and the June 2026 audit that retired the previous six defaults live in [docs/MCP-CONNECTOR-POLICY.md](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.

Multi-model commands require additional setup

`multi-*` commands are **not** covered by the base plugin/rules install. To use `/multi-plan`, `/multi-execute`, `/multi-backend`, `/multi-frontend`, and `/multi-workflow`, you must also install the `ccg-workflow` runtime. 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.

Reset, repair, or uninstall

### Reset / Uninstall ECC If you installed from the universal package, run these commands from the same project directory used for installation: ```bash npx ecc-universal list-installed npx ecc-universal doctor npx ecc-universal repair npx ecc-universal uninstall --dry-run npx ecc-universal uninstall ``` From a source checkout, inspect the managed state before reinstalling: ```bash node scripts/ecc.js list-installed node scripts/ecc.js doctor node scripts/ecc.js repair node scripts/ecc.js uninstall --dry-run ``` For a direct source-checkout uninstall: ```bash node scripts/uninstall.js --dry-run node scripts/uninstall.js ``` If you are leaving, the uninstall command prints an optional [20-second feedback form](https://github.com/affaan-m/ECC/issues/new?template=quick-feedback.yml). It is a public GitHub issue, never blocks uninstall, and ECC does not upload diagnostics. You can also run `ecc feedback` at any time to see the problem, feedback, and feature routes. Plugin users should remove the plugin from Claude Code, then delete only the rule folders they manually copied and no longer want. ECC only removes files recorded in its install-state. It does not claim unrelated files in your harness directories. If you stacked methods, clean up in this order: 1. Remove the Claude Code plugin install. 2. Run the ECC uninstall command from the project directory that contains the managed install-state. 3. Delete any extra rule folders you copied manually and no longer want. 4. Reinstall once, using a single path.

## Universal guided setup details > [!IMPORTANT] > These package-runner commands require `ecc-universal` 2.2.0 or newer and > Node.js 18 or newer. Claude plugin setup also requires Git and Claude Code > 2.1 or newer on `PATH`. For Claude Code plugin setup, updates, scope changes, and hook-profile changes: ```bash npx ecc-universal setup ``` ECC 2.2 supports the same guided setup through modern package runners: | Package runner | Guided setup command | |---|---| | npm / npx | `npx ecc-universal setup` | | pnpm | `pnpm dlx ecc-universal setup` | | Yarn 2+ | `yarn dlx ecc-universal setup` | | Bun | `bunx ecc-universal setup` | Yarn Classic 1 does not provide `yarn dlx`; use `npx`, install the package globally, or upgrade Yarn for a temporary one-shot run. The wizard inventories the official marketplace and every native Claude install scope before making changes, then installs, updates, or safely moves `ecc@ecc` to the scope you choose. Rerun the same command whenever you want to update ECC, change scope, or change its hook profile. This setup wizard currently configures the Claude Code plugin; use the multi-harness wizard below for Codex or Kimi Code. To configure more than one coding agent in one reviewed flow, use the multi-harness wizard: ```bash npx ecc-universal install --guided ``` It lets you select any combination of Claude Code, Codex, and Kimi Code, shows each install channel and destination, preflights every selection before the first write, and asks for one final confirmation. | Harness | Guided install behavior | |---|---| | Claude Code | Native `ecc@ecc` plugin with one `user`, `project`, or `local` scope and an ECC hook profile | | Codex | Native Codex marketplace/plugin lifecycle; hook review and trust remain Codex-owned | | Kimi Code | Managed project files under `./.kimi-code`; ECC hooks, model/provider settings, and authentication are not configured | For automation, make every provider-specific choice explicit: ```bash npx ecc-universal install --guided \ --harness claude --harness codex --harness kimi \ --claude-scope local --claude-hooks standard \ --profile core --yes ``` Verify the native guided Codex path and managed Kimi path without writing first: ```bash npx ecc-universal install --guided --harness codex --dry-run npx ecc-universal install --profile core --target kimi --dry-run ``` Additional package-name commands are also available through the 2.2 alias: ```bash npx ecc-universal consult "security reviews" --target claude npx ecc-universal install --profile minimal --target claude --with capability:machine-learning npx ecc-universal doctor --target kimi ``` Do not use `npx ecc-install --profile minimal --target claude`: `ecc-install` is a binary name inside `ecc-universal`, not a separately published npm package. ECC also ships advanced managed adapters for `cursor`, `antigravity`, `gemini`, `opencode`, `codebuddy`, `joycode`, `qwen`, `zed`, `hermes`, and `openclaw`. Those targets still use their documented `ecc install --target ...` paths until each adapter has passed the guided collision, update, repair, and uninstall lifecycle matrix. Neither wizard silently installs into every detected harness. ## Start Using ECC Start with the workflow you need, not the full catalog. | 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" ``` Manual installs may expose the shorter compatibility form: ```text /plan "Add authentication" ``` Skills are the primary workflow surface. Commands remain convenient entry points and compatibility shims. Check what is installed with: ```bash /plugin list ecc@ecc ```

Which agent should I use?

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 ```

## 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. 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 above in [Self-Hosted Models and Custom Endpoints](#self-hosted-models-and-custom-endpoints)) - **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 ### 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. Full detail in [Share context between harnesses](#share-context-between-harnesses) below.

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 |

Release history in detail

### v2.0.0: The Agent Harness Operating System (Jun 2026) Stable graduation of the 2.0 line: 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. - **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 a single harness. - **Itô prediction-market skill pack**: the consolidated `ito-baskets` skill (read-only basket index, comparison, market briefs, and non-executable planning worksheets — replacing the former `ito-market-intelligence`, `ito-basket-compare`, `ito-trade-planner`, and `ito-data-atlas-agent` skills), plus `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 in-tree**: the Rust control-plane prototype in `ecc2/` builds locally and exposes `dashboard`, `start`, `sessions`, `status`, `stop`, `resume`, and `daemon` commands. - **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. - **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 and 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`, `documentation-lookup`, `bun-runtime`, `nextjs-turbopack`, 8 operational domain skills, and `mcp-server-patterns`. - **Session and state infrastructure**: SQLite state store with query CLI, session adapters for structured recording, skill evolution foundation for self-improving skills. - **Orchestration overhaul**: Deterministic harness audit scoring, hardened orchestration status and launcher compatibility, 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 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 and 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, and 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` 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, and PM2 (Feb 2026) - **Interactive installation wizard**: New `configure-ecc` skill provides guided setup with merge/overwrite detection - **PM2 and 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 and 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).

## Why Choose ECC? | 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 | ### TDD: Test-Driven Development ```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. ### Skills keep the context focused 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)

Memory Vault in depth: scopes, handoffs, and trust boundaries

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

## Guides This repo is the raw code. The guides explain everything.

The Shorthand Guide
_{Setup, foundations, and day-one use. Read this first. (thread)}

> 内容过长，已截断。完整文档请查看仓库原文。