# Hyperagent

> Run a self-referential self-improving agent loop where a meta-agent iteratively modifies a task-agent's code to optimize for any measurable target. Based on Facebook Research's Hyperagents paper (arXiv:2603.19461). Use when asked to "run hyperagent", "self-improve this", "optimize with self-modification", or "evolve this agent/script".

- **Type:** Skill
- **Install:** `agentstack add skill-ckorhonen-claude-skills-hyperagent`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ckorhonen](https://agentstack.voostack.com/s/ckorhonen)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ckorhonen](https://github.com/ckorhonen)
- **Source:** https://github.com/ckorhonen/claude-skills/tree/main/skills/hyperagent
- **Website:** https://cdd.dev/skills

## Install

```sh
agentstack add skill-ckorhonen-claude-skills-hyperagent
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Hyperagent

## Quick Start — Simple Examples

New to Hyperagent? Try these beginner-friendly tasks before the full setup.

**1. Optimize a simple Python script to run faster**

Say: _"Use hyperagent to optimize this script for speed"_ and paste something like:
```python
# slow_sort.py
def sort_numbers(nums):
    result = []
    while nums:
        smallest = min(nums)
        result.append(smallest)
        nums.remove(smallest)
    return result
```
Hyperagent will benchmark it, propose a faster implementation, and validate the improvement.

**2. Improve a prompt to get better answers**

Say: _"Run hyperagent on this prompt and improve accuracy"_ with a prompt like:
```
Summarize this article in one sentence.
```
The meta-agent iterates on the prompt, measures quality, and keeps improvements that score higher.

**3. Make a sorting function more efficient**

Say: _"Evolve this function with hyperagent"_ and paste any function. Hyperagent creates a benchmark, runs generations of improvements, and shows you the performance gain per generation.

**4. Self-improve any script**

Say: _"Self-improve this agent/script"_ and point to any Python file. Hyperagent wraps it in an evaluation loop, proposes modifications, and tracks what works.

> The simplest possible setup: create `task.sh` that prints `METRIC score=0.5`, then run `python3 scripts/init_session.py`. From there the loop is fully automated.

---

Self-referential self-improvement: a meta-agent that modifies a task-agent (and itself) to optimize any measurable objective.

Inspired by Facebook Research's *Hyperagents* paper (arXiv:2603.19461), which demonstrated that agents combining a task-solver and a self-modifying meta-level into a single editable program can achieve open-ended, compounding improvements that transfer across domains.

## How It Works

A hyperagent is a system with two components in a single editable codebase:

1. **Task Agent** — solves the target task (benchmark, code generation, data processing, etc.)
2. **Meta Agent** — analyzes task performance history and proposes modifications to the task agent's code (and optionally its own code)

The key insight from the paper: when the meta-level modification procedure is itself editable, the system can improve not just task performance but also the mechanism that generates future improvements — enabling compounding, transferable gains.

## Core Principles

1. **Self-referential modification**

   The meta-agent can modify the task-agent's code AND its own strategy. Both live in the same editable workspace. This enables metacognitive self-improvement: improving how you improve.

2. **Population-based exploration (archive)**

   Don't just keep the best variant — maintain an archive of all successful variants as stepping stones. Parent selection favors high performers with unexplored potential.

3. **Empirical evaluation gates everything**

   No change is accepted without measurement. Every candidate is evaluated against the task benchmark with repeated trials.

4. **Persistent memory and performance tracking**

   The system maintains a structured history of all experiments, hypotheses, and outcomes. Later generations build on earlier insights — no rediscovering dead ends.

5. **Transfer across domains**

   Meta-level improvements (performance tracking, evaluation strategies, hypothesis generation patterns) are domain-agnostic and can be transferred to new tasks.

## Available Scripts

- **`scripts/common.py`** — shared utilities (archive management, metrics, reporting)
- **`scripts/init_session.py`** — initialize a hyperagent session, scaffold the workspace
- **`scripts/run_task.py`** — evaluate a task-agent variant and record metrics
- **`scripts/log_variant.py`** — log evaluated record, decide disposition, update archive and reports
- **`scripts/render_report.py`** — generate HTML report of the full evolutionary history
- **`scripts/select_parent.py`** — select a parent from the archive for the next generation

> **Note:** There is no `generate_variant.py` script — the meta-agent role (hypothesis generation and code modification) is performed by the LLM agent itself, not by a script.

All scripts are non-interactive, expose `--help`, emit structured JSON on stdout, and keep diagnostics on stderr.

## Default Workflow

1. **Initialize** the session after defining the optimization target:

   ```bash
   python3 scripts/init_session.py \
     --goal "Improve prompt accuracy on math benchmark" \
     --metric-name accuracy \
     --unit pct \
     --direction higher \
     --task-command ./task.sh \
     --checks-command ./checks.sh \
     --scope src/agent.py \
     --max-generations 50
   ```

2. **Evaluate the baseline** (generation 0):

   ```bash
   python3 scripts/run_task.py \
     --id gen-000 \
     --hypothesis "Control: unmodified task agent" \
     --change-summary "No modifications" \
     --baseline \
     --output .hyperagent/gen-000.json

   python3 scripts/log_variant.py --input .hyperagent/gen-000.json
   ```

3. **Selection → Modification → Evaluation loop**:

   ```bash
   # Select a parent from the archive
   python3 scripts/select_parent.py --output .hyperagent/parent.json

   # Generate a variant (meta-agent proposes modifications)
   # This is where YOU (the LLM agent) act as the meta-agent:
   # - Read the parent's code and performance history
   # - Hypothesize an improvement
   # - Apply code modifications
   # - Record what you changed and why

   # Evaluate the variant
   python3 scripts/run_task.py \
     --id gen-001 \
     --hypothesis "Add chain-of-thought prompting to improve reasoning" \
     --change-summary "Wrap task prompt in step-by-step reasoning template" \
     --parent gen-000 \
     --output .hyperagent/gen-001.json

   python3 scripts/log_variant.py --input .hyperagent/gen-001.json
   ```

4. **Render reports** at any time:

   ```bash
   python3 scripts/render_report.py
   ```

## Up-Front Q&A

Before starting, gather or confirm:

1. **Objective** — what are we optimizing?
2. **Primary metric** — exact name, unit, direction (lower/higher)
3. **Task command** — the script that runs the task agent and emits `METRIC name=value` lines
4. **Correctness gates** — tests or checks that must pass for a variant to be kept
5. **Scope** — which files can the meta-agent modify?
6. **Meta-scope** — can the meta-agent modify its own strategy? (default: yes)
7. **Generation budget** — max generations before stopping
8. **Minimum improvement threshold** — default 1%

## Workspace Setup

1. Prefer a **dedicated worktree** on a fresh branch:

   ```bash
   git worktree add ../hyperagent-- -b hyperagent/-
   ```

2. Create:
   - `hyperagent.md` — checked in, durable session brief with full evolutionary history
   - `task.sh` — checked in, benchmark runner (emits `METRIC name=value`)
   - `checks.sh` — checked in, correctness gates
   - `.hyperagent/` — local artifact directory, NOT checked in

3. Ensure artifacts stay untracked:

   ```bash
   rg -qxF '.hyperagent/' .git/info/exclude || printf '\n.hyperagent/\n' >> .git/info/exclude
   ```

## The Meta-Agent Role

**You (the LLM) are the meta-agent.** Your job each generation is:

1. **Select parent** — use `scripts/select_parent.py` or choose based on the archive
2. **Analyze** — read the parent's code, performance history, and past experiment outcomes
3. **Hypothesize** — propose a specific, testable modification with a causal theory for why it should help
4. **Modify** — apply code changes to the task agent (and optionally to your own strategy notes in `hyperagent.md`)
5. **Evaluate** — run `scripts/run_task.py` to measure the variant
6. **Log** — use `scripts/log_variant.py` to record the result and update the archive
7. **Reflect** — update `hyperagent.md` with what you learned

### Meta-Level Self-Modification

The meta-agent can improve its own process by updating:
- **Strategy notes** in `hyperagent.md` (hypothesis generation patterns, evaluation heuristics)
- **Memory entries** in `.hyperagent/memory.jsonl` (qualitative insights, correction plans)
- **The task evaluation protocol** (adding secondary metrics, changing trial counts)

These meta-improvements compound across generations and transfer to new tasks.

## Required Files

### `hyperagent.md`

The durable contract and evolutionary history. A fresh agent can resume from this.

```markdown
# Hyperagent: 

## Objective

## Configuration
- Primary metric:
- Unit:
- Direction:
- Minimum improvement: X%
- Task command:
- Correctness gates:
- Generation budget:

## Scope
- Task agent files:
- Meta-agent can self-modify: yes/no

## Archive
`.hyperagent/archive.jsonl`

## Lineage

## Meta-Strategy

## What We've Learned

## Performance Tracking

```

### `task.sh`

Bash script that runs the task agent and emits `METRIC name=value` lines:

```bash
#!/bin/bash
set -euo pipefail
# Run the task agent
python3 src/agent.py --input data/test.json 2>/dev/null
# The agent script should emit: METRIC accuracy=0.85
```

## Archive Structure

The archive (`.hyperagent/archive.jsonl`) stores every variant ever evaluated:

```json
{
  "id": "gen-007",
  "generation": 7,
  "parent_id": "gen-003",
  "timestamp": "2026-03-27T20:00:00Z",
  "hypothesis": "Add few-shot examples to improve pattern recognition",
  "change_summary": "Inserted 3 domain-specific examples into the task prompt",
  "files_touched": ["src/agent.py"],
  "metric_name": "accuracy",
  "direction": "higher",
  "warmup_trials": [0.82, 0.83],
  "measured_trials": [0.85, 0.86, 0.84, 0.85, 0.87],
  "summary": {"median": 0.85, "mean": 0.854, "min": 0.84, "max": 0.87},
  "checks": "passed",
  "disposition": "keep",
  "children_count": 0,
  "meta_modifications": ["Updated strategy notes with few-shot pattern"],
  "reason": "Improved by 3.2% over parent gen-003 (0.824). Checks passed."
}
```

## Parent Selection

Selection probability for a parent is proportional to:
- **Performance score** (higher is better for archive diversity)
- **Inverse of children count** (favor unexplored high-performers)

This balances exploitation (good variants) with exploration (understudied variants).

```bash
python3 scripts/select_parent.py
# Output: {"selected_parent": "gen-003", "score": 0.824, "children": 1, "reason": "High performer with few children"}
```

## Decision Rules

- **`keep`** — variant beats current best by ≥ threshold, checks pass
- **`discard`** — variant is worse, equal, or improvement below threshold
- **`checks_failed`** — metric improved but correctness gates failed
- **`crash`** — variant could not be evaluated

## Plateau Detection

Track improvement velocity. Stop or pivot when:
- 3+ consecutive generations with no improvement
- Hypothesis diversity drops (recycling ideas)
- Improvement velocity < 0.1% per generation over last 5

## Loop Behavior

Run autonomously until:
- Generation budget exhausted
- Plateau detected (3 consecutive non-improvements)
- All promising hypotheses explored
- User interrupts

During the loop:
- One hypothesis per generation
- Record dead ends explicitly
- Keep the worktree clean between variants (revert discarded changes)
- Update `hyperagent.md` after every generation

## Common Pitfalls

### 1. Meta-Agent Overfitting Its Own Strategy
**Symptom:** Meta-strategy becomes over-specialized to early successes
**Fix:** Periodically review and broaden the strategy; try categorically different approaches

### 2. Archive Bloat
**Symptom:** Archive grows large, selection becomes slow
**Fix:** Archive old generations after 50 variants; maintain a compact summary

### 3. Self-Modification Destabilizing the Loop
**Symptom:** Meta-agent modifies evaluation or logging in ways that break the loop
**Fix:** Keep outer-loop scripts (init, run, log, select) immutable. Only modify task code and strategy notes.

### 4. Hypothesis Recycling
**Symptom:** Later generations retry earlier failed ideas
**Fix:** Always read `.hyperagent/memory.jsonl` before proposing. Explicitly check against dead ends.

## Transfer Protocol

To transfer meta-improvements to a new domain:

1. Extract meta-strategy from `hyperagent.md` "What We've Learned" section
2. Copy `.hyperagent/memory.jsonl` as starting knowledge
3. Initialize new session with transferred strategy as initial context
4. The meta-agent starts with accumulated wisdom instead of from scratch

## Report Generation

```bash
python3 scripts/render_report.py
```

Generates `.hyperagent/report.html` with:
- Lineage tree visualization
- Performance over generations
- Best-so-far trend
- Disposition breakdown
- Per-variant trial distributions
- Meta-strategy evolution timeline

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ckorhonen](https://github.com/ckorhonen)
- **Source:** [ckorhonen/claude-skills](https://github.com/ckorhonen/claude-skills)
- **License:** MIT
- **Homepage:** https://cdd.dev/skills

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ckorhonen-claude-skills-hyperagent
- Seller: https://agentstack.voostack.com/s/ckorhonen
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.