hyperagent

Runs an evolutionary loop where a meta-agent modifies task-agent code to optimize measurable metrics.

1|Updated May 6, 2026
One-click install
npx skills add https://github.com/surfingalien/FinSurfing --skill hyperagent-surfingalien
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: hyperagent
Source: https://github.com/surfingalien/FinSurfing/tree/main/.claude/skills/hyperagent
Command: npx skills add https://github.com/surfingalien/FinSurfing --skill hyperagent-surfingalien

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Iteratively improving code, prompts, or scripts against a measurable objective is slow and unstructured when done by hand. This Skill automates a self-referential improvement loop: a meta-agent proposes code modifications, evaluates each variant against a benchmark, and keeps only changes that measurably improve the target metric. ## Core Features & Use Cases - Evolutionary variant archive: Every evaluated variant is logged with hypothesis, metrics, and disposition (keep/discard/crash), with parent selection weighted by performance and exploration. - Empirical evaluation gates: Warmup and measured trials parse METRIC lines from task scripts, with optional correctness checks that must pass before a variant is kept. - Reporting and plateau detection: Generates CSV and HTML reports with lineage trees, trend charts, and automatic plateau warnings. - Use Case: Optimize a text summarizer's word-overlap score — the baseline scores 0.33, the meta-agent proposes keyword extraction, and the kept variant reaches 0.94, a 183% improvement tracked in the archive. ## Quick Start Ask the agent to run hyperagent on a script or prompt you want improved, specifying the metric to optimize and the command that benchmarks it.

Frequently Asked Questions about hyperagent

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I set up a hyperagent optimization session?

Run scripts/init_session.py with a goal, metric name, unit, direction, and a task command that emits METRIC lines. This scaffolds hyperagent.md and a .hyperagent/ artifacts directory, then you evaluate a baseline and start the improvement loop.

How does the meta-agent generate code improvements?

The LLM itself acts as the meta-agent: it reads the parent's code and performance history, hypothesizes a modification with a causal theory, applies the change, and evaluates it. There is no generate_variant script; hypothesis generation is done by the agent.

What format must my task script output for metrics?

Task scripts must print lines starting with METRIC followed by key=value pairs or a JSON object, such as METRIC score=0.85. Values must parse as floats, and other stdout output is ignored.

Does hyperagent require external Python packages?

No, all bundled scripts use only the Python standard library. The only requirements are python3 and git, making it runnable in minimal environments without pip installs.

What happens when optimization stops improving?

The system detects plateaus after a configurable number of consecutive non-improvements (default 3) and tracks improvement velocity. select_parent.py emits a warning suggesting you pivot strategy or stop the loop.

When should I not use this evolutionary approach?

Avoid it when the objective cannot be expressed as a measurable metric emitted by a command, or when a single evaluation is too expensive to repeat across warmups and trials. It also requires a git-style workspace to track changes safely.