affaan-m/ECC: a harness-native agent operating system for Claude Code and Codex

The problem ECC targets: context burned on process, not code

ECC's own framing is narrow. The README says the project exists so that an agent 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. The stated loop is plan, test, implement, review, verify, remember, improve. Its tagline is blunter: optimize the context window, persist everything else.

That is a real complaint among people running long coding sessions. Every new conversation starts from zero, so the operator re-explains the same review standard, the same test-first habit, the same security checks. ECC's answer is to install those as artifacts on disk rather than as prompt text. The README counts 68 agents, 286 skills and 94 legacy command shims, plus hooks, rules, memory and AgentShield security scanning. The audience is the person who already pays for a coding agent and wants the process to survive across sessions and across repositories.

How the artifacts are laid out across seven harnesses

The repository layout is the mechanism. Top-level directories include .claude/, .claude-plugin/, .codex/, .codex-plugin/, .cursor/, .gemini/, .opencode/, .zed/, .qwen/, .kimi/, .hermes/, .pi/, .openclaw/, .adal/ and .trae/. Each holds the configuration that a particular harness reads. The npm package ecc-universal ships those directories in its files list, so an install drops harness-specific files rather than a single generic bundle.

Shared content sits outside them: agents/, commands/, contexts/, config/, docs/, examples/ and docker/. The repository also carries AGENTS.md, CLAUDE.md, SOUL.md, agent.yaml, .mcp.json and COMMANDS-QUICK-REF.md. Examples include per-stack CLAUDE.md files for Django, Rails, Laravel, Rust, Go, Next.js and HarmonyOS, plus unified-memory/ and eval-harness/ directories.

The README is explicit that this is not uniform. It says ECC works best with Claude Code, has a supported Codex sync path, and provides capability-limited adapters for Cursor, OpenCode, Gemini, Zed, GitHub Copilot, Antigravity, Qwen and others, directing readers to a support status matrix before assuming feature parity. Treat the matrix as the real specification. A directory existing for a harness does not mean every skill, hook or memory behaviour is wired up there.

Installing ECC as a Claude Code plugin

The README's simplest path is the native Claude Code plugin. Run these two commands inside Claude Code, not in a shell:

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

The first registers the repository as a plugin marketplace. The second installs the plugin slug ecc@ecc, which the README says brings in ECC's skills, agents, commands and plugin-managed hooks. After that, the README is direct: if you choose this path, stop there, and do not also run a full manual install into Claude Code. Running both is the documented way to get duplicated or conflicting artifacts.

A second path exists for people who want guided setup across harnesses. The package.json names the npm package ecc-universal, and the README notes that ECC 2.2 adds guided package setup through it. The npm package page is listed among the official sources.

A first real use: environment variables and the security scan

Before hooks or MCP-backed features do anything useful, credentials need to be in place. The repository ships .env.example as the canonical list. Copy it and fill in values:

cp .env.example .env

The file defines ANTHROPIC_API_KEY and GITHUB_TOKEN as the two primary entries, with GITHUB_TOKEN described as the token for the MCP GitHub server. It also documents optional keys: DOCKER_PLATFORM for arm64 or amd64 overrides, CLAUDE_CODE_PACKAGE_MANAGER for npm, pnpm, yarn or bun, and OpenAI-compatible endpoints for Astraflow, UModelVerse and Atlas Cloud. The same file carries an ECC agent data section noting that memory hooks for sessions, learned skills, aliases and metrics default to ~/.claude, and that a separate root is appropriate when running ECC in Cursor alongside Claude Code. That isolation setting is the one to read before installing into two harnesses on one machine.

For the security side, the README lists a second npm package, ecc-agentshield, among the official sources. AgentShield is described as security scanning for agents. The README does not document a rollback procedure for the hooks it installs, so plan to review what lands in your harness config directory before committing a repository that contains it.

Where ECC is the wrong tool

The clearest limitation is harness coverage. If your team standardised on Cursor, Zed, Gemini or Antigravity, the README itself calls those adapters capability-limited and points at a support status matrix rather than promising parity. Installing ECC there means accepting a subset of the skills, hooks and memory behaviour that a Claude Code user gets.

A second constraint is the install surface. ECC writes into harness configuration directories and registers hooks. That is the point, but it also means the project touches files your editor and agent read on every session. Teams with a locked-down developer image, or anyone who cannot add plugin marketplaces to a corporate Claude Code install, will need the manual path and a review of what each directory contains.

A third is scope. This is a process layer, not a model, not an inference provider and not a benchmark. It cannot make a weak model plan well. If your sessions are short and single-file, the plan, review and memory machinery is overhead you will not amortise, and the 286 skills become a large surface you never invoke.

Finally, distribution discipline matters. The README carries a warning that only the GitHub repository, the npm packages ecc-universal and ecc-agentshield, the GitHub App, the plugin slug ecc@ecc and ecc.tools are official, and that third-party re-uploads are not maintained or reviewed and may contain malware. Installing from a mirror is the failure mode to avoid.

How ECC differs from a plain rules file

The obvious alternative is a hand-written CLAUDE.md or AGENTS.md plus a few custom commands. That approach is thinner and more portable: one file, no plugin marketplace, no hooks, no install footprint, and nothing to uninstall. The ECC repository even ships examples/CLAUDE.md and per-stack variants like examples/rails-app-CLAUDE.md and examples/saas-nextjs-CLAUDE.md, which is a fair signal that the maintainers consider a rules file a reasonable starting point rather than a competitor to eliminate.

The difference in approach is persistence and enforcement. A rules file states preferences and hopes the model follows them. ECC installs agents, skills and hooks that the harness executes, and it adds a memory layer whose default root is ~/.claude, so learned skills, aliases and session data accumulate outside any single repository. Whether that accumulation helps depends on whether you want state on disk. A rules file keeps your repository self-contained; ECC moves part of the process into your home directory, which is exactly why the .env.example documents a separate root for running two harnesses side by side.

Licence, maintenance and upgrade surface

ECC is MIT-licensed. The README states the repository stays MIT-licensed forever and that ECC Pro, a hosted GitHub App for private repos, is the paid product that funds the work. Package.json for ecc-universal confirms the MIT licence field and version 2.2.1. The pyproject.toml in the repository describes a separate component, llm-abstraction, version 0.1.0, also MIT, requiring Python 3.11 or later and depending on the anthropic and openai packages; note its classifier says Development Status 3 - Alpha, so do not read it as equally mature as the main package.

The release cadence is visible: v2.0.0 on 2026-06-10, v2.1.0 on 2026-07-27 and v2.2.0 on 2026-08-28, with the last push to the default branch on 2026-08-28. That is recent, and the release titles show a pattern of adding harness integrations: Antigravity 2.0 and a Nasiko CLI bridge in 2.2.0, Kimi and self-hosted compute in 2.1.0. Each of those can change what lands in your harness directories, so pin a version rather than tracking main if you have audited the installed files.

On licence implications, MIT permits commercial use and modification, but the Pro tier and the GitHub App are separate commercial offerings with their own terms at ecc.tools/pricing. Nothing here is legal advice; if you redistribute ECC inside a product, read the LICENSE file and the Pro terms yourself.

Editorial conclusion

Adopt ECC if you already live in Claude Code and want the plan, test, review, remember cycle installed once instead of retyped every session. Skip it if Cursor, Zed or Antigravity is your primary harness and you expect parity, because the README points to a support status matrix before you assume it. Verify first which install path you are on: the plugin commands and a manual install both write skills, agents and hooks, and the README warns against running both into Claude Code.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes