Auto Research

Docs • Wiki • Commands • Runtime • Self-Improvement

Autonomous recursive self-improvement engine for OpenCode.

┌──────────────────────────────────────────────┐
│  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. Unlike simple task runners, it maintains a standing 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[Standing 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

Install the CLI globally if you want Auto Research available long-term on your PATH:

npm install -g opencode-autoresearch
opencode-autoresearch doctor

For a one-time install without keeping a global CLI, use bunx instead:

bunx opencode-autoresearch install
bunx opencode-autoresearch doctor

Then start the setup wizard inside OpenCode:

/autoresearch

Quick Start

# 1. Install the CLI globally
npm install -g opencode-autoresearch

# 2. Verify installation
opencode-autoship doctor

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

# 4. Start Auto Research in OpenCode
/autoresearch

Runtime Surfaces

Commands

CLI Commands

Architecture

flowchart LR
    A[OpenCode /autoresearch] --> B[CLI]
    B --> C[Run Manager]
    C --> D[State JSON]
    C --> E[Results TSV]
    C --> F[Subagent Pool]
    F --> G[Orchestrator]
    F --> H[Scout]
    F --> I[Analyst]
    F --> J[Verifier]
    F --> K[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:

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/           # 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
hooks/                         # Shell hooks for session lifecycle
docs/                          # Install and architecture docs
wiki/                          # GitHub wiki pages
.autoresearch/                 # Runtime state directory
.opencode-plugin/              # Plugin manifest

Notes

• This is an OpenCode-only package. No Claude or Codex runtime is supported.
• 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.