How to Configure Harness Optimization in ECC: A Complete Guide

To configure harness optimization in ECC, use the harness-optimizer agent to audit your current setup via /harness-audit, propose targeted modifications to /.mcp.json, apply them using /harness-apply, and validate the changes with the /verify command.

The Everything Claude Code (ECC) repository by affaan-m provides a specialized harness-optimizer agent designed to improve local agent-harness configuration for reliability, cost-effectiveness, and throughput without modifying product code. Understanding how to configure harness optimization in ECC enables you to systematically tune hooks, evals, routing rules, and safety policies using built-in slash commands and Model Context Protocol (MCP) configuration files.

Understanding the Harness-Optimizer Architecture

The Harness-Optimizer Agent

The optimization workflow is driven by the agent defined in agents/harness-optimizer.md. This agent declares a specific toolset including Read, Grep, Glob, Bash, and Edit to safely analyze and modify your harness configuration. According to the source code, the agent follows a five-step workflow: run /harness-audit to establish baseline metrics, identify the top three leverage points (hooks, evals, routing, context, or safety), propose reversible configuration changes, apply them to the repository, and report before/after deltas.

The MCP Configuration File

All harness configurations that the optimizer manipulates reside in the hidden MCP file /.mcp.json at the repository root. This JSON file contains:

• Hook registrations (e.g., pre-tool or post-tool hooks)
• Eval definitions used for regression testing
• Routing rules mapping user intents to agents
• Context-size limits and safety policies

Core Commands for Harness Configuration

ECC provides dedicated slash commands documented in COMMANDS-QUICK-REF.md to manage the optimization lifecycle.

Auditing with /harness-audit

The /harness-audit command generates a baseline scorecard of your current harness performance, including latency, error rates, and cost hints. Execute this from the repository root:

claude /harness-audit

The output provides measurable targets:

Harness Audit – Baseline
------------------------
Latency: 120 ms (target < 100 ms)
Errors: 0.2 % (target < 0.5 %)
Cost estimate: $0.003 per 1k calls (target ≤ $0.005)
Safety score: 92 / 100

Applying Changes with /harness-apply

Once you have identified optimizations, use /harness-apply to update /.mcp.json. The command takes a proposed configuration snippet, merges it with existing settings, and automatically re-runs the audit to display performance deltas.

Step-by-Step Configuration Workflow

Step 1: Establish a Baseline

Run the audit command to capture current performance metrics. This creates the foundation for measuring improvement.

Step 2: Identify Optimization Targets

Analyze the audit output to locate leverage points. Common targets include missing pre-tool hooks, inefficient routing rules, or inadequate safety policies.

Step 3: Propose Configuration Changes

Create a JSON snippet addressing the identified issues. For example, to add rate-limiting hooks for API calls:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "tool == \"API\" && tool_input.path matches \"/api/.*\"",
        "hooks": [
          {
            "type": "command",
            "command": "node ./scripts/rateLimit.js"
          }
        ],
        "description": "Enforce per-user rate limits on all API calls"
      }
    ]
  }
}

Save this to a temporary file (e.g., new-hooks.json).

Step 4: Apply and Verify

Execute the apply command:

claude /harness-apply new-hooks.json

The agent will read the current /.mcp.json, merge your snippet while preserving existing keys, edit the configuration file, and run a second audit showing improvements:

Applied changes successfully.
--- Before vs. After ---
Latency: 120 ms → 95 ms
Errors: 0.2 % → 0.1 %
Cost: $0.003 → $0.0025
Safety: 92 → 96

Finally, invoke the verification loop to ensure stability:

claude /verify

This executes the full build, lint, type-check, and test suite defined in skills/verification-loop/SKILL.md.

Safety Constraints and Verification

The harness-optimizer operates under strict safety constraints defined in lines 9-16 of agents/harness-optimizer.md, known as the Prompt Defense Baseline. These rules enforce:

• Non-execution of arbitrary code
• No secret leakage outside the repository
• Untrusted data handling for all fetched content

After any configuration change, the verification-loop skill automatically validates that the harness modification does not break existing functionality by running comprehensive regression tests.

Summary

• The harness-optimizer agent in agents/harness-optimizer.md provides a systematic workflow for tuning ECC harness configurations without modifying product code.
• Configuration changes are applied to /.mcp.json, which controls hooks, evals, routing, and safety policies.
• Use /harness-audit to establish performance baselines and /harness-apply to implement optimizations with automatic before/after comparisons.
• The verification loop in skills/verification-loop/SKILL.md ensures all changes pass build, lint, and test suites.
• Strict Prompt Defense Baseline constraints prevent unauthorized code execution and secret exposure during optimization.

Frequently Asked Questions

What is the harness-optimizer agent in ECC?

The harness-optimizer agent is a specialized component defined in agents/harness-optimizer.md that audits and improves the local agent-harness configuration. It uses tools like Read, Grep, and Edit to analyze /.mcp.json and propose changes that improve reliability, cost-effectiveness, and throughput while adhering to strict safety constraints.

Where is the harness configuration stored in ECC?

The harness configuration is stored in the hidden MCP file /.mcp.json at the repository root. This file contains hook registrations, eval definitions for regression testing, routing rules, context-size limits, and safety policies that the optimizer modifies.

How do I verify that harness optimizations haven't broken my build?

After applying changes with /harness-apply, run the /verify command to invoke the verification-loop skill. This automatically executes the full build, lint, type-check, and test suite to confirm that harness tweaks do not introduce regressions or break existing functionality.

What safety measures prevent the harness-optimizer from executing harmful commands?

The agent operates under a Prompt Defense Baseline (lines 9-16 of agents/harness-optimizer.md) that explicitly forbids arbitrary code execution, prevents secret leakage, and treats all fetched data as untrusted. These constraints ensure that harness modifications remain confined to repository configuration files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}