Epic Harness

A self-evolving AI coding agent harness — 3 commands, 26 skills, 1 autonomous pipeline, learns from your failures.

Less to memorize. More intelligence per keystroke. Gets smarter every session.

English | 日本語 | 한국어 | Deutsch | Français | 简体中文 | 繁體中文 | Português | Español | हिन्दी

A Claude Code plugin that consolidates 30+ commands into 3 commands + 26 auto-trigger skills, and evolves new skills from your own failure patterns.

Web Dashboard — auto-launches on session start

10-screen real-time metrics for eval scores, tool stats, orbit pipelines, evolved skills, and hook health. Opens automatically with the first Claude Code session — no manual setup needed. The Eval & Evolve screen surfaces the HarnessX evolution-engine state: reward-hacking warnings, seesaw solved-task registry, variant pool, and the adaptation landscape (persistent failures + untried edit types).

# Auto-launches on first session (default: http://localhost:7700)
# Configure port or disable in ~/.harness/config.toml:
[dashboard]
port = 7700       # set to 0 to disable auto-launch
auto_open = true  # open browser on first session

Screens: Dashboard · /orbit Pipeline · Commands (3) · Skills (26) · Live Agents · Eval & Evolve · Hooks (6) · Integrations (6) · harness-mem · Settings

What It Does

One command ships a feature end-to-end. Skills fire without you asking. The agent gets smarter after every session.

$ /orbit "Add JWT auth to the login API"
→ spec approved → go (TDD subagents) → check (PASS) → ship (PR + CI) → evolve

Or invoke pipeline skills directly:

/spec "Add JWT auth to the login API"   # clarifies requirements → SPEC-*.md
/go                                      # auto-plans → TDD subagents → 4 min
/check                                   # parallel review + security + tests → PASS
/ship                                    # isolated test → PR → CI green

Skills trigger automatically in the background — no extra commands:

Writing a feature?    → tdd fires (Red→Green→Refactor enforced)
Test fails?           → debug fires (root-cause first, no random fixes)
Touching auth or DB?  → secure fires (OWASP checklist, no shortcuts)
File hits 200 lines?  → simplify fires (extract, rename, reduce)

After the session ends, the evolve loop analyzes what broke, generates targeted skills, and loads them next session. The agent that struggled with TypeScript build failures will have an evo-ts-care skill next time.

Installation

First time? Read the Quick Start Guide (5 min).

epic-harness ships as a plugin — skills, hooks, and the harness-mem MCP server are loaded directly from the plugin layout (skills/, hooks.json, .mcp.json). There is no install subcommand; each tool reads the plugin from disk.

Claude Code (recommended)

/plugin marketplace add epicsagas/plugins
/plugin install epic@epicsagas

Auto-installs the binary, skills, hooks, and the harness-mem MCP server in one step.

agy (Antigravity CLI)

agy plugin install .

Skills (27), hooks, and the harness-mem MCP server are auto-discovered from the plugin's plugin.json + skills/ + hooks.json + .mcp.json.

Codex CLI

codex plugin marketplace add epicsagas/plugins

Skills and agents are available immediately — no further steps needed.

Binary-only (no plugin host)

brew install epicsagas/tap/epic-harness      # macOS / Linux (Homebrew)
cargo binstall epic-harness                  # pre-built binary (Rust)
cargo install epic-harness                   # build from source

No Homebrew? Use the installer script:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/epicsagas/epic-harness/releases/latest/download/install.sh | sh

Windows:

irm https://github.com/epicsagas/epic-harness/releases/latest/download/install.ps1 | iex

The binary self-seeds ~/.harness/config.toml and HARNESS.md on the first hook run — no setup wizard, no install step.

epic-harness --version to verify. Update with brew upgrade epic-harness or re-run the installer script.

Prerequisites: Git. Source/binary installs also need the Rust toolchain.

Verify

epic --version              # Binary installed
ls ~/.harness/              # Data directory (auto-created on first session)

Inside a Claude Code session: /evolve status

Telemetry: usage reporting is on by default (opt-out). Toggle with epic-harness telemetry status|on|off.

Telemetry

epic-harness collects anonymous usage telemetry by default (opt-out) to improve hook reliability and skill evolution. Events are sent to Posthog.

What we collect: command name, duration, outcome (success/failure), failure class, and hook block/failure events — plus product, product_version, os, and a random install_id (a UUID generated on first run, stored at ~/.config/epic-harness/install-id).

What we never collect: source code, file contents, file paths, environment variables, secrets, or any personally-identifiable information.

Control it:

epic-harness telemetry status   # show current consent
epic-harness telemetry off      # disable (stops all sending immediately)
epic-harness telemetry on       # re-enable

Consent is stored at ~/.config/epic-harness/telemetry-consent. When off, no telemetry is sent.

Commands

Pipeline stages (/spec, /go, /check, /ship, /discover) are now skills — they auto-trigger via context or can be invoked by name. Legacy command names still work via alias routing.

/orbit — Autonomous Pipeline

/orbit wraps the entire pipeline into a single autonomous execution. Pick a mode — everything else is hands-off until the PR.

flowchart TD
    START(["/orbit"]) --> MODE{"requirement?"}:::human
    MODE -->|"unclear"| WAIT["Interactive\n/discover → /spec\nthen 'orbit go'"]:::human
    MODE -->|"clear + complex"| COUNCIL["Council\n4-voice auto-spec"]:::auto
    MODE -->|"clear + simple"| DIRECT["Direct\nauto-spec"]:::auto
    WAIT --> SPEC_LOAD["Load spec"]
    COUNCIL --> SPEC_LOAD
    DIRECT --> SPEC_LOAD
    SPEC_LOAD --> GO["Go\nplan → TDD → integrate"]:::auto
    GO --> CHECK["Check\nreview + audit + test"]:::auto
    CHECK -->|"PASS / WARN"| SHIP["Ship\nisolated test → PR → CI"]:::auto
    CHECK -->|FAIL| RETRY{"retry < 3?"}
    RETRY -->|yes| GO
    RETRY -->|no| PAUSE["Pause\nuser decides"]:::human
    PAUSE -->|continue| GO
    PAUSE -->|abort| ABORT(["Abort"])
    SHIP --> EVOLVE["Evolve\nauto-analyze session"]:::auto
    EVOLVE --> DONE(["Orbit Complete\nconsolidated report"]):::auto

    classDef human fill:#4a4a6a,stroke:#9b9bcc,color:#fff
    classDef auto  fill:#1a5c3a,stroke:#4caf7d,color:#fff

Purple — human steps: mode selection (unclear → interactive), 3× check failure pause. Green — clear + complex → council auto-spec; clear + simple → direct build; both fully autonomous.

State persisted in $HARNESS_DIR/orbit/PIPELINE-{timestamp}.json — survives context compaction.

Caveats: The agent may bypass the pipeline when modifying orbit itself or editing docs only. See Known Issues (Agent Judgment).

Auto Skills (Ring 2)

Skills trigger automatically based on context. You don't invoke them.

Token budget note: Claude Code loads skill descriptions into every session context. epic's 26 skills fit within the default skillListingBudgetFraction: 0.01 (1%). If you install additional skills (e.g. episteme, alcove, obscura), the combined total may exceed the budget and trigger a "descriptions dropped" warning. Add this to ~/.claude/settings.json to fix it:

"skillListingBudgetFraction": 0.02

Use 0.03 if you have 20+ skills installed.

Evolve (Ring 3)

The harness watches every tool call, scores it on 3 axes, detects failure patterns, and generates targeted skills — automatically, at session end.

Scoring

composite = 0.5 × tool_success + 0.3 × output_quality + 0.2 × execution_cost

Failure classification (9 types): type_error · syntax_error · test_fail · lint_fail · build_fail · permission_denied · timeout · not_found · runtime_error

Pattern Detection

Evolution Flow

Observe (PostToolUse — 3-axis scoring)
    ↓ obs/session_{id}.jsonl
Analyze (SessionEnd)
    ↓ per-tool, per-ext scores + patterns
Propose (Solver — graduated by score: ≥0.90 skip, ≥0.70 moderate, <0.70 full)
    ↓ SkillProposal[] with confidence
Curate (Accept/Merge/Skip, feedback masked from solver)
    ↓ evolved/{skill}/SKILL.md + meta.json
Gate (format check, dedup, cap 10, gated promotion ≥ 3 sessions)
    ↓ evolved_backup/ (best checkpoint)
Instinct (high-success patterns → cross-project memory.db nodes)
    ↓
Reload (next session — resume loads evolved skills)

Skill seeding: weak tool (success <60%, min 5 obs), weak file type (success <50%, min 3 obs), high-frequency error (5+ occurrences).

Stagnation: 3 sessions without 5% improvement → auto-rollback to best checkpoint.

SkillOpt-Inspired Optimization

Three deep learning-inspired techniques adapted from SkillOpt:

Prompt Auto-Tuning

Underperforming evolved skills receive targeted tuning guidance appended after <!-- auto-tuned --> delimiter. Original content is never modified. 3 consecutive declining sessions → auto-rollback tuning, history cleared.

Skill Effectiveness

Every evolved skill tracked with A/B attribution:

/evolve history → Skill Effectiveness

| Skill              | With | Without | Delta |
|--------------------|------|---------|-------|
| evo-ts-care        | 0.87 | 0.72    | +15%  |
| evo-bash-discipline| 0.65 | 0.68    | -3%   |

Positive delta = effective. Negative = consider removing via /evolve rollback.

Cold-Start Presets

On first session, stack-appropriate preset skills auto-apply:

Instinct Learning

High-success patterns extracted and promoted across projects:

observe (100% confirmed) → extract_instincts() → instinct node (confidence ≥ 0.8)
    → promote to global when observed in ≥ 2 projects

/evolve              # Run now
/evolve status       # Dashboard: scores, trends, patterns, skills
/evolve history      # Full history + skill effectiveness
/evolve cross-project # Cross-project pattern analysis
/evolve rollback     # Restore previous best
/evolve reset        # Clear all evolution data

HarnessX-Inspired Defenses (v0.7.0)

The evolution loop now carries the safety mechanisms from the HarnessX paper's AEGIS pipeline, adapted to epic-harness's single-agent, per-project model. See docs/references/operational-mirror.md for the RL-analogy mapping.

A regression harness (tests/evolve_regression_test.rs) locks these contracts with 6 hermetic scenarios — no live benchmark required.

Harness Snapshot (v0.7.0)

The harness is now a serializable, comparable first-class object:

epic harness snapshot              # JSON: config + skills + guard rules + metrics + content hash
epic harness diff before.json after.json   # field-by-field structural diff
# (restore is deferred — destructive)

Security Pipeline

Three-stage vulnerability assessment pipeline ported from defending-code:

/threat-model    # 1. Trust boundaries, threat actors, scenarios → THREAT_MODEL.md
/vuln-scan       # 2. 4-dimension scanner (injection, auth, data exposure, deps) → VULN-FINDINGS.json
/triage          # 3. Adversarial validation, severity adjustment, chaining → TRIAGE.json

Audit --strict Mode

For security engagements, --strict mode enforces independence between audit modes:

• Code, security, and test reviewers receive only the diff + spec — no builder context
• Cross-check independence: modes run blind until synthesis
• Blind scoring prevents anchoring bias

Optional engagement context via .harness/engagement.md in project root (authorization, scope, constraints, exclusions). See docs/references/engagement.md for the template.

Hooks (Ring 0)

Run invisibly on every session. Single Rust binary (epic-harness) with subcommands.

Polish feeds back into observe: format failure → lint_fail, TypeScript error → build_fail. Edit→Error thrashing gets detected even when errors come from polish.

Each session writes its own session_{date}_{pid}_{random}.jsonl — multiple concurrent sessions won't corrupt each other's data.

Hook Profiles

Via ~/.harness/config.toml or EPIC_HOOK_PROFILE env var:

Custom Guard Rules

Add project-specific rules via .harness/guard-rules.yaml in your project root:

blocked:
  - pattern: kubectl\s+delete\s+namespace | msg: Namespace deletion blocked
warned:
  - pattern: docker\s+system\s+prune | msg: Docker prune — verify first

Team (epic team)

Teams are org-level, not project-bound. Running /team in any project enriches a shared pool of agent definitions — never silently overwrites.

epic team                              # Interactive: scan → design → write → sync
epic team sync backend                 # Dispatch agents → .claude/agents/backend/
epic team link backend                 # Dispatch + register project in team config
epic team list                         # All teams in current org
epic team list --org netflix           # Teams in a named org
epic team show backend --playbook      # Config + full playbook
epic team delete backend               # Recall from current project only
epic team delete backend --global      # Permanently delete from org store

After syncing, agents are available in the next session: @domain-expert, @reviewer, @tester, etc.

Multi-org: epic team --org netflix — separate topology per org.

Merge strategy: changed agents prompt (default: keep existing, backup to .history/). Playbook always appends.

Multi-Tool Support

All tools share the same ~/.harness/projects/{slug}/ data directory.

¹ codex_hooks = true in ~/.codex/config.toml · ² Plugin install; subagent support not yet available · ³ Cursor 1.7+ · ⁴ JS plugin · ⁵ 5 hook scripts · ⁶ Conventions only

Architecture: 4-Ring Model

flowchart TB
    subgraph R0["Ring 0 — Autopilot (hooks, invisible)"]
        direction LR
        h1(resume) --- h2(guard) --- h3(polish) --- h4(observe) --- h5(snapshot) --- h6(reflect)
    end

    subgraph R1["Ring 1 — Commands (you call these)"]
        direction TB
        subgraph orbit_wrap["  /orbit  "]
            direction LR
            c1("spec") --> c2("go") --> c3("check") --> c4("ship") --> c5("evolve")
        end
        c6("/team")
        c7("/evolve (manual)")
    end

    subgraph R2["Ring 2 — Auto Skills (context-triggered)"]
        direction LR
        s1(spec) --- s2(go) --- s3(check) --- s4(ship) --- s5(tdd) --- s6(debug) --- s7(secure) --- s8(perf) --- s9(simplify) --- s10(verify) --- s11(audit) --- s12(eval) --- s13(threat-model) --- s14(vuln-scan) --- s15(triage)
    end

    subgraph R3["Ring 3 — Evolve (self-improving)"]
        direction LR
        e1(observe) --> e2(analyze) --> e3(seed) --> e4(gate) --> e5(reload)
    end

    R0 -->|"observe every tool call"| R3
    R3 -.->|"evolved skills"| R2
    R1 -->|"auto-trigger skills"| R2
    R0 -->|"resume: restore context"| R1

Cross-Project Learning

Opt-in to share failure patterns across projects:

touch ~/.harness/projects/{slug}/.cross-project-enabled

Session end → exports anonymized patterns to ~/.harness/global_patterns.jsonl. Session start → shows hints from other projects' weak areas.

Unified Memory

All agents share a knowledge graph in ~/.harness/memory.db (SQLite with full-text search). No external runtime.

score = recency(25%) + importance(35%) + access_frequency(15%) + FTS_match(25%)

CLI

epic mem recall "auth refactor" --project my-project   # Smart recall
epic mem add --title "JWT rotation" --type decision    # Add node
epic mem search "JWT"                                  # FTS5 search
epic mem list --type decision --project my-project    # Filter
epic mem context --project my-project                  # Project context
epic mem serve                                         # Web UI → :7700 or custom port with --port 8800
epic mem mcp-install                                   # Register MCP server
epic mem export --out ./docs/memory                    # Export to Markdown

MCP Tools (6)

Node Types

Lifecycle: 30+ days without access → 10% importance decay (floor 0.05). 180+ days → tagged stale, excluded from recall. pinned tag prevents decay.

~/.harness/
├── memory.db                  # SQLite knowledge graph (nodes + edges + FTS5)
├── graph.json                 # Cached graph (for web UI)
├── config.toml                # User configuration
├── global_patterns.jsonl      # Cross-project patterns (opt-in)
├── orgs/                      # Team global store
│   └── {org}/teams/{team}/
│       ├── config.json, mission.md, playbook.md, agents/, .history/
└── projects/{slug}/
    ├── memory/                # Project patterns and rules
    ├── sessions/              # Session snapshots (for resume)
    ├── obs/                   # Tool usage observation logs (JSONL)
    ├── evolved/               # Auto-evolved skills
    │   ├── manifest.json
    │   └── {skill}/SKILL.md + meta.json
    ├── evolved_backup/        # Best checkpoint (for rollback)
    ├── dispatch/              # Skill dispatch logs
    ├── evolution.jsonl        # Full evolution history
    └── metrics.json           # Aggregate stats + skill attribution

# Priority: env var (EPIC_HOOK_PROFILE) > this file > defaults

[hook]
profile = "standard"         # "minimal" | "standard" | "strict"
gateguard_hints = true

[scoring]
weights = [0.5, 0.3, 0.2]   # [success, quality, cost]

[evolution]
max_skills = 10
stagnation_limit = 3
improvement_threshold = 0.05
gated_promotion_min = 3

[pattern]
# repeated_error_min = 3
# debug_loop_min = 5
# graduated_scope_skip = 0.90
# graduated_scope_moderate = 0.70

[instinct]
# confidence_threshold = 0.8
# promotion_min_projects = 2
# max_instincts = 20
# min_observations = 10
# min_avg_score = 0.5

Known Issues (Agent Judgment)

These issues arise from the agent's interpretation of context rather than bugs in the code. Listed here so users know what to watch for.

Discovered Issues

Intentional Design Choices

These were considered for enhancement but kept as-is after evaluation:

Troubleshooting

export PATH="$HOME/.cargo/bin:$PATH"

/plugin install epic@epicsagas

xattr -d com.apple.quarantine ~/.cargo/bin/epic-harness
xattr -d com.apple.quarantine ~/.cargo/bin/epic

cp ~/.cargo/bin/epic-harness hooks/bin/epic-harness

Development

cargo install --path .                                        # Build + install
cp ~/.cargo/bin/epic-harness hooks/bin/epic-harness           # Update plugin binary
cargo test                                                    # Tests

Hooks look for the binary in two places: hooks/bin/epic-harness (plugin local) → ~/.cargo/bin/epic-harness (PATH).

Links

• Changelog — release history
• Contributing — how to contribute
• Security — reporting vulnerabilities
• Issues — bug reports and feature requests

Acknowledgments

• a-evolve — Automated evolution and benchmark patterns
• agent-skills — Claude Code agent skill system
• everything-claude-code — Comprehensive Claude Code patterns
• gstack — Plugin architecture reference
• harness — Hook and harness infrastructure patterns
• serena — Autonomous agent design
• SuperClaude Framework — Multi-command framework architecture
• superpowers — Claude Code extension patterns

License

Apache 2.0