self-improving-agents: Instructions file for Claude Code

Self-Improving Agents -- Project Context for Claude Code

Project Overview

This repo demonstrates 4 levels of self-improving code agents, from the simplest possible loop to a competitive adversarial arena. Each level adds one key idea. All demos use real LLM calls (Gemini 2.5 Flash) with multiple task types.

A side-by-side comparison of approaches to autonomous code improvement.

---

Background & History

I built a self-improving review loop for his Graph RAG project (BetterForAll/graph-rag-ui, private) starting February 1, 2026 -- 5 weeks before Karpathy's AutoResearch (March 6-7, 2026) and 6 weeks before Meta's HyperAgents paper (March 17, 2026, arxiv 2603.19461).

My original approach (in graph-rag-ui) introduced several techniques that later appeared independently in those papers:

• Asymmetric context windows -- small focused worker, 1M-token evaluator
• Structured issue taxonomy -- categorized feedback with severity + fix suggestions
• Step-by-step pipeline logging -- queryable JSON logs instead of raw context
• Fully autonomous from a single Cursor instruction -- no human in the loop

---

Repo Structure

tasks/                      Shared task definitions (real files, not strings)
  snake/                      Snake game AI (deterministic: score) + visual player
  support/                    Customer support Q&A (LLM-as-judge: quality)
  email_validation/           Email validation (adversarial: accuracy)
  task_runner.py              Central module: load_task, write_solution, run_solution
  checkpoint.py               Shared checkpoint/resume (atomic writes, all levels)

autoresearch/               Level 1: AutoResearch Loop
  run.py                      The main loop (--task snake|support|email_validation)
  llm.py                      Gemini 2.5 Flash wrapper
  experiment.py               Run experiments with real-time JSON logging

feedback-loop/              Level 2: Feedback Loop
  run.py                      Orchestrates worker + reviewer
  worker.py                   Proposes improvements (small context, focused)
  reviewer.py                 Structured JSON feedback (full context, sees everything)
  llm.py                      Gemini wrapper

hyperagent/                 Level 3: HyperAgent Loop (true code-rewriting)
  run.py                      Generation loop with 3-stage validation
  llm.py                      Gemini wrapper
  seed/                       Original agent code (immutable reference)
    task_agent.py               Seed task agent
    meta_agent.py               Seed meta-agent
  agent_code/                 Live working copies (rewritten by meta-agent)
  generations/                Versioned snapshots (gen_000/, gen_001/, ...)

arena-loop/                 Level 4: Arena Loop (adversarial + self-modifying)
  run.py                      Arena loop with tournament selection
  code_agent.py               Mini-HyperAgent code agents (can mutate propose())
  test_agent.py               Test hardening agents (adversarial inputs)
  arena.py                    Tournament selection + strategy evolution
  llm.py                      Gemini wrapper
  CONCEPT.md                  Full architectural writeup (GAN analogy, roadmap)