Skip to content
Back to search

openclaw-autoresearch

Autonomous experiment loop plugin for OpenClaw

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gianfrancopiana--openclaw-autoresearch/badge.svg)](/listings/gianfrancopiana--openclaw-autoresearch)

HTML

<a href="/listings/gianfrancopiana--openclaw-autoresearch"><img src="/api/listings/gianfrancopiana--openclaw-autoresearch/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires OpenClaw `2026.4.25` or newer. Needs bash, git, and a git repo.

Use OpenClaw's plugin installer:

openclaw plugins install @gianfrancopiana/openclaw-autoresearch

If you're running from a local OpenClaw checkout, use:

pnpm openclaw plugins install @gianfrancopiana/openclaw-autoresearch

For local plugin development, link your working copy instead of copying files:

openclaw plugins install --link /absolute/path/to/openclaw-autoresearch
# or from a local OpenClaw checkout:
# pnpm openclaw plugins install --link /absolute/path/to/openclaw-autoresearch

For a packaged local install, build the tarball and install that artifact:

npm install
npm pack
openclaw plugins install ./gianfrancopiana-openclaw-autoresearch-<version>.tgz

The install command records the plugin, enables it, and makes it available after restart. OpenClaw reads the package metadata, loads the compiled runtime entry [`dist/index.js`](dist/index.js), and finds the manifest in [`openclaw.plugin.json`](openclaw.plugin.json).

Verify:

- skill: `autoresearch-create` - tools: `init_experiment`, `run_experiment`, `log_experiment`, `autoresearch_status` - command: `/autoresearch` (recommended) - direct skill fallback: `/skill autoresearch-create`

Prefer the explicit `/autoresearch` command surface in OpenClaw. The auto-generated native skill alias `/autoresearch_create` may not trigger reliably on some hosts, so use `/skill autoresearch-create` if you need to invoke the skill directly.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 141 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # openclaw-autoresearch
  2. Autonomous experiment loop for any optimization target.
  3. Faithful OpenClaw port of [`davebcn87/pi-autoresearch`](https://github.com/davebcn87/pi-autoresearch), including upstream statistical confidence scoring.
  4. ## How it works
  5. The agent runs a loop: edit code, run a benchmark, measure the result, keep or discard. Each iteration is logged. The loop runs autonomously until interrupted.
  6. Three tools drive the loop:
  7. | Tool | What it does |
  8. |---|---|
  9. | `init_experiment` | Configures the session: name, primary metric, unit, direction (lower/higher). Once runs exist, starting a new segment requires `reset: true`, and the prior segment's best result is carried forward into checkpoint context. |
  10. | `run_experiment` | Executes a shell command, times it, captures stdout/stderr, parses `METRIC name=number` lines, and opens a pending experiment window that must be logged before another run can start. |
  11. | `log_experiment` | Records the pending run. The first logged run in a segment is tagged as the baseline automatically. `keep` auto-commits to git. `discard`/`crash` log without committing, and `discard` now requires an `idea` note that is appended to `autoresearch.ideas.md`. If the prior `run_experiment` captured the primary metric, `log_experiment` can infer `commit` and `metric` automatically. After 3+ runs in a segment, it also reports a confidence score for the best improvement versus noise. |
  12. In OpenClaw sessions, the plugin uses the host-provided `workspaceDir` as the normal repo root. Each tool also accepts an optional `cwd` so callers can explicitly target a nested or non-session repo when needed.
  13. All state lives in six repo-root files:
  14. | File | Purpose |
  15. |---|---|
  16. | `autoresearch.md` | Session doc. The plugin keeps the Metrics, How to Run, What's Been Tried, and Plugin Checkpoint sections synchronized so resumes are less agent-dependent. |
  17. | `autoresearch.sh` | Benchmark script. Outputs `METRIC name=number` lines. |
  18. | `autoresearch.jsonl` | Structured log: config headers + experiment entries (metric, status, timestamp, segment, commit hash). |
  19. | `autoresearch.ideas.md` | Backlog of promising ideas not yet tried. Optional. |
  20. | `autoresearch.checkpoint.json` | Plugin-managed checkpoint: latest logged state, recent runs, and any pending unlogged run. |
  21. | `autoresearch.lock` | Session lock with PID + timestamp so another agent can detect an active or stale loop before forking a second session. |
  22. The design is file-first: any agent can pick up the repo-root files and continue the loop without prior context.
  23. ## Install
  24. Requires OpenClaw `2026.4.25` or newer.
  25. Needs bash, git, and a git repo.
  26. Use OpenClaw's plugin installer:
  27. ```bash
  28. openclaw plugins install @gianfrancopiana/openclaw-autoresearch
  29. ```
  30. If you're running from a local OpenClaw checkout, use:
  31. ```bash
  32. pnpm openclaw plugins install @gianfrancopiana/openclaw-autoresearch
  33. ```
  34. For local plugin development, link your working copy instead of copying files:
  35. ```bash
  36. openclaw plugins install --link /absolute/path/to/openclaw-autoresearch
  37. # or from a local OpenClaw checkout:
  38. # pnpm openclaw plugins install --link /absolute/path/to/openclaw-autoresearch
  39. ```
  40. For a packaged local install, build the tarball and install that artifact:
  41. ```bash
  42. npm install
  43. npm pack
  44. openclaw plugins install ./gianfrancopiana-openclaw-autoresearch-<version>.tgz
  45. ```
  46. The install command records the plugin, enables it, and makes it available
  47. after restart. OpenClaw reads the package metadata, loads the compiled runtime
  48. entry [`dist/index.js`](dist/index.js), and finds the manifest in
  49. [`openclaw.plugin.json`](openclaw.plugin.json).
  50. Verify:
  51. - skill: `autoresearch-create`
  52. - tools: `init_experiment`, `run_experiment`, `log_experiment`, `autoresearch_status`
  53. - command: `/autoresearch` (recommended)
  54. - direct skill fallback: `/skill autoresearch-create`
  55. Prefer the explicit `/autoresearch` command surface in OpenClaw. The auto-generated native skill alias `/autoresearch_create` may not trigger reliably on some hosts, so use `/skill autoresearch-create` if you need to invoke the skill directly.
  56. ## Workflow Guarantees
  57. - `run_experiment` refuses to start a second run until the previous one is logged.
  58. - `run_experiment` parses `METRIC name=number` lines and stores a pending run so `log_experiment` can default from the actual benchmark output.
  59. - `init_experiment` refuses to reset a live history unless `reset: true` is passed explicitly.
  60. - The first `log_experiment` in a segment is tagged as the baseline automatically, even if it is later discarded.
  61. - `discard` logs must include an `idea` note, and that note is appended to `autoresearch.ideas.md`.
  62. - During active autoresearch mode, raw benchmark execution through OpenClaw `exec`/`bash` is blocked. Use `run_experiment` instead.
  63. - `autoresearch_status` warns when a pending run is unlogged, when the canonical branch has drifted, when a stale/live lock exists, or when git history has moved ahead of the last logged experiment. On `autoresearch/*` branches it explicitly warns not to push unlogged commits.
  64. - After 3+ positive-metric runs in a segment, `log_experiment`, `autoresearch_status`, and the synced session doc report a MAD-based confidence score so the agent can distinguish likely wins from noise.
  65. - The plugin updates `autoresearch.checkpoint.json`, `autoresearch.lock`, and the plugin-managed sections in `autoresearch.md` after init, run, and log transitions.
  66. ## Use
  67. In the repo you want to optimize:
  68. 1. Load the plugin.
  69. 2. Run `/autoresearch` or `/autoresearch setup <goal>`.
  70. 3. Send a normal message with the goal, command, metric (+ direction), files in scope, and constraints.
  71. 4. If you need the raw skill invocation, use `/skill autoresearch-create`.
  72. 5. The agent writes `autoresearch.md` and `autoresearch.sh`, captures or reuses the canonical `autoresearch/*` branch, runs a baseline with `run_experiment`, then records it with `log_experiment`.
  73. 6. Use `/autoresearch` or `/autoresearch status` to re-prime context on a later turn.
  74. To resume an existing session, a new agent reads the repo-root files and continues from where the last one stopped.
  75. ### User steers
  76. Messages sent while an experiment is running are queued and surfaced after the next `log_experiment`. The agent finishes the current experiment before incorporating the steer.
  77. ### Ideas backlog
  78. When the agent discovers promising but complex ideas mid-loop, it appends them to `autoresearch.ideas.md`. Discarded experiments now require an `idea` note, so failed paths leave behind concrete follow-up suggestions instead of disappearing. On resume, the agent reads the backlog, prunes stale entries, and uses the remaining ideas as experiment paths.
  79. ## Upstream reference
  80. This port preserves upstream semantics, names, and file contracts while adapting presentation to OpenClaw. There is no Pi-style widget, dashboard, or editor shortcut layer. Remaining differences are tracked in [`docs/non-parity.md`](docs/non-parity.md).
  81. - upstream repo: `https://github.com/davebcn87/pi-autoresearch`
  82. - pinned upstream commit: `2227029fa5712944a36938b5fe59f709cb30ed22` (`2227029f`)
  83. - later upstream parity cherry-pick: confidence scoring from `cf1bbf03debca8f3fb2cca2c3e799b9e23320f87` (`cf1bbf0`, March 19, 2026)
  84. ## Validation
  85. ```bash
  86. npm install --include=dev
  87. npm run check:release-metadata
  88. npm run typecheck
  89. npm test
  90. npm run validate
  91. npm run release:verify
  92. npm run smoke:openclaw-host -- /absolute/path/to/openclaw
  93. npm run smoke:registry-openclaw-host -- <published-version> /absolute/path/to/openclaw
  94. ```
  95. Release instructions, including `npm run release:prepare -- <version> --host /absolute/path/to/openclaw` and GitHub Actions trusted publishing with npm provenance, live in [`RELEASING.md`](RELEASING.md).
  96. The local test shim supports typechecking and tests without a full OpenClaw host checkout. Runtime behavior depends on a real OpenClaw host, so run the host smoke against a current checkout before release.
  97. ## License
  98. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.