Image: GitHub

ECC: Agent Harness Performance Optimization System

The world of AI coding agents is undergoing a revolution. What started as simple chat-based coding assistants has evolved into AI agents that can write code, run tests, perform code reviews, and even orchestrate security scans — all automatically. But here's the problem: coordinated workflows are hard to build from scratch in every prompt.

Enter ECC (Agent Harness Performance Optimization System) — an open-source project with 240K+ stars on GitHub that serves as the "operating system" for AI coding agents. ECC provides skills, agents, memory, and security to AI agents so they can work like structured, professional engineers.

What Is ECC?

ECC isn't just a collection of prompts or config files. It's a complete coordinated system that gives AI agents engineering capabilities:

plan -> test -> implement -> review -> verify -> remember -> improve

Instead of building that process into every prompt, you install it once and it becomes part of how the agent works. ECC is free and open-source under the MIT license, with the main repository at github.com/affaan-m/ECC and homepage at ecc.tools.

What Does ECC Provide?

ECC isn't just "a lot of skills." It organizes the entire AI coding agent workflow into separate, coordinated components:

• 68 agents — specialist sub-agents for planning, review, build repair, security, architecture, and domain work
• 284 skills — reusable workflows loaded on demand (TDD, security review, deep research, etc.)
• 94 commands — slash commands as entry points (migrating to skills-first)
• Hooks & Memory — runtime automation, session summaries, continuous learning, instincts, and context controls
• Rules — project or language standards installed selectively
• AgentShield — 102 security rules that scan every session

Why Is It So Popular (240K+ Stars)?

ECC earned 240K+ stars for good reason. Key factors include:

1. Solved a real problem — Developers needed structured workflows for AI agents, not just empty prompts
2. Multi-harness support — Works with Claude Code, Codex, Cursor, OpenCode, and many more
3. Battle-tested — Built by Affaan Mustafa (winner of the Anthropic x Forum Ventures hackathon, September 2025) and already used in production
4. MIT license forever — Always free, always open-source
5. Active community — 36.4K+ forks, an active Discord community, and weekly releases
6. Enterprise-ready — GitHub App for private repos, Pro plan starting at $19/seat/month

Key Features of ECC

1. Skills — Workflows Loaded When Needed

Skills are reusable workflows loaded only when a task requires them. This keeps the context window focused:

Example skill usage:

/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

2. Instincts — Continuous Learning

Instincts are patterns learned from actual work sessions, complete with confidence scores. So when an agent faces a similar situation, it can "remember" approaches that have already proven effective.

ecc memory init --scope project
ecc memory search "authentication migration" --target-harness codex
ecc memory doctor

3. Memory — Unified Memory Vault

The Memory Vault provides a single Markdown format — local and inspectable — for durable context and handoffs between harnesses:

• Project/team memories → .ecc/memory/
• User memories → ~/.ecc/memory/

Memory is not executable policy; it's unreviewed context. You should verify important claims against authoritative sources and promote accepted knowledge to governed project documentation.

An optional ecc-memory-mcp stdio server can expose save/search/read/doctor surfaces without activating by default.

4. Security — AgentShield

AgentShield is a security auditor for agent configurations with 102 security rules that scan for:

• Prompt injection
• Hook configurations
• MCP configs
• Permissions
• Secrets
• Agent files

npx -y ecc-agentshield scan --path .

You can also run a scan directly from a slash command:

/security-scan

5. Research-First Development

ECC promotes a research-first approach to development. Before writing code, the agent must:

1. Plan — Create an editable plan before implementation
2. Research — Look up best practices and existing approaches
3. Test — Write failing tests first (RED phase)
4. Implement — Write code until tests pass (GREEN phase)
5. Review — Review from a fresh context
6. Verify — Confirm build, lint, types, and tests all pass

How ECC Works

Repository Structure

ECC/
├── agents/           # 68 specialized subagents for delegation
├── skills/           # 284 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

The root is the source of truth. Platform adapters package or map the same workflows instead of maintaining separate copies.

TDD Workflow — Full Example

Here's the TDD flow implemented by ECC:

/ecc:plan "Add usage-based billing alerts"
  -> confirm or edit the plan
  -> activate tdd-workflow
  -> capture RED evidence (failing tests) before implementation
  -> implement until GREEN (tests passing)
  -> review from fresh context (separate agent)
  -> fix findings with regression tests
  -> verify: build ✓, lint ✓, types ✓, tests ✓

The result isn't just code. It's a trail of evidence: plan, failing test, passing test, review findings, and final verification.

Plan Canvas — New in ECC 2.1

Plan Canvas is a browser-based, loopback-only canvas where you can:

1. Review a plan by clicking instead of re-typing
2. Attach numbered annotations
3. Chat from a side rail
4. Approve a plan or request changes
5. Mermaid diagrams render live

# Example usage
/ecc:plan "describe the feature"
# Review from the browser canvas, not the terminal

The canvas is harness-agnostic and model-agnostic: a plain CLI (ecc-plan-canvas) that speaks JSON, so any agent can use it.

AI Agent Compatibility

ECC supports various AI coding agents with different levels of compatibility:

Claude Code (Stable Primary)

Claude Code is ECC's primary target with the most comprehensive support:

# Install via native plugin
/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc

Or add rules manually:

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/  # swap in your stack

Available features: Native instructions, native skills, native agents, ECC plugin hooks, MCP configuration.

Codex (Supported Sync + Marketplace Experimental)

# Install via Codex marketplace
codex plugin marketplace add affaan-m/ECC
codex plugin add ecc@ecc
codex plugin list --json
node scripts/codex/check-plugin-cache.js

Or use the sync flow for a more reliable path:

git clone https://github.com/affaan-m/ECC.git
cd ECC
npm install
bash scripts/sync-ecc-to-codex.sh

Available features: Instructions via AGENTS.md, native synced skills set, Codex multi-agent roles, TOML merge through sync. Limitation: No ECC hook runtime.

Cursor (Beta Project Adapter)

# Install to .cursor/
ecc install --target cursor

Available features: Project rules, build-dependent project agents, Cursor hook adapter. Limitation: Agent discovery varies by Cursor build, hook sets are not identical.

OpenCode (Beta Built Plugin)

# Build plugin, then selective installer
ecc install --target opencode

Available features: Plugin instructions, built skills subset, plugin agents, plugin events. Limitation: ECC ships a subset catalog, reference config pins Anthropic models.

Other Platforms

Cross-Tool Capability Map

Installation

Method 1: Plugin (Recommended for Claude Code)

/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc

Method 2: npm Package

npm i -g ecc-universal

Method 3: Multi-Harness Wizard (Coming in 2.2)

npx ecc-universal install --guided

This wizard lets you select a combination of Claude Code, Codex, and Kimi Code in a single flow.

Method 4: GitHub App (For Private Repos)

# 1. Install the app on your repo or org
# 2. Comment /ecc-tools analyze
# 3. Review the generated pull request

Important: Pick One Path Only (Per Harness)

• Recommended today for Claude Code: Use native plugin commands
• Works: Claude Code plugin + Codex native plugin
• Works: Claude Code plugin + legacy Codex sync flow
• Avoid: Claude Code plugin + full Claude manual install
• Avoid: Codex sync + Codex marketplace plugin

Don't stack install methods. Installing ECC twice into the same harness can duplicate skills, commands, hooks, or configuration.

Verifying Installation

# Check installation status
ecc memory doctor
 
# Dry run for Codex
npx ecc-universal install --guided --harness codex --dry-run
 
# Dry run for Kimi
npx ecc-universal install --profile core --target kimi --dry-run

Use Cases

1. Building Features with TDD

/ecc:plan "Add usage-based billing alerts"
-> TDD workflow
-> RED: write failing tests
-> GREEN: implement until tests pass
-> Review from fresh context
-> Verify: build, lint, types, tests

2. Fixing Bugs

Reproduce a bug with a failing test, then use the TDD workflow to fix it. ECC ensures regression tests are written and all verification passes.

3. Code Review

/code-review

A fresh-context review from a separate agent to catch regressions and blind spots.

4. Build Repair

/build-fix

Automated build repair with an evidence trail.

5. Codebase Cleanup

/refactor-clean

Systematic codebase cleanup.

6. Context Budget Management

/context-budget

Monitor and manage context window pressure.

7. Session Management

/save-session or /learn-eval   # End a long session
/resume-session                  # Resume later

8. Security Audit

/security-scan

Or run AgentShield directly:

npx -y ecc-agentshield scan --path .

Comparison: ECC vs Other Frameworks

ECC vs Manual Prompt Engineering

ECC vs Other Custom Frameworks

ECC vs Simple Prompt Templates

ECC isn't an ordinary prompt template. The fundamental differences:

1. Structured workflow — ECC has a gated workflow (plan→test→implement→review→verify) enforced by hooks, not just instructions
2. Runtime enforcement — Hooks run outside the model context, so they can't be bypassed by the model
3. Continuous learning — Instincts and the memory vault allow agents to learn from previous sessions
4. Security scanning — AgentShield scans agent config as an attack surface, not just trusting everything by default

Token Optimization

Agent usage can get expensive if you don't manage token consumption. ECC provides several optimizations:

# Check context pressure
/context-budget
 
# Strategic compaction
# Context window management via hooks

Some best practices:

• Use selective/profile installs for only the components you need
• Use background processes for long-running tasks
• Take advantage of session save/resume for extended work
• Monitor token usage regularly

ECC 2.1 — Latest Features

Plan Canvas

Browser-based plan review with:

• Click-based annotation (no typing)
• Side rail chat
• Mermaid diagram live rendering
• Approve/Request changes workflow

Kimi Code Install Target

ECC can now install natively into Moonshot AI's Kimi Code CLI:

ecc install --target kimi

Self-Hosted GPU Computing

Verified path with Itô for self-hosted compute, including an opt-in ecc ito find RFQ bridge.

Hermes + OpenClaw Install Targets

New install targets for the Hermes and OpenClaw harnesses.

Tips for Getting Started

1. Start with your needs, not the full catalog — Install only the skills you need
2. Join the Discord community — discord.gg/36yGMHGFbR for Q&A and show-and-tell
3. Read the guides first — The Shorthand Guide for setup and day-one use
4. Use the GitHub App — For private repos on a team, the GitHub App is the fastest path
5. Don't skip security — Run AgentShield regularly to scan agent configs

Conclusion

ECC isn't just a collection of prompts or configs — it's a complete operating system for AI coding agents. With 240K+ stars, 68 agents, 284 skills, and support for 7+ harnesses, ECC delivers the structured workflow that transforms an AI agent from "can write code" into "can work like a professional engineer."

For developers exploring AI coding agents, ECC is a rock-solid starting point. Free, open-source, and battle-tested in production. Install it once, and let your agent work in a more structured way.

Links:

• GitHub: github.com/affaan-m/ECC
• Homepage: ecc.tools
• Discord: discord.gg/36yGMHGFbR
• npm: ecc-universal, ecc-agentshield
• GitHub App: github.com/apps/ecc-tools

Tags: ai-agents, anthropic, claude, claude-code, developer-tools, llm, mcp, productivity

License: MIT