How to Optimize AI Agent Performance with ECC on Claude Code in 2025

What Is ECC and Why AI Agent Developers Need It

ECC (github.com/affaan-m/ECC) is a harness-native operator system for agentic coding workflows. Where most teams stitch together ad-hoc system prompts and hope for consistency, ECC gives you a structured layer—skills, instincts, memory rules, security scanning, and MCP configurations—that travels with your project across every supported AI harness. Maintainer affaan-m built it over 10+ months of daily production use, it won the Anthropic Hackathon, and it now sits at 182K+ stars with 170+ contributors.

The Problem: Raw AI Coding Agents Are Inconsistent and Insecure

If you've spent any time running Claude Code or Cursor in a real codebase, you've hit the wall: agents that forget project conventions after a few turns, hallucinate dependencies, leak environment variables into generated code, or simply refuse to follow review steps you specified three messages ago. The root cause is that these agents have no persistent behavioral contract with your project. Each session starts cold. Every workaround you add to a system prompt grows the context window and still doesn't survive a harness upgrade.

ECC as a Harness-Native Operator System

"Harness-native" means ECC's artifacts live inside your repository and are understood directly by the agent harness—not injected as a blob of text at the top of every conversation. ECC writes skills as TypeScript modules, hooks as YAML event descriptors, memory rules as JSON schemas, and MCP configurations as structured manifests. The harness loads these natively, so the operator contract survives session restarts, team member onboarding, and harness version upgrades. Contrast this with a system prompt template: paste it wrong once and your entire behavior layer silently disappears.

How ECC Won the Anthropic Hackathon and Became Production-Ready

The project originated as an internal toolset for building production AI products on top of Claude. When affaan-m open-sourced it after the Anthropic Hackathon win, the community immediately validated the architecture—28K+ forks and a GitHub App with 150+ installs followed quickly. Today ECC supports Claude Code, Codex, Cursor, OpenCode, Gemini, Zed, and GitHub Copilot. The v2.0.0-rc.1 release adds the cross-harness layer and the Hermes operator story documented in docs/HERMES-SETUP.md.

---

Core Concepts: The Five Pillars of ECC

ECC organizes everything an agent needs to behave consistently into five pillars. Understanding these upfront saves you from treating ECC as "just another config file."

Skills: Reusable Agent Capabilities Across Harnesses

A Skill is a self-contained TypeScript module that defines a named capability—think code-review, dependency-audit, or migration-planner. Each skill declares an input schema, a handler that drives the agent, and optional metadata that tells ECC which harnesses support it. Skills live in skills/ and are referenced by hooks, CI pipelines, or direct invocation. Unlike a system prompt paragraph, a skill is versioned, testable, and importable.

Instincts: Heuristic Rules That Shape Agent Behavior

Instincts live in rules/ and encode your team's non-negotiables: "never mutate the database schema without a migration file," "always run tests before proposing a PR." They're evaluated by ECC's rule engine at decision points in the agent loop, acting as guardrails without consuming extra conversational tokens. Instincts are expressed as structured rule objects, not prose—which means they're diffable, reviewable, and composable.

Memory Optimization: Persistent Context Without Token Bloat

ECC defines three memory scopes: session (cleared on agent restart), project (persists in .ecc/memory/project.json), and global (user-level knowledge anchors). Rules in memory/ control what gets promoted between scopes, what gets compressed, and what gets pruned. The result is agents that remember your architecture decisions across days without burning tokens re-reading the same boilerplate every turn.

Security Scanning with ecc-agentshield

ecc-agentshield is a separate npm package that scans agent-generated outputs for secrets, prompt injection signatures, and unsafe shell commands before they reach your codebase or CI pipeline. It ships with a default ruleset and accepts project-specific regex overrides via a config file. You can run it as a CLI gate, a pre-commit hook, or a GitHub Actions step.

Research-First Development: How ECC Enforces Best Practices

The fifth pillar is a workflow contract: ECC ships with hooks that force agents to retrieve relevant documentation and prior art before writing new code. This "research-first" pattern—enabled by MCP configurations that wire agents to context sources—dramatically reduces hallucinated APIs and duplicate implementations. The MCP configurations in mcp/ define which tools and servers the agent is allowed to call during research phases.

Pillar        | Artifact Type          | Harness Support
--------------+------------------------+-----------------------------------------
Skills        | TypeScript module      | All (Claude Code, Codex, Cursor, etc.)
Instincts     | JSON rule object       | All
Memory        | JSON config + store    | Claude Code, Cursor, OpenCode
Security      | npm package + YAML     | CI/CD, any harness via pre-commit
Research-First| MCP config manifest    | Claude Code, Gemini, OpenCode

---

Quick Start: Installing ECC for Claude Code

Prerequisites: Node.js, npm, and Claude Code CLI

Before installing, verify your environment:

| Requirement | Minimum Version | Check Command | |---|---|---| | Node.js | 18.x LTS | node --version | | npm | 9.x | npm --version | | Claude Code CLI | 1.x | claude --version | | OS | macOS 12+, Ubuntu 22+, Windows WSL2 | — |

Installing ecc-universal via npm

Install the global CLI first, then initialize ECC inside your project root:

# Install the ECC CLI globally
npm install -g ecc-universal

# Verify installation
ecc --version
# Expected output: ecc-universal/2.0.0-rc.1 linux-x64 node-v20.11.0

# Move into your project and initialize
cd my-project
ecc init

Initializing the ECC Operator Layer in Your Project

🚀 ECC v2.0.0-rc.1 — Initializing operator layer...

✔ Detected harness: Claude Code
✔ Created .ecc/
✔ Created skills/          ← reusable agent capabilities
✔ Created hooks/           ← event-driven skill triggers
✔ Created memory/          ← context scope configuration
✔ Created rules/           ← instinct/heuristic definitions
✔ Created mcp/             ← MCP server configurations
✔ Wrote .ecc/config.json
✔ Wrote CLAUDE.md          ← harness manifest (auto-loaded by Claude Code)

📖 Next: read docs/HERMES-SETUP.md or run `ecc guide hermes`

Verifying the Installation and Running the Hermes Setup Guide

After ecc init, run ecc guide hermes to launch the interactive Hermes setup wizard. It walks you through attaching your first skill, configuring memory scope, and running a smoke-test agent session. The guide references docs/HERMES-SETUP.md for every step and takes under five minutes on a fresh project.

---

Use Case 1 — Boosting Coding Agent Throughput with Skills and Hooks

What Are ECC Skills and How They Differ from System Prompts

A system prompt paragraph saying "always review code for security issues" costs tokens every single turn and degrades if the context window fills. An ECC skill is invoked only when its trigger fires, executes a focused agent sub-task, and returns a structured result. The agent sees a scoped context—not your entire conversation history.

Writing a Custom Skill for Automated Code Review

Here's a complete ECC skill that runs lint-and-review on staged files:

// skills/code-review.skill.ts
import { defineSkill } from 'ecc-universal';

export default defineSkill({
  name: 'code-review',
  version: '1.0.0',
  description: 'Lint staged files and produce a structured review report.',
  harnesses: ['claude-code', 'cursor', 'codex'],

  input: {
    type: 'object',
    properties: {
      files: {
        type: 'array',
        items: { type: 'string' },
        description: 'Relative paths of files to review',
      },
      severity: {
        type: 'string',
        enum: ['error', 'warning', 'info'],
        default: 'warning',
        description: 'Minimum severity level to report',
      },
    },
    required: ['files'],
  },

  async handler({ files, severity = 'warning' }, agent) {
    // 1. Research phase: fetch relevant lint rules from project docs
    const lintRules = await agent.mcp.fetch('project://lint-rules');

    // 2. Run agent review over each file
    const results = await Promise.all(
      files.map((file) =>
        agent.task({
          prompt: `Review ${file} against these rules: ${lintRules}. Report issues at or above ${severity} severity.`,
          context: { file: agent.fs.read(file) },
          outputSchema: {
            type: 'array',
            items: {
              type: 'object',
              properties: {
                line: { type: 'number' },
                severity: { type: 'string' },
                message: { type: 'string' },
              },
            },
          },
        })
      )
    );

    return { reviewed: files.length, issues: results.flat() };
  },
});

Wiring Hooks to Trigger Skills on File Save or PR Events

# hooks/pre-commit-review.hook.yaml
name: pre-commit-review
trigger:
  event: git.pre-commit
  filter:
    extensions: ['.ts', '.tsx', '.js', '.py']
skill: code-review
input:
  files: '{{ event.staged_files }}'
  severity: warning
on_failure:
  action: block_commit
  message: 'ECC code-review found blocking issues. Run `ecc skill run code-review --fix` to resolve.'

Drop this file in hooks/ and ECC registers it with Claude Code's hook system automatically on the next ecc sync. No manual harness configuration required.

---

Use Case 2 — Memory Optimization for Long-Running Agent Sessions

Why Context Window Bloat Kills Agent Performance

At around 60-70% context window utilization, Claude Code starts dropping earlier turns. When those dropped turns contain your architecture decisions or agreed conventions, the agent reverts to generic behavior—often undoing work from earlier in the session. You then spend tokens re-explaining context you already provided. This is the death spiral of long agentic workflows.

ECC Memory Layers: Session, Project, and Global Scope

ECC's three scopes break this cycle:

• Session scope: high-frequency, low-importance state (current task progress, temp variables). Pruned aggressively.
• Project scope: architecture decisions, agreed conventions, repo layout. Persisted across restarts in .ecc/memory/project.json.
• Global scope: user-level knowledge anchors (preferred libraries, style rules). Shared across all projects.

Configuring Memory Rules to Prune and Compress Agent Context

// memory/rules.json
{
  "version": "2",
  "scopes": {
    "session": {
      "max_tokens": 8000,
      "pruning": {
        "strategy": "lru",
        "compress_threshold": 0.75,
        "compress_ratio": 0.4,
        "preserve_tags": ["decision", "constraint", "error"]
      }
    },
    "project": {
      /* before optimization: ~12,000 tokens re-injected per session */
      /* after optimization:  ~2,800 tokens via anchored summaries   */
      "anchors": [
        {
          "id": "arch-decisions",
          "source": "docs/ARCHITECTURE.md",
          "summary_model": "claude-3-5-haiku",
          "max_anchor_tokens": 800,
          "refresh": "on_file_change"
        },
        {
          "id": "coding-conventions",
          "source": "docs/CONVENTIONS.md",
          "max_anchor_tokens": 400,
          "refresh": "weekly"
        }
      ],
      "dedup": {
        "enabled": true,
        "similarity_threshold": 0.92
      }
    },
    "global": {
      "anchors": [
        {
          "id": "user-preferences",
          "source": "~/.ecc/global-prefs.md",
          "max_anchor_tokens": 300
        }
      ]
    }
  }
}

| Metric | Without ECC Memory | With ECC Memory Rules | |---|---|---| | Tokens per session start | ~12,000 | ~2,800 | | Context window at 90 min | 94% full | 61% full | | Convention drift rate | ~40% of tasks | <5% of tasks | | Sessions before re-explanation | 1 | 10+ |

---

Use Case 3 — Security Hardening Agents with ecc-agentshield

Common Security Risks in Agentic Coding Workflows

When an agent writes code autonomously—especially in long sessions touching environment config, Dockerfiles, or CI scripts—three threat classes appear consistently: secret leakage (hardcoded API keys, tokens), prompt injection (malicious instructions embedded in retrieved files or issue comments), and unsafe shell commands (agent-generated scripts that pipe to sh or use eval). Standard linters don't catch prompt injection; standard SAST tools don't model agent output patterns.

Installing and Configuring ecc-agentshield

npm install -g ecc-agentshield

# Scan a directory of agent-generated output
ecc-agentshield scan ./src --config .ecc/agentshield.config.json

# Expected output on a clean scan:
# ✔ Scanned 47 files | 0 secrets | 0 injections | 0 unsafe commands
# Shield status: PASS

Scanning Agent Outputs for Secret Leakage and Prompt Injection

| Threat Type | Detection Method | Remediation | |---|---|---| | Hardcoded secrets | Entropy analysis + regex patterns | Replace with env var reference | | Prompt injection | Instruction-pattern regex + embedding similarity | Flag for human review | | Unsafe shell cmds | AST + pattern matching (eval, curl \| sh) | Block and suggest safe alternative | | Sensitive path traversal | Path pattern analysis | Sandbox file access |

Integrating agentshield into a CI/CD Pipeline

# .github/workflows/agentshield-scan.yml
name: ECC AgentShield Security Scan

on:
  pull_request:
    branches: [main, develop]

jobs:
  agentshield:
    name: Agent Output Security Scan
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - name: Checkout PR
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install ecc-agentshield
        run: npm install -g ecc-agentshield

      - name: Run AgentShield scan on changed files
        id: shield_scan
        run: |
          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
          echo "Scanning: $CHANGED"
          ecc-agentshield scan $CHANGED \
            --config .ecc/agentshield.config.json \
            --reporter github-annotations \
            --fail-on secrets,injections

      - name: Post scan summary to PR
        if: always()
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const report = fs.existsSync('agentshield-report.json')
              ? JSON.parse(fs.readFileSync('agentshield-report.json'))
              : { summary: 'No report generated.' };
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 🛡️ ECC AgentShield Scan\n\`\`\`\n${JSON.stringify(report.summary, null, 2)}\n\`\`\``,
            });

Custom agentshield Configuration

// .ecc/agentshield.config.json
{
  "version": "1",
  "rules": {
    "secrets": {
      "enabled": true,
      "custom_patterns": [
        {
          "id": "internal-api-key",
          "description": "Internal service API key pattern",
          "regex": "ISK-[A-Za-z0-9]{32}",
          "severity": "critical"
        },
        {
          "id": "db-connection-string",
          "description": "PostgreSQL connection string",
          "regex": "postgres(?:ql)?:\/\/[^:]+:[^@]+@",
          "severity": "critical"
        }
      ],
      "entropy_threshold": 4.2,
      "exclude_paths": ["**/*.test.ts", "fixtures/"]
    },
    "prompt_injection": {
      "enabled": true,
      "signatures": [
        "ignore previous instructions",
        "disregard your system prompt",
        "you are now in developer mode"
      ],
      "scan_targets": ["**/*.md", "**/*.txt", "**/*.json"]
    },
    "unsafe_shell": {
      "enabled": true,
      "patterns": [
        { "match": "curl.*\\|.*sh", "severity": "critical" },
        { "match": "eval\\(", "severity": "high" },
        { "match": "exec\\(.*\\$\\{", "severity": "high" }
      ]
    }
  },
  "reporting": {
    "output_file": "agentshield-report.json",
    "fail_on": ["critical", "high"]
  }
}

---

Cross-Harness Architecture: Using ECC Beyond Claude Code

The ECC Cross-Harness Layer Explained (v2.0.0-rc.1)

ECC v2.0.0-rc.1 ships a cross-harness abstraction layer documented in docs/architecture/cross-harness.md. The core insight is that every supported harness exposes roughly the same primitives—a way to inject context, a way to call tools, a way to persist state—but with wildly different APIs and file formats. ECC's adapter shims normalize these differences so your skills and hooks are written once and deployed everywhere.

Migrating Skills from Claude Code to Cursor or Codex

When you run ecc sync --harness cursor in a project that already has Claude Code skills, ECC:

1. Reads each skill's harnesses array to check compatibility.
2. Generates Cursor-native .cursorrules fragments and MDC files from your rules/ definitions.
3. Converts MCP configurations to Cursor's tool manifest format.
4. Warns you about any skill that uses Claude-Code-specific APIs (like agent.mcp.fetch) with a suggested Cursor equivalent.

Handling Harness-Specific Quirks with Adapter Shims

| Feature | Claude Code | Codex | Cursor | OpenCode | Gemini | Zed | GitHub Copilot | |---|---|---|---|---|---|---|---| | Skills | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ⚠️ Partial | ⚠️ Partial | ⚠️ Partial | | Hooks | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ❌ None | ⚠️ Partial | ❌ None | | Memory (3 scopes) | ✅ Full | ⚠️ Session only | ✅ Full | ✅ Full | ❌ None | ❌ None | ❌ None | | agentshield | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ✅ Full | ✅ Full | | MCP configs | ✅ Full | ⚠️ Partial | ✅ Full | ✅ Full | ✅ Full | ⚠️ Partial | ❌ None |

The Hermes operator story (introduced in v2.0.0-rc.1) layers on top of this: Hermes is the name for the default operator identity that ECC installs across all supported harnesses, giving your agents a consistent "persona" with unified memory and skill access regardless of which harness the developer uses that day.

---

Limitations and Known Constraints

ECC earns its stars, but ship with realistic expectations.

Harnesses with Partial ECC Support in 2025

Gemini, Zed, and GitHub Copilot support Skills but not Hooks or full Memory scoping. If your team is locked into one of these harnesses, you lose event-driven skill invocation—you'll need to call skills manually or trigger them from CI rather than on file-save events. The ecc sync command will warn you about every unsupported feature per harness; don't ignore these warnings.

Memory Optimization Trade-offs at Large Scale

The LRU pruning strategy in session scope is aggressive by design. If your project has rare-but-critical context (a single edge-case constraint you mentioned once three hours ago), it will be pruned before a common duplicate. Mitigate this by tagging important items: agent.memory.tag('constraint', 'never use setTimeout in service workers'). Items tagged constraint, decision, or error are preserved regardless of LRU score.

ecc-agentshield False Positive Rate and Tuning

Out of the box, agentshield's entropy-based secret detection fires on high-entropy test fixture strings, base64-encoded images in source files, and certain minified CSS strings. Expect 5-15 false positives per thousand files on a typical codebase until you configure exclude_paths and calibrate entropy_threshold. The default of 3.5 is too sensitive for most codebases; 4.2 is a better starting point for TypeScript/JavaScript projects.

Private Repo Features Require ECC Pro ($19/seat/month)

The GitHub App (150+ installs) and private repository scanning via the cloud dashboard are ECC Pro features. The CLI tools (ecc-universal, ecc-agentshield) are MIT-licensed and fully functional for local and self-hosted CI use. If your org needs PR-level annotation, team-shared memory sync, or the managed agentshield cloud scanner, budget $19/seat/month. For solo developers or open-source projects, the free tier covers everything in this article.