ECC — The Open-Source Agent Harness OS for Claude Code and Beyond

Most "AI coding setups" I've seen are a dumped CLAUDE.md and a couple of slash commands someone copied from a Twitter thread. ECC is the opposite extreme. It's a structured, versioned, cross-harness agent harness operating system — 278 skills, 67 specialized subagents, 94 legacy command shims, a full hook runtime, learned-instinct memory, and a security auditor — all wired together and installable in under two minutes. It's been in daily production use by its author for 10+ months, built while shipping real products. That provenance matters to me.

What "Agent Harness OS" Actually Means

The framing is ambitious but it holds up. When you install ECC, you're not just getting a config file. You're getting a layered system with distinct, composable surfaces:

• Skills — the primary workflow surface. Markdown files with YAML frontmatter describing a workflow (TDD loop, security review, deployment pattern, etc.) that the agent loads and follows. Over 278 of them, covering everything from tdd-workflow to autonomous-loops to perl-security.
• Agents — 67 scoped subagents for delegation. code-reviewer, security-reviewer, mle-reviewer, pytorch-build-resolver, harmonyos-app-resolver — each declared with a tool list and model preference. You invoke them explicitly or let the harness delegate automatically.
• Hooks — event-driven automations that fire on PreToolUse, PostToolUse, Stop, and SessionStart. Auto-format on file edit, block console.log commits, secret detection in prompts, session memory persistence. All implemented in portable Node.js scripts so they run on Windows, macOS, and Linux without shell compatibility nightmares.
• Rules — always-follow guidelines organized into common/ (language-agnostic: git workflow, security, testing, coding style) plus language-specific packs for TypeScript, Python, Go, Swift, PHP, and HarmonyOS/ArkTS.
• Instinct-based memory — a continuous learning system that extracts patterns from your sessions, scores them by confidence, and injects the highest-confidence ones back at session start. It learns your codebase's idioms over time.

Cross-Harness Is the Real Story

ECC works across Claude Code, Cursor, Codex (app + CLI), OpenCode, Zed, GitHub Copilot, and several others. That's not marketing copy — the architecture supports it. For Cursor, ECC uses a DRY adapter pattern: a thin adapter.js translates Cursor's hook event format into the same shape Claude Code uses, so the shared scripts/hooks/*.js files run without duplication. For Codex, it generates a .codex/config.toml and merges MCP server definitions using an add-only TOML merge strategy. For GitHub Copilot, where there's no hook or agent API, it falls back to a .github/copilot-instructions.md plus reusable .github/prompts/*.prompt.md files.

If you work across multiple tools on the same machine — which increasingly describes senior developers — the cross-harness memory isolation is a detail worth knowing. Set ECC_AGENT_DATA_HOME per harness so your Claude Code and Cursor sessions don't overwrite each other's session summaries:

# In your Cursor shell profile export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc" # Claude Code keeps the default ~/.claude # Session data, learned skills, and metrics stay isolated per harness

Installing It Without Breaking Your Existing Setup

This is where the README earns its length. ECC has three install paths — plugin, manual installer, and CLI — and stacking them is the most common way to end up with duplicated skills and misfiring hooks. The cardinal rule: pick one path and stop there.

For most Claude Code users, the recommended path is the plugin plus manual rule copying:

# Step 1: Install the plugin /plugin marketplace add https://github.com/affaan-m/ECC /plugin install ecc@ecc # Step 2: Clone the repo and copy only the rules you want 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/ # or golang, python, php, swift, arkts

Do not run ./install.sh --profile full after the plugin install. The plugin already loads skills, commands, and hooks. The full installer would copy those same surfaces into your user directories and create duplicate runtime behavior — hooks firing twice, commands appearing twice in /plugin list.

If you've already stacked installs and things look broken, ECC ships a lifecycle wrapper to diagnose and repair:

node scripts/ecc.js list-installed node scripts/ecc.js doctor node scripts/ecc.js repair # Or preview full removal before committing to it node scripts/uninstall.js --dry-run

AgentShield: Security Scanning Baked In

ECC ships a companion tool called AgentShield — a security auditor for your Claude Code configuration itself. It scans CLAUDE.md, settings.json, MCP configs, hooks, agent definitions, and skills across five categories: secrets detection (14 patterns), permission auditing, hook injection analysis, MCP server risk profiling, and agent config review.

# Quick scan, no install needed npx ecc-agentshield scan # Auto-fix safe issues npx ecc-agentshield scan --fix # Three-agent red-team/blue-team/auditor pipeline using Claude Opus npx ecc-agentshield scan --opus --stream

The --opus mode is the interesting one: it runs three Opus agents in parallel — an attacker finding exploit chains, a defender evaluating protections, and an auditor synthesizing both into a prioritized risk assessment. It's adversarial reasoning over your own config, not just pattern matching. Exit code 2 on critical findings makes it CI-gate-friendly.

Rough Edges and Limitations

• Scope is enormous, which cuts both ways. 278 skills means there's almost certainly something useful in here for any stack. It also means the surface area is large enough that understanding the whole system takes real time. Budget a few hours, not 15 minutes.
• Plugin vs. manual install confusion is real. The README handles this thoroughly, but the fact that it devotes several warning blocks to "don't stack install methods" suggests this has burned people repeatedly. Read the install section carefully before touching anything.
• Codex plugin mode is fragile upstream. The repo is honest about this — marketplace discovery works, but runtime skill loading from local marketplaces is unreliable due to an upstream Codex issue (openai/codex#26037). Use the manual sync script for Codex instead of the plugin path.
• Context budget is a real concern. Loading all MCPs, all skills, and all rules simultaneously will compress your effective context window from 200k toward 70k. ECC provides granular controls (ECC_SESSION_START_MAX_CHARS, ECC_DISABLED_MCPS, ECC_DISABLED_HOOKS) but you need to actually use them for high-volume sessions.
• GitHub Copilot support is instruction-layer only. No hooks, no subagent API. Useful, but a significant step down from the Claude Code experience.

Who This Is Actually For

ECC is not a beginner tool and it doesn't pretend to be. It's built for developers who are already running Claude Code or Cursor daily, are hitting the ceiling of ad-hoc prompt engineering, and want a structured system they can version-control, share with a team, and build on top of. The instinct-based memory system in particular rewards long-term use — it gets more useful as it learns your codebase's patterns over weeks of sessions.

If you're shipping production software with an AI coding assistant and you want your agent to behave like a disciplined senior engineer rather than an eager intern, ECC is the most comprehensive open-source system I've found for getting there. Internal link suggestion: link "hook runtime" or "hook automations" to a future DevTools post covering Claude Code hooks and CLAUDE.md configuration patterns.