Hermes Wiki
TechResearch/Harness_Engineering/ecc_agent_harness_toolkit

ECC — Agent Harness Operating System

github.com/affaan-m/ECC — MIT-licensed, single-maintainer, ~239K stars, 36K forks. Install: /plugin marketplace add https://github.com/affaan-m/ECC then /plugin install ecc@ecc in Claude Code, or npx ecc-universal setup.

One line: it's a packaged, opinionated layer of agents/skills/rules/hooks/memory that turns "please use TDD" and "please review your own work" from prompt-text hopes into enforced workflow — plan -> test -> implement -> review -> verify -> remember -> improve. Works with Claude Code natively, has adapters for Codex, Cursor, OpenCode, Gemini CLI, Zed, Copilot, and more, with an explicit support-parity matrix rather than pretending every harness gets the same features.

Directly comparable to what Hermes already does in this vault (nightly cron, lint/fix/synthesis agents, Logs/2026 audit trail) — ECC is the general-purpose, cross-project version of that same idea: don't trust the model to remember the process, make the harness enforce it.

The core distinction: skills vs. agents vs. rules vs. hooks vs. instincts

The most reusable idea in the repo — worth applying to any Claude Code setup, not just ECC's:

Concept What it does Context cost
Skills Reusable workflows (TDD, security review, deep research) Loaded only when the task needs them
Agents Scoped subagents with their own context + tool permissions Isolates planning/implementation/review so one context doesn't both write and grade its own work
Rules Durable, always-loaded project/language standards Always in context — install selectively, one common/ pack + one language pack, not everything
Hooks Scripts triggered by harness events (PreToolUse, Stop, etc.) Runs outside the model context — deterministic, can't be "forgotten"
Instincts Patterns learned from real sessions, with confidence scores, recalled when relevant Continuous-learning-v2's answer to "memory" that isn't just a giant transcript dump

The ## Skills keep the context focused framing is the useful bit: most homegrown harnesses conflate all five of these into one big CLAUDE.md, which is exactly the failure mode this vault's own system_prompt.md layering (see README's "System Prompts Per Project/Feature") already avoids.

TDD as a gated workflow, not an instruction

/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

The output isn't just code — it's an evidence trail: plan, failing test, passing test, review findings, verification. The "review from fresh context" step is the same principle behind spawning a clean subagent for code review rather than asking the implementing context to grade itself (an approach already used in this environment's own /code-review skill).

Unified Memory Vault — cross-harness handoffs

ecc memory gives Claude, Codex, Hermes(!), OpenClaw, Kimi, etc. one shared, local, inspectable Markdown format (ecc.memory.v1) for durable context and handoffs between agents/harnesses:

npm install -g ecc-universal
ecc memory init --scope project
ecc memory handoff --from hermes --target codex --title "..." --body-file ./handoff.md
ecc memory search "authentication migration" --target-harness codex
ecc memory doctor

Key design choice: memory is explicitly unreviewed context, not executable policy — agents must verify recalled claims against authoritative sources rather than treating them as instructions. Project memories are .gitignore'd by default (fail-closed); team-scope memory is the opt-in for version-controlled sharing. Scopes: project (.ecc/memory/) vs. user (~/.ecc/memory/).

AgentShield — treating the harness itself as attack surface

npx -y ecc-agentshield scan --path .

Scans your own agent configs, hooks, MCP setup, permissions, and secrets for vulnerabilities — the framing is that hooks run shell commands, MCP servers hold credentials, and project instructions enter the agent's context, so all three are executable configuration and need auditing like code. Also ships GateGuard, which gates destructive shell commands (rm, force/path git checkout, destructive find -exec) before they execute — a deterministic pre-tool-use guard rather than relying on the model to self-police.

Token optimization settings (directly actionable)

{
  "model": "sonnet",
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  }
}
Setting Default Recommended Why
model opus sonnet ~60% cost cut, handles 80%+ of coding tasks
MAX_THINKING_TOKENS 31,999 10,000 ~70% cut in hidden thinking cost/request
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 95 50 Compacts earlier → better quality in long sessions instead of degrading near the limit

Plus a hard rule worth keeping regardless of ECC: keep under 10 MCPs and under 80 tools active — each MCP tool description eats into the 200K context window, and a heavy MCP load can shrink usable context from 200K to ~70K before a single message is sent.

Continuous learning → skills (the "evolve" loop)

continuous-learning-v2 extracts instinct-level patterns from real sessions (with confidence scores) instead of the v1 approach of raw Stop-hook pattern dumps. /evolve clusters accumulated instincts into reusable skills; /prune deletes expired low-confidence ones. This is the same shape as this vault's own bi-weekly/monthly Hermes synthesis pass, just applied to agent behavior rather than note content.

What's probably NOT worth adopting wholesale

  • The full component count (67 agents, 284 skills, 94 command shims) is built for a general SaaS/multi-language consultancy workload — most of the language-specific rule packs (Laravel, Kotlin, ArkTS, Perl, Quarkus, C++...) are irrelevant to this vault's Localz/Courses/wiki stack.
  • It's a single-maintainer project with a monetized Pro tier (private-repo GitHub App) layered on the OSS core — worth watching for maintenance risk given the size of the surface area, though the OSS core is MIT and self-contained.
  • Don't stack install methods (plugin + manual install simultaneously) — the README is explicit that this duplicates skills/hooks/config.
Hermes Wiki