# Autoresearch

> Check and run autonomous experiments. Query experiment status, view results dashboards, and execute iterations. TRIGGER when: user asks about experiment status, autoresearch progress, "how's the experiment going", "run another iteration", or invokes "/autoresearch". DO NOT TRIGGER when: user is working on autoresearch agent code itself.

- Skill: `droodotfoo/autoresearch` (Agent Skill)
- Install (CLI): `npx skillmds@latest add droodotfoo/autoresearch`
- Raw SKILL.md: https://api.skillmd.com/api/skills/droodotfoo/autoresearch/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: DROOdotFOO (https://skillmd.com/u/droodotfoo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/droodotfoo/autoresearch

---


# Autoresearch

Domain-agnostic autonomous experiment runner. Optimizes a single metric by
iterating: hypothesis -> code change -> verify -> keep/discard.

## What You Get

- JSONL experiment log with metric history, deltas from baseline, and commit SHAs
- Markdown results dashboard comparing all iterations
- Git branch per experiment with keep/discard via commit/revert

## CLI Usage

```bash
# Initialize an experiment
autoresearch init noir-gates \
  --objective "minimize constraint count" \
  --metric constraints \
  --verify "nargo compile 2>&1 | grep constraints" \
  --direction lower \
  --mutable src/main.nr

# Run a single iteration
autoresearch run "inline witness computation"

# Autonomous loop (Claude generates hypotheses)
autoresearch loop --iterations 10 --model claude-sonnet-4-6

# View results
autoresearch dashboard
autoresearch status
```

## MCP Server

```bash
autoresearch serve
```

### Configure MCP

Add to `~/.mcp.json`:

```json
{
  "mcpServers": {
    "autoresearch": {
      "command": "autoresearch",
      "args": ["serve"]
    }
  }
}
```

### MCP Tools

| Tool | Description |
|------|-------------|
| `autoresearch_status` | Current experiment status (name, metric, runs, best) |
| `autoresearch_dashboard` | Full results table as markdown |
| `autoresearch_run` | Execute a single experiment iteration |

## Install

```bash
cd agents/autoresearch
pip install -e .
```

Requires `ANTHROPIC_API_KEY` for the autonomous loop (hypothesis generation).