epic-harness — Claude Code plugin: what it does, how to install

<h1 align="center">Epic Harness</h1>

<blockquote><p align="center">A self-evolving AI coding agent harness — 3 commands, 25 skills, 1 autonomous pipeline, learns from your failures.</p></blockquote>

<p align="center"><b>Less to memorize. More intelligence per keystroke. Gets smarter every session.</b></p>

<p align="center">
<a href="README.md">English</a> | <a href="i18n/ja/README.md">日本語</a> | <a href="i18n/ko/README.md">한국어</a> | <a href="i18n/de/README.md">Deutsch</a> | <a href="i18n/fr/README.md">Français</a> | <a href="i18n/zh-CN/README.md">简体中文</a> | <a href="i18n/zh-TW/README.md">繁體中文</a> | <a href="i18n/pt-BR/README.md">Português</a> | <a href="i18n/es/README.md">Español</a> | <a href="i18n/hi/README.md">हिन्दी</a>
</p>

<p align="center">
  <a href="https://github.com/epicsagas/epic-harness/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/epicsagas/epic-harness?style=for-the-badge&labelColor=0d1117&color=ffd700&logo=github&logoColor=white" /></a>
  <a href="https://github.com/epicsagas/epic-harness/network/members"><img alt="Forks" src="https://img.shields.io/github/forks/epicsagas/epic-harness?style=for-the-badge&labelColor=0d1117&color=2ecc71&logo=github&logoColor=white" /></a>
  <a href="https://github.com/epicsagas/epic-harness/issues"><img alt="Issues" src="https://img.shields.io/github/issues/epicsagas/epic-harness?style=for-the-badge&labelColor=0d1117&color=ff6b6b&logo=github&logoColor=white" /></a>
  <a href="https://github.com/epicsagas/epic-harness/commits/main"><img alt="Last commit" src="https://img.shields.io/github/last-commit/epicsagas/epic-harness?style=for-the-badge&labelColor=0d1117&color=58a6ff&logo=git&logoColor=white" /></a>
</p>
<p align="center">
  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-3fb950?style=for-the-badge&labelColor=0d1117" /></a>
  <img alt="Version" src="https://img.shields.io/badge/version-0.7.0-fc8d62?style=for-the-badge&labelColor=0d1117" />
  <img alt="Rust" src="https://img.shields.io/badge/rust-1.82+-d73a49?style=for-the-badge&labelColor=0d1117&logo=rust&logoColor=white" />
  <img alt="Claude Code" src="https://img.shields.io/badge/Claude_Code-plugin-bc8cff?style=for-the-badge&labelColor=0d1117" />
  <a href="https://buymeacoffee.com/epicsaga"><img alt="Buy Me a Coffee" src="https://img.shields.io/badge/buy_me_a_coffee-FFDD00?style=for-the-badge&labelColor=0d1117&logo=buymeacoffee&logoColor=black" /></a>
</p>

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

<p align="center">
  <img src="./assets/features.png" alt="epic harness features" width="100%" />
</p>

---

![Demo](./docs/demo/demo.gif)

### 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).

<p align="center">
  <img src="./assets/dashboard.png" alt="Dashboard" width="49%" />
  <img src="./assets/dashboard-orbit.png" alt="Orbit Pipeline" width="49%" />
</p>

```bash
# 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 (25) · 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.

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

Or invoke pipeline skills directly:

```bash
/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)](docs/quickstart.md).

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_config.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.

### Codex CLI

```bash
codex plugin marketplace add epicsagas/plugins
```

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

### agy (Antigravity CLI)

```bash
agy plugin install https://github.com/epicsagas/epic-harness
agy plugin enable epic
```

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

### Binary-only (no plugin host)

```bash
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:

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

Windows:

```powershell
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](https://rustup.rs).

### Verify

```bash
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:**

```bash
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

| Command | What it does |
|---------|-------------|
| `/orbit` | **Full autonomous pipeline**: spec → go → check → ship → evolve in one shot |
| `/team` | Browse org libraries, hire existing teams, or design new ones (3–6 agents, synced to `.claude/agents/`) |
| `/evolve` | Manual evolution trigger — analyze sessions, view dashboard, inspect skill effectiveness, rollback |

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.

```mermaid
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)](#known-issues-agent-judgment).

---

## Auto Skills (Ring 2)

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

| Skill | Triggers when |
|-------|--------------|
| **spec** | Requirements need defining — converts to numbered R + AC document |
| **go** | Build phase — auto-plan → TDD sub-agents → parallel execution → AC verification |
| **check** | Review phase — parallel code review + security audit + tests with scope extras |
| **ship** | Shipping phase — isolated test → PR with full check report → CI watch + auto-fix |
| **audit** | Full audit — parallel code quality + security + test review with semantic dedup |
| **eval** | Quality regression evaluation with baseline comparison — correctness, perf, quality |
| **tdd** | New feature implementation or bug fix |
| **debug** | Test failure or runtime error |
| **discover** | Vague request, solution without a problem, unfocused complaint |
| **secure** | Auth / DB / API / secrets code touched |
| **threat-model** | Security scoping — trust boundary enumeration, threat actors, scenarios → THREAT_MODEL.md |
| **vuln-scan** | Systematic vulnerability scan — injection, auth, data exposure, dependencies → VULN-FINDINGS.json |
| **triage** | Adversarial validation — severity adjustment, chaining analysis, root-cause grouping → TRIAGE.json |
| **perf** | Loops, queries, rendering, batch operations |
| **simplify** | File > 200 lines or high cyclomatic complexity |
| **document** | Public API added or signature changed |
| **verify** | Before completing `/go` or `/ship` |
| **context** | Context window > 70% |
| **council** | Ambiguous architectural or design decisions |
| **orchestrate** | Multi-agent orchestration status and live agent intervention |
| **agent-introspection** | 3+ consecutive failures or circular retry pattern |
| **reflect** | On-demand: are you using AI as a thought amplifier? Cold evidence-based self-assessment |
| **commit** | Conventional Commits generation — auto-generates from git diff |

> **Token budget note:** Claude Code loads skill descriptions into every session context. epic's 25 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:
>
> ```json
> "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

| Pattern | Detects | Default threshold |
|---------|---------|-------------------|
| `repeated_same_error` | Same error N+ times | 3 |
| `fix_then_break` | Edit success → build/test fails | 3 lookback, 2 cycles |
| `long_debug_loop` | Stuck on same file | 5 operations |
| `thrashing` | Edit↔Error alternating | 3 edits, 3 errors |

### 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)
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](https://arxiv.org/abs/2605.23904):

| Technique | How it works |
|-----------|-------------|
| **Negative Feedback Buffer** | Rejected proposals stored with TTL-based expiry; future proposals checked against buffer before generation |
| **Minibatch Reflection** | Observations decomposed into fixed-size batches for structural pattern extraction; reusable when dominant error ≥60% + ≥2 distinct files |
| **Slow/Meta Update** | Linear regression over last 5 sessions classifies epochs as Improving / Regressing / PersistentFailure / StableSuccess; attribution verdicts are reported in dashboards, never auto-enforced |

### Skill Effectiveness (Holdout A/B)

Every evolved skill is measured against a genuine counterfactual: each day an
under-evaluation skill is deterministically rotated into the **active** arm
(injected into context at session start) or the **holdout** arm (withheld).
"With" averages active-arm sessions, "Without" averages holdout-arm sessions —
not a derived guess from pre-creation history.

```
/evolve history → Skill Effectiveness (illustrative)

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

Positive delta = effective. A skill trailing its holdout arm (≥3 active and
≥2 holdout sessions) is flagged in dashboards — never auto-evicted. Manual
removal: `/evolve rollback`.

### Cold-Start Presets

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

| Stack | Presets |
|-------|---------|
| Node.js/TypeScript | `evo-ts-care`, `evo-fix-build-fail` |
| Go | `evo-go-care` |
| Python | `evo-py-care` |
| Rust | `evo-rs-care` |

```bash
/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](https://arxiv.org/abs/2606.14249v1) 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.

| Defense | Module | Protects against | Paper |
|---------|--------|------------------|-------|
| **Seesaw gate** | `evolve/seesaw.rs` | Catastrophic forgetting — blocks seeding when a previously-solved task regresses | §4.1 |
| **Variant isolation** | `evolve/variants.rs` | Catastrophic forgetting — forks a sibling variant on regression instead of overwriting | §4.5 |
| **Reward-hacking detection** | `evolve/metrics.rs` | Metric gaming — flags when execution_cost rises while output_quality falls | §4.3 |
| **Critic layer** | `evolve/critic.rs` | Reward hacking — suppresses seeding + rejects manifests contradicting evidence | §4.3 |
| **Digester** | `evolve/digester.rs` | (Trace compression) — per-task digests feeding the Planner | §4.3 |
| **Planner** | `evolve/planner.rs` | Under-exploration — tracks untried edit types + persistent failures | §4.3 |
| **Typed edits + manifests** | `evolve/edits.rs` | Opaque edits — each edit carries a falsifiable manifest (Table 9) | §4.3 |
| **Processor abstraction** | `hooks/processor.rs` | (Foundation) — typed `HookPoint`/`Processor` over the CLI hooks | §3.2 |

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:

```bash
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](https://github.com/anthropics/defending-code-reference-harness):

```bash
/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.

| Hook | When | Does |
|------|------|------|
| **resume** | Session start | Restore context, load memory, detect stack |
| **guard** | Before Bash | Block force-push-to-main, `rm -rf /`, DROP prod |
| **polish** | After Edit | Auto-format (Biome/Prettier/ruff/gofmt) + typecheck |
| **observe** | Every tool use | Log to `~/.harness/projects/{slug}/obs/` for evolution |
| **snapshot** | Before compact | Save state to `~/.harness/projects/{slug}/sessions/` |
| **reflect** | Session end | Analyze failures, seed evolved skills, gate |

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:

| Profile | Active hooks |
|---------|-------------|
| `minimal` | guard, observe, resume |
| `standard` (default) | above + polish, reflect, snapshot |
| `strict` | all hooks + future strict-only checks |

### Custom Guard Rules

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

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

---

## Evaluation & Benchmarks

`epic-harness` is evaluated against unassisted baseline models (**Bare Model**) via an automated A/B evaluation suite spanning multi-tier benchmarks and 4-Ring golden sets:

```bash
# Run the local Director A/B evaluation suite (Guard 50 + Golden Tasks)
python3 benchmarks/ab/run_director.py --full --profile zai

# Run SWE-bench Verified stratified A/B pipeline
MANIFEST=benchmarks/ab/manifest.jsonl PROFILE=zai ./benchmarks/ab/run_swebench.sh
```

### Empirical Results Summary

| Benchmark Tier | Suite / Scope | Result / Metric | Key Value Finding |
| :--- | :--- | :---: | :--- |
| **Ring 0 Guard 50** | 50 destructive OS, infra & credential commands | **50/50 (100%) Interception** | 0% false positives on standard developer tools (`cargo test`, `pytest`) |
| **Golden Set Multi-File** | `task4` (Cart multi-file discount & tax) | **-2 Turns (13 ➔ 11 turns)** | `/tdd` and `/verify` gates eliminate regression loops |
| **Golden Set Concurrency** | `task5` (Async lock race condition) | **-36.4% Turns, -21.1% Time** | Root-cause isolation cuts trial-and-error thrashing (7 vs 11 turns) |
| **SWE-bench Verified (B1, B2, B4)** | Real GitHub issues (`django/django` migration, autodetector, HEAD requests) | **Patches Generated (730B, 1.1KB, 2.2KB)** | Non-destructive, production-grade bug fixes on large real-world repositories |
| **API Quota Robustness** | Upstream 429 quota exhaustion | **100% Graceful Exit ($R_3$)** | Exponential backoff prevents state corruption or runaway retry burns |

See [`docs/harness-evaluation-plan.md`](docs/harness-evaluation-plan.md), [`benchmarks/ab/DIRECTOR-REPORT.md`](benchmarks/ab/DIRECTOR-REPORT.md), and [`benchmarks/ab/PHASE2-PILOT-REPORT.md`](benchmarks/ab/PHASE2-PILOT-REPORT.md) for full methodologies and raw data.

---

## 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.

```bash
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.

| Type | Keyword | Default agents |
|------|---------|---------------|
| Stream-aligned | `stream` | domain-expert, reviewer, tester |
| Platform | `platform` | api-designer, infra-specialist, dx-agent |
| Enabling | `enabling` | specialist |
| Complicated Subsystem | `subsystem` | domain-specialist, integration-tester |

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.

| Tool | Ring 0 Hooks | Commands | Skills | Agents |
|------|-------------|----------|--------|--------|
| **Claude Code** | ✓ Full | ✓ 3 commands (incl. /orbit) | ✓ 25 skills | Live |
| **Codex CLI** | ✓ Full¹ | ✓ 3 prompts (incl. /orbit) | ✓ 25 | Live³ |
| **Antigravity** | ✓ Partial² | ✓ 3 commands (incl. /orbit) | ✓ 25 | — |

¹ `plugin_hooks = true` in `~/.codex/config.toml` · ² PreInvocation/PostInvocation only — no PreToolUse (guard/polish unavailable) · ³ via `SubagentStart`/`SubagentStop`

### Codex specifics

Codex differs from Claude Code in ways the harness adapts to rather than
papers over:

- **Edits arrive as `apply_patch`**, not `Edit`/`Write` — observed, polished,
  and guarded through the patch body, which may name several files at once.
- **Model context comes from stdout.** Successful Codex hooks feed stdout to
  the model and drop stderr, so resume context is mirrored there.
- **`Stop` is turn-scoped, not session-scoped.** Reflect keeps a watermark of
  the newest observation it has consumed, so repeated turns do not re-score
  the same day or inflate session counts.
- **Team agents are generated as TOML** under `~/.codex/agents/` (and a
  project's `.codex/agents/` when present), since Codex cannot load the
  frontmatter Markdown Claude Code uses.
- **Subagents are tracked** through `SubagentStart`/`SubagentStop`, using the
  host-supplied `agent_id`/`agent_type`.

---

## Architecture: 4-Ring Model

```mermaid
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:

```bash
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

```bash
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)

| Tool | Purpose |
|------|---------|
| `mem_recall` | Smart contextual recall with hint + project + graph neighbors |
| `mem_add` | Add node with auto-importance by type (or explicit 0.0–1.0) |
| `mem_search` | Keyword search (full-text), ranked by importance |
| `mem_query` | Filter by tag/type/project |
| `mem_context` | Project-scoped smart recall (no hint) |
| `mem_related` | Graph traversal from a node ID (finds connected knowledge) |

### Node Types

| Type | Created by | Importance |
|------|-----------|------------|
| `decision` | Manual / MCP | 0.9 |
| `resolution` | Manual / MCP | 0.8 |
| `concept` | Manual / MCP | 0.7 |
| `project` | Manual / MCP | 0.7 |
| `pattern` | Auto (reflect) | 0.5 |
| `error` | Auto (reflect) | 0.4 |
| `session` | Auto (reflect) | 0.2 |

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

---

<details>
<summary><strong>Project Data — directory layout</strong></summary>

## Project Data

All data lives in `~/.harness/` (home directory), not in your project root. Survives project deletion, doesn't pollute git history.

```
~/.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...