agent-harness-optimizer

name	agent-harness-optimizer
description	Agent harness optimization patterns for token efficiency, memory persistence, session management, and cross-harness parity. Use when optimizing agent performance, reducing token costs,.

Overview

Agent harness optimization is the practice of tuning the runtime environment that surrounds an AI agent -- model selection, prompt structure, hook configuration, memory persistence, and session management -- to maximize output quality while minimizing token cost and latency. Derived from real-world patterns across 10+ months of daily agentic work, these techniques apply to any harness: Claude Code, Cursor, OpenCode, Codex, Gemini, and beyond.

When to Use

Trigger phrases:

• "agent harness optimizer"

• "Token costs are rising faster than output quality"

• "Agents lose context between sessions or after compaction"

• "Hook scripts are slow, brittle, or produce noisy output"

• Token costs are rising faster than output quality

• Agents lose context between sessions or after compaction

• Hook scripts are slow, brittle, or produce noisy output

• You need the same agent behavior across multiple AI coding harnesses

• Session history grows unwieldy and needs structured management

• Background processes are eating into the main context window

• You want to set up continuous learning from session patterns

When NOT to Use

• Task is outside your authorization scope
• You need to implement controls (use implementing-* skills)
• Task is about analysis, not action (use analyzing-* skills)
• You don't have access to target systems
• Task requires compliance expertise (consult professionals)
• Task is about defense, not offense (use defensive skills)

Process

1. Gather requirements and constraints from the user
2. Validate prerequisites (tools, permissions, data)
3. Execute the core operation with error handling
4. Verify output meets quality standards
5. Report results and log for future reference

1. Token Optimization Audit

Assess current token spend across three vectors:

Model Selection Routing

• Use fast/cheap models (Haiku-class) for: lint checks, simple file reads, status queries, hook callbacks
• Use standard models (Sonnet-class) for: code generation, refactoring, test writing, standard tasks
• Use premium models (Opus-class) for: architecture decisions, security review, complex debugging, multi-system changes
• Route dynamically: if task.complexity < 3 then fast_model elif task.complexity < 7 then standard_model else premium_model

System Prompt Slimming

• Audit CLAUDE.md and AGENTS.md for redundant instructions -- most projects have 30-50% duplication
• Move rarely-used instructions to category-specific files loaded on demand
• Use compact formats: bullet lists over paragraphs, code over prose
• Target: system prompt under 4K tokens for standard workflows, under 8K for complex projects
• Strip instructions that duplicate harness defaults (e.g., "use Read tool" when the harness already enforces this)

Background Process Isolation

• Never run builds, tests, or long-running commands in the main context window
• Use run_in_background: true for all operations over 5 seconds
• Offload analysis to cheaper models via subagent delegation
• Use Grep/Glob for discovery instead of Bash find/grep to reduce output tokens

2. Memory Persistence via Hooks

Implement session-persistent memory using hook-based save/load:

SessionStart Hook (Load)

# On session start, load prior context
# Read project memory, notepad, and recent session summary
cat .omc/project-memory.json 2>/dev/null
cat .omc/notepad.md 2>/dev/null

PreToolUse Hook (Capture)

# Capture tool calls and prompts for pattern extraction
echo "$(date +%s)|$TOOL_NAME|$INPUT_PREVIEW" >> .omc/session-trace.log

PostToolUse/Stop Hook (Save)

# On session end, persist learnings
# Save key decisions, patterns learned, errors encountered
# Keep under 2000 chars to avoid context bloat on next load

Memory File Structure

.omc/
  project-memory.json    # Persistent project context (conventions, stack, decisions)
  notepad.md             # Working memory (auto-pruned after 7 days)
  session-trace.log      # Tool call log for pattern extraction
  state/                 # Mode-specific state (autopilot, ralph, etc.)

3. Session Management

Manage agent sessions with structured lifecycle commands:

Branch -- Create isolated work contexts per task

• Each task gets a git worktree or branch for isolation
• Prevents context bleed between unrelated tasks

Search -- Query prior session history

• Search session transcripts for patterns, decisions, and solutions
• Avoid re-solving problems already solved

Export -- Extract session artifacts

• Export decisions, code changes, and learnings as structured documents
• Share across team or feed into continuous learning

Compact -- Reduce active context size

• Summarize conversation history into dense notes
• Remove resolved tool outputs, keep only decisions and blockers
• Target: compact to 30% of original size

Metrics -- Track session efficiency

• Tokens spent per task, per tool, per decision
• Time-to-completion for common task types
• Error rate and retry count

4. Hook Runtime Controls

Configure hook behavior at runtime without editing files:

# Set strictness profile
export ECC_HOOK_PROFILE=minimal    # Only critical hooks (security, error)
export ECC_HOOK_PROFILE=standard   # Default -- lint, typecheck, memory
export ECC_HOOK_PROFILE=strict     # All hooks including style, docs

# Disable specific hooks temporarily
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

# Cap SessionStart context size
export ECC_SESSION_START_MAX_CHARS=4000

# Disable SessionStart context for low-context setups
export ECC_SESSION_START_CONTEXT=off

# Suppress cost warnings but keep other context/scope warnings
export ECC_CONTEXT_MONITOR_COST_WARNINGS=off

Hook Profile Design Principles

• minimal: For fast iteration, debugging, and exploration. Only blocks security violations.
• standard: For daily development. Includes type checking, lint, and memory hooks.
• strict: For production code, PRs, and releases. Enforces style, docs, and full verification.

5. Cross-Harness Parity

Ensure agent behavior is consistent across harnesses:

Concern	Claude Code	Cursor	OpenCode	Codex	Gemini
Rules location	~/.claude/rules/	.cursorrules	opencode.json	AGENTS.md	System prompt
Hooks	Native hook system	File watchers	Plugin events	None	None
Skills/Commands	Plugin + slash commands	Custom instructions	Plugins + commands	Markdown only	Prompt-only
Memory	.claude/ directory	.cursor/	.opencode/	Project root	External store
MCP	Native support	Limited	Plugin-based	None	None

Parity Checklist

• Core instructions translated to each harness's native format
• Hooks replicated as file watchers or plugin events where native hooks unavailable
• Skills portable as markdown with harness-agnostic trigger detection
• Memory files in project root (harness-agnostic) with harness-specific symlinks
• Test each harness independently: same input should produce same output quality

6. Continuous Learning from Sessions

Feed session patterns back into the system:

Observation Capture (automatic via hooks)

• Record: tool calls, user corrections, error resolutions, repeated workflows
• Scope: project-specific patterns stay project-scoped, universal patterns become global

Pattern Detection (background analysis)

• User corrections become instinct candidates (confidence: 0.3-0.5 initially)
• Repeated successful patterns increase confidence (up to 0.9)
• Failed patterns decrease confidence or get removed

Evolution Path

Observation -> Instinct (0.3) -> Validated Instinct (0.7) -> Skill (0.9)

• Instincts below 0.5 confidence are suggestions only
• Instincts above 0.7 are auto-applied with logging
• Instincts at 0.9+ are candidates for promotion to reusable skills

Common Rationalizations

Rationalization	Reality
"The model is expensive so the harness does not matter"	Harness optimization typically reduces tokens 40-60% with no quality loss
"Hooks slow down my workflow"	A well-tuned hook profile adds under 2 seconds and catches errors that cost minutes to debug later
"Cross-harness support is not needed -- I only use Claude Code"	Team members and CI pipelines may use different harnesses; parity prevents drift
"Memory persistence is overkill for small projects"	Even small projects benefit from remembering past decisions to avoid re-debating settled questions
"System prompt length does not matter with 200K context"	Longer system prompts increase latency, cost, and the chance the model ignores key instructions

Red Flags

• Token spend increasing without corresponding quality improvement
• Hooks producing errors or warnings that get ignored repeatedly
• Session context hitting limits mid-task (needs compaction strategy)
• Same bugs reappearing across sessions (memory/learning not working)
• Agent behavior differs significantly across harnesses for the same project
• Background processes leaking into main context window
• Hook scripts exceeding 3 seconds execution time
• System prompt over 8K tokens with no measurable quality benefit

Verification

• System prompt audit complete: under 4K tokens for standard, under 8K for complex projects
• Model routing configured: fast/standard/premium tiers mapped to task complexity
• Memory persistence working: session start loads prior context, session end saves learnings
• Hook profile set to appropriate strictness for the current work mode
• Background isolation confirmed: no long-running commands in main context
• Cross-harness test passed: core workflow works on at least 2 harnesses
• Session metrics tracked: token cost per task measured and within budget
• Continuous learning active: observations being captured and instincts accumulating