ECC

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)

[](https://discord.gg/36yGMHGFbR) [](https://ecc.tools) [](https://github.com/apps/ecc-tools) [](#the-guides)

[](https://github.com/affaan-m/ECC/stargazers) [](https://github.com/affaan-m/ECC/network/members) [](https://github.com/affaan-m/ECC/graphs/contributors) [](https://www.npmjs.com/package/ecc-universal) [](https://www.npmjs.com/package/ecc-agentshield) [](https://github.com/marketplace/ecc-tools) [](LICENSE)

> [!WARNING] > Official sources only. Install ECC only from verified channels: the GitHub repository github.com/affaan-m/ECC, the npm packages ecc-universal and ecc-agentshield, the GitHub App, the plugin slug ecc@ecc, and the project website 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).

---

ECC Pro Private repos · GitHub App · $19/seat/mo

Sponsor Fund the OSS · From $5/mo

Community

Discussions · Q&A · Show & Tell

GitHub App Install · PR audits · Free tier

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.

Business sponsors

CodeRabbit

Greptile

Atlas Cloud

Community sponsors: Mike Morgan · @jasonwu513 · @1anter · @massimotodaro · @meadmccabe

Become a Sponsor · Sponsor Tiers · Sponsorship Program

---

The Guides

This repo is the raw code only. The guides explain everything.

The Shorthand Guide

Setup, foundations, philosophy. Read this first. (thread)

The Longform Guide

Token optimization, memory persistence, evals, parallelization. (thread)

The Security Guide

Attack vectors, sandboxing, sanitization, CVEs, AgentShield. (thread)

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

---

What's New

v2.0.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. 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 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, #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.

---

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:

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

.\install.ps1 --profile minimal --target claude
# or
npx ecc-install --profile minimal --target claude

This profile intentionally excludes hooks-runtime.

If you want the normal core profile but need hooks off, use:

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

Add hooks later only if you want runtime enforcement:

./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:

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:

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.

# Add marketplace
/plugin marketplace add https://github.com/affaan-m/ECC

# Install plugin
/plugin install ecc@ec

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [affaan-m](https://github.com/affaan-m)
- **Source:** [affaan-m/ECC](https://github.com/affaan-m/ECC)
- **License:** MIT
- **Homepage:** https://ecc.tools

Install and usage instructions live in the source repository linked above.