cursor-autoresearch

Autonomous experiment loop for Cursor: try an idea, measure it, keep what works, discard what does not, and continue iterating.

This plugin ports the original pi-autoresearch workflow to Cursor plugins:

• MCP tools: init_experiment, run_experiment, log_experiment
• Skills: autoresearch-create, autoresearch-finalize
• Command: /autoresearch
• Live dashboard: http://127.0.0.1:7331 (served by the MCP server)

Plugin structure

.
├── .cursor-plugin/plugin.json
├── commands/autoresearch.md
├── skills/
│   ├── autoresearch-create/SKILL.md
│   └── autoresearch-finalize/
│       ├── SKILL.md
│       └── finalize.sh
├── rules/autoresearch-guardrails.mdc
├── mcp.json
├── src/server.ts
├── dist/server.js
└── dashboard/
    ├── src/...
    └── dist/...

How it works

MCP tools

Tool	Purpose
init_experiment	Initialize or re-initialize a segment with metric metadata
run_experiment	Execute benchmark command, parse METRIC lines, run optional checks
log_experiment	Persist run to autoresearch.jsonl, auto-commit keep, auto-revert discard/crash/checks_failed

Durable session files

autoresearch persists progress in the active work directory:

• autoresearch.jsonl - append-only run history
• autoresearch.md - high-level objective and experiment memory
• autoresearch.sh - benchmark script with structured metric output
• autoresearch.checks.sh - optional correctness checks
• autoresearch.ideas.md - optional backlog of deferred ideas
• autoresearch.config.json - optional config (maxIterations, workingDir)

Dashboard

The MCP server also hosts a local web dashboard on 127.0.0.1:7331.

• GET /api/state returns current parsed state
• GET /api/stream provides SSE updates
• React dashboard UI is served from dashboard/dist

Usage

Start or resume

Use:

/autoresearch optimize unit test runtime while preserving correctness

The command resumes from autoresearch.md if present, or routes to the setup skill for new sessions.

Stop loop

/autoresearch off

Stops active loop behavior without deleting files.

Clear session log

/autoresearch clear

Deletes autoresearch.jsonl from effective workDir.

Finalize into clean branches

/skill:autoresearch-finalize

Groups kept experiments and runs skills/autoresearch-finalize/finalize.sh to create independent review branches.

Local development

Install dependencies

npm install

Build artifacts

npm run build

This regenerates:

• dist/server.js
• dashboard/dist/*

Test finalize script

npm run test:finalize

Local plugin loading in Cursor

Use a local plugin symlink:

ln -s /path/to/cursor-autoresearch ~/.cursor/plugins/local/cursor-autoresearch

Then reload Cursor window.

Known constraints (v1)

• Dashboard is local-only (127.0.0.1:7331)
• Fixed dashboard port: 7331
• No Cursor hooks are used for auto-resume; loop continuity is enforced by command/skill instructions

License

MIT