Auto Research

Docs • Wiki • Commands • Runtime • Self-Improvement

Multi-runtime autonomous recursive self-improvement engine.

┌──────────────────────────────────────────────┐
│  ITERATION MODEL        Subagent-first        │
│  ORCHESTRATION          Standing pool         │
│  VERIFICATION           Mechanical metrics    │
│  PERSISTENCE            State + Memory        │
│  META-LEARNING          Strategy adaptation   │
└──────────────────────────────────────────────┘

What It Does

Auto Research is a subagent-first autonomous iteration engine that runs structured improve-verify loops inside OpenCode or Hermes Agent. Unlike simple task runners, it maintains a pool of specialized subagents, persists learnings across iterations, and can run recursive self-improvement loops on its own codebase.

• Plans experiments from a measurable goal
• Modifies one focused change per iteration
• Verifies mechanically — never on intuition alone
• Keeps or discards based on strict metric improvement
• Learns from patterns across iterations
• Repeats until the stop condition is met

The Core Loop

flowchart LR
    A[Plan] --> B[Modify]
    B --> C[Verify]
    C --> D{Keep?}
    D -->|yes| E[Learn]
    D -->|no| B
    E --> F[Memory]
    F --> A

flowchart TD
    A[Goal + Metric + Verify] --> B[Baseline]
    B --> C[Pool Init]
    C --> D[Iteration N]
    D --> E[Subagent Context]
    E --> F[Focused Change]
    F --> G[Mechanical Verify]
    G --> H{Strict Improvement?}
    H -->|yes| I[Keep + Record]
    H -->|no| J[Discard + Reset]
    I --> K{Stop Condition?}
    J --> K
    K -->|no| D
    K -->|yes| L[Report + Memory]

The Self-Improvement Loop

Auto Research can run on itself. The recursive loop adds a meta-orchestrator that:

flowchart TD
    A[Meta-Goal: Improve AutoResearch] --> B[Run Child Loop]
    B --> C[Measure: Tests pass? Docs improved?]
    C --> D{Child Success?}
    D -->|yes| E[Update Memory + Strategy]
    D -->|no| F[Adapt Approach]
    E --> G[Persist Learnings]
    F --> B
    G --> H[Meta-Report]
    H --> I{Meta-Stop?}
    I -->|no| B
    I -->|yes| J[Archive Run]

See skills/autoresearch/references/self-improve-loop.md for the full recursive loop specification.

Installation

OpenCode

For OpenCode, paste this one-line install prompt into your agent. This URL follows the latest main instructions:

Fetch and follow instructions from https://raw.githubusercontent.com/Maleick/AutoResearch/refs/heads/main/INSTALL.md

Recommended plugin install in opencode.json:

{
  "plugin": ["opencode-autoresearch@latest"]
}

Restart OpenCode, then run the setup wizard:

/autoresearch

Hermes Agent

# 1. Clone AutoResearch
git clone https://github.com/Maleick/AutoResearch.git
cd AutoResearch
npm install

# 2. Install the Hermes skill
mkdir -p ~/.hermes/skills/software-development/autoresearch
cp skills/hermes/autoresearch-prompt.md ~/.hermes/skills/software-development/autoresearch/SKILL.md
cp skills/hermes/INTEGRATION.md ~/.hermes/skills/software-development/autoresearch/REFERENCES.md

# 3. Create a cronjob
hermes cron create \
  --name "autoresearch-loop" \
  --workdir ~/projects/AutoResearch \
  --skill autoresearch-hermes \
  "every 15m" \
  "Run AutoResearch iteration loop. Detect phase from .autoresearch/state.json and execute one phase. Approved verify command: \"npm run test:coverage\". Approved guard command: \"npm run typecheck\"."

See skills/hermes/README.md for full Hermes setup, troubleshooting, and command mapping.

npm CLI (both runtimes)

Global install path:

npm install -g opencode-autoresearch
autoresearch doctor
autoresearch --version

One-time package runner path:

npx opencode-autoresearch doctor

See INSTALL.md for prerequisites, verification, updating, and troubleshooting.

Quick Start

OpenCode

# 1. Add the plugin to opencode.json
# { "plugin": ["opencode-autoresearch@latest"] }

# 2. Restart OpenCode

# 3. Navigate to your project
cd ~/Projects/my-project

# 4. Start Auto Research in OpenCode
/autoresearch

Hermes Agent

# 1. Ensure the skill is installed (see Installation above)

# 2. Initialize state from a trusted shell before enabling unattended cron
autoresearch init \
  --goal "Improve test coverage" \
  --metric "coverage_pct" \
  --direction "higher" \
  --verify "npm run test:coverage" \
  --guard "npm run typecheck" \
  --iterations 20 \
  --mode background

# 3. Start the cronjob
hermes cron resume autoresearch-loop

# 4. Check progress
cat .autoresearch/state.json | jq .

Runtime Surfaces

Commands

CLI Commands

Architecture

flowchart LR
    A[OpenCode /autoresearch] --> B[CLI]
    H[Hermes Cronjob] --> B
    B --> C[Run Manager]
    C --> D[State JSON]
    C --> E[Results TSV]
    C --> F[Subagent Pool]
    F --> G[Orchestrator]
    F --> I[Scout]
    F --> J[Analyst]
    F --> K[Verifier]
    F --> L[Synthesizer]

Runtime Artifacts

Self-Improvement Mode

Run Auto Research on its own codebase:

# Initialize a recursive self-improvement run
autoresearch init \
  --goal "Improve test coverage and documentation" \
  --metric "coverage_pct" \
  --direction "higher" \
  --verify "npm run test:coverage" \
  --guard "npm run typecheck" \
  --mode "background" \
  --iterations "20"

# Check status
autoresearch status

# Resume if stopped
autoresearch resume

The self-improvement loop:

1. Baselines current state (tests, docs, metrics)
2. Dispatches subagents to identify improvement opportunities
3. Makes one focused change per iteration
4. Verifies mechanically (tests, typechecks, lint)
5. Keeps strict improvements, discards regressions
6. Records patterns to autoresearch-memory.md
7. Adapts strategy when repeated discards occur
8. Continues until iteration cap or goal met

Subagent Pool

The standing pool provides specialized roles reused across iterations:

Runtime Comparison

Development

npm run typecheck   # TypeScript strict checks
npm run build       # Compile TypeScript to dist/
npm run test        # Run test suite
npm pack --dry-run  # Preview shipped package contents

Repository Layout

src/                           # TypeScript source (runtime helpers, CLI, subagent pool)
dist/                          # Compiled JavaScript output
commands/                      # OpenCode command surfaces
skills/autoresearch/           # OpenCode skill bundle with references
  references/                  # Workflow and runtime references
    core-principles.md         # Loop discipline
    loop-workflow.md           # Main iteration workflow
    subagent-orchestration.md  # Pool management
    state-management.md        # State semantics
    self-improve-loop.md       # Recursive self-improvement
skills/hermes/                 # Hermes Agent skill bundle
  README.md                    # Hermes setup and usage
  INTEGRATION.md               # Architecture and command mapping
  autoresearch-prompt.md       # Cron prompt template
hooks/                         # Shell hooks for session lifecycle
docs/                          # Install and architecture docs
wiki/                          # GitHub wiki pages
.autoresearch/                 # Runtime state directory
.opencode-plugin/              # Plugin manifest

Notes

• OpenCode users: install via opencode.json plugin array or npm install -g opencode-autoresearch.
• Hermes Agent users: install via skill files in skills/hermes/ and create a cronjob.
• The CLI uses Node.js ESM modules.
• Self-improvement loops require --mode background for long-running unattended operation.
• Memory files (autoresearch-memory.md) are portable across runs and repositories.

License

MIT — See LICENSE for details.