Cursor Autoresearch
No description available
Ask AI about Cursor Autoresearch
Powered by Claude · Grounded in docs
I know everything about Cursor Autoresearch. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
◈ Cursor Autoresearch
Autoresearch is a single workflow for Cursor and VS Code: MCP tools drive a measurable optimization loop, results append to autoresearch.jsonl, you can add an optional browser dashboard and packaged agent skills (autoresearch-create, autoresearch-finalize).
| Field | Details |
|---|---|
| Open-source project name | Cursor Autoresearch |
| GitHub repo | cursor-autoresearch (easy to discover and share) |
| Product / UI name | Autoresearch (MCP server and marketplace extension) |
Port of pi-autoresearch for editors that use pi upstream in the terminal. Same idea as karpathy/autoresearch: try a change, benchmark, keep wins, revert losses, repeat — for any primary metric (test time, bundle size, build time, Lighthouse, and more).

Contents
- Quick start (your own project)
- What you get
- How it works
- Cursor rule
- Add rules and skills to your project
- Install for Cursor
- Install for VS Code
- Skills
- Extension
- Example: faster tests
- Configuration
- Technology stack
- npm packages
- Requirements
- Build (from a clone)
- Develop this repository
Quick start (your own project)
Do this in the repo you want to optimize — open that folder as your workspace. The MCP server must see that folder via AUTORESEARCH_CWD (usually ${workspaceFolder}).
Prerequisites: Node.js 18+ to run the published MCP via npx (same floor as @modelcontextprotocol/sdk). Use Node.js 22+ only if you are developing this repository (pnpm install / CI — see Requirements). One-shot bootstrap also needs git on your PATH.
Cursor
-
Add the MCP server (pick one):
- Automated: run One-shot bootstrap — clones this repo, merges
~/.cursor/mcp.json, and symlinks skills under~/.agents/skills/. - Manual: merge the JSON from the MCP config snippet into your user
~/.cursor/mcp.json(or use Cursor’s MCP UI).AUTORESEARCH_CWDmust be${workspaceFolder}so tools run in the project you opened.
- Automated: run One-shot bootstrap — clones this repo, merges
-
Restart Cursor so MCP picks up the change.
-
Install the rule and workspace skills into that project (from the project root):
curl -fsSL https://raw.githubusercontent.com/ergenekonyigit/cursor-autoresearch/main/scripts/add-to-your-project.sh | bash -s -- --allMore options (target dir, skills-only, symlinks): Add rules and skills to your project.
-
Install the extension (recommended) for the status bar, dashboard, and results webview: Extension (Visual Studio Marketplace or
.vsix).
Then add autoresearch.md, autoresearch.sh, and drive the loop with the MCP tools — see Example: faster tests and How it works.
VS Code (GitHub Copilot + MCP)
Use the servers block in Install for VS Code. Reload the window after editing mcp.json. Steps 3–4 above still apply if you want .cursor/rules and .cursor/skills in the repo; VS Code does not load ~/.agents/skills/ automatically.
What you get
- Closed optimization loop in your repo: one primary metric (e.g. wall-clock seconds, lower is better), agent edits code, a fixed benchmark script measures outcomes, every run is recorded so sessions can resume.
- Three MCP tools:
init_experiment→run_experiment→log_experiment(see How it works). - Session artifacts:
autoresearch.md(goal, scope, what you tried),autoresearch.sh(repeatable benchmark; stdout must emitMETRIC name=value), optionalautoresearch.config.json. - Monorepo packages: shared engine in
packages/core,packages/mcp-server(stdio MCP),packages/vscode-extension(status bar, commands, local HTTP + SSE dashboard, results webview). - Skills under
skills/for starting and finalizing autoresearch sessions (Cursor-oriented paths documented below).
How it works
init_experiment— Name the run and set metric direction (higher/lower is better).run_experiment— Runs your benchmark (commonly./autoresearch.sh). ParsesMETRIC name=valuefrom stdout.log_experiment— Appends a line toautoresearch.jsonl. Outcomes likekeepcan auto-commit;discard,crash, or failed checks can revert code while keeping autoresearch files.
Typical workspace layout
| File / convention | Role |
|---|---|
autoresearch.md | Goal, scope, “what we tried” — keep it current. |
autoresearch.sh | Repeatable benchmark; metric names must match init_experiment. |
autoresearch.config.json | Optional — e.g. maxIterations, workingDir. |
| Branch name | Often autoresearch/<goal>-<date>. |
[!NOTE]
AUTORESEARCH_CWDmust point at the project you optimize (whereautoresearch.jsonlandautoresearch.mdlive), usually${workspaceFolder}— not necessarily the clone of this repo.
Cursor rule
.cursor/rules/autoresearch-active.mdc nudges the agent to use MCP tools and keep autoresearch.md in sync when autoresearch.jsonl exists. Install it with step 3 of Quick start (your own project), or see Add rules and skills to your project for flags and advanced options.
Add rules and skills to your project
This is Quick start (your own project) step 3 for Cursor (and optional workspace files in VS Code). Run these from the root of the project you want to equip (the folder you open in the editor). The script downloads files from GitHub by default; no clone of this repository is required.
Rules + skills (default)
curl -fsSL https://raw.githubusercontent.com/ergenekonyigit/cursor-autoresearch/main/scripts/add-to-your-project.sh | bash -s -- --all
Rules only
curl -fsSL https://raw.githubusercontent.com/ergenekonyigit/cursor-autoresearch/main/scripts/add-to-your-project.sh | bash -s -- --rules
Skills only (installs under .cursor/skills/ in that project)
curl -fsSL https://raw.githubusercontent.com/ergenekonyigit/cursor-autoresearch/main/scripts/add-to-your-project.sh | bash -s -- --skills
Install into a specific directory (without changing your shell’s current directory)
TARGET="/path/to/your/project" curl -fsSL https://raw.githubusercontent.com/ergenekonyigit/cursor-autoresearch/main/scripts/add-to-your-project.sh | bash -s -- --all
Use a local clone instead of curl (copy files) — set AUTORESEARCH_ROOT to your cursor-autoresearch checkout:
AUTORESEARCH_ROOT="/path/to/cursor-autoresearch" curl -fsSL https://raw.githubusercontent.com/ergenekonyigit/cursor-autoresearch/main/scripts/add-to-your-project.sh | bash -s -- --all
Symlink from a local clone (updates when you pull the upstream repo; requires AUTORESEARCH_ROOT):
AUTORESEARCH_ROOT="/path/to/cursor-autoresearch" curl -fsSL https://raw.githubusercontent.com/ergenekonyigit/cursor-autoresearch/main/scripts/add-to-your-project.sh | bash -s -- --all --symlink
If you already cloned this repository, you can also run the script from disk:
/path/to/cursor-autoresearch/scripts/add-to-your-project.sh /path/to/your/project --all
From this repository’s root, pnpm add-to-project runs the same script (pass a target path and flags after --):
pnpm add-to-project -- /path/to/your/project --all
| Variable / flag | Meaning |
|---|---|
TARGET | Project directory to write into (default: current working directory). |
REF | Git branch or tag on GitHub (default: main). |
REPO_SLUG | owner/repo used for raw.githubusercontent.com (default: ergenekonyigit/cursor-autoresearch). |
AUTORESEARCH_ROOT | Local checkout of this repo; when set, files are read from disk (copy) instead of downloaded. |
--symlink | Symlink rule and skill folders into AUTORESEARCH_ROOT instead of copying (live updates on git pull). |
Install for Cursor
Details for Quick start (your own project) step 1 when you use Cursor.
One-shot bootstrap
Clones to ~/.local/share/cursor-autoresearch by default, merges ~/.cursor/mcp.json, symlinks skills:
curl -fsSL https://raw.githubusercontent.com/ergenekonyigit/cursor-autoresearch/main/scripts/bootstrap.sh | bash
| Variable | Default | Meaning |
|---|---|---|
INSTALL_DIR | $HOME/.local/share/cursor-autoresearch | Clone path |
REPO_URL | https://github.com/ergenekonyigit/cursor-autoresearch.git | Git remote |
SKIP_MCP | — | Set to 1 to skip writing ~/.cursor/mcp.json |
SKIP_SKILLS | — | Set to 1 to skip symlinks under ~/.agents/skills/ |
Already cloned this repo?
pnpm install:cursor # same as ./scripts/install.sh
Restart Cursor so MCP reloads.
~/.cursor/mcp.json
{
"mcpServers": {
"autoresearch": {
"command": "npx",
"args": ["-y", "@ergenekonyigit/cursor-autoresearch-mcp-server"],
"env": {
"AUTORESEARCH_CWD": "${workspaceFolder}"
}
}
}
}
References: Cursor MCP, Plugins / MCP.
Install for VS Code
Use this when you work in VS Code with GitHub Copilot and MCP servers. This is the MCP part of Quick start (your own project) for VS Code.
- If you use
npxin the config below, no local clone is required. If you prefer a local path-based setup, complete Build (from a clone). - Add
mcp.json:- Workspace:
.vscode/mcp.jsonin the folder you open, or - User: Command Palette → MCP: Open User Configuration.
- Workspace:
- Use the
serversshape (notmcpServers):
{
"servers": {
"autoresearch": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@ergenekonyigit/cursor-autoresearch-mcp-server"],
"env": {
"AUTORESEARCH_CWD": "${workspaceFolder}"
}
}
}
}
- Reload the window (Developer: Reload Window) or restart VS Code.
Reference: MCP configuration (VS Code).
[!TIP] Bootstrap /
pnpm install:cursoronly updates~/.cursor/mcp.json. For VS Code–only setups, run the bootstrap script withSKIP_MCP=1if you want clone + build + skills without changing Cursor’s config, then add.vscode/mcp.jsonor usermcp.jsonas above.
Skills path: Files under ~/.agents/skills/ are aimed at Cursor-style loading. VS Code does not use that path automatically — use Copilot instructions, prompts, or adapt ideas from skills/.
Rules: .cursor/rules/ apply in Cursor; for VS Code, copy the intent into project or user instructions if you want similar behavior.
Skills
If you did not use bootstrap or pnpm install:cursor:
ln -sfn "$PWD/skills/autoresearch-create" ~/.agents/skills/autoresearch-create
ln -sfn "$PWD/skills/autoresearch-finalize" ~/.agents/skills/autoresearch-finalize
You can also symlink into .cursor/skills/ (e.g. autoresearch-create → ../../skills/autoresearch-create) for workspace-only discovery. Nothing in the build requires these symlinks. The Add rules and skills to your project script can populate .cursor/skills/ for a single workspace without touching ~/.agents/skills/.
Extension
Optional but recommended after Quick start (your own project) step 4: status bar controls, local dashboard, and the results webview.
Install from Visual Studio Marketplace:
Or build a .vsix and install via Extensions: Install from VSIX…
pnpm package:extension
Shortcuts: Ctrl+Alt+X (expanded status), Ctrl+Alt+Shift+X (results webview).
Example: faster tests (e.g. Vitest)
Prompt idea: Reduce how long npm run test takes — set up autoresearch and speed it up. (Use pnpm test, pnpm vitest run, etc., to match your repo.)
- Create a branch such as
autoresearch/vitest-speed-<date>. - Add
autoresearch.mdandautoresearch.sh, commit so the next session can resume. - MCP:
init_experiment(e.g. metricvitest_seconds, lower is better) → baselinerun_experiment+log_experiment. - Iterate: change config →
run_experiment→log_experimentwith keep / discard until done ormaxIterationshits.
Minimal benchmark (adjust the inner command; metric names must match init_experiment):
#!/usr/bin/env bash
set -euo pipefail
SECS="$(/usr/bin/time -p npm run test 2>&1 | awk '/^real/ {print $2}')"
echo "METRIC vitest_seconds=$SECS"
If you use pnpm exec vitest run, substitute accordingly. For very fast suites, averaging or median inside the script can stabilize the metric.
Configuration
Place autoresearch.config.json next to autoresearch.jsonl — under the directory AUTORESEARCH_CWD points at (usually ${workspaceFolder}), i.e. your optimized project, not the cursor-autoresearch clone.
| Key | Purpose |
|---|---|
maxIterations | Cap on counted runs in the current segment; start a new segment with init_experiment after that. Omit for no cap. |
workingDir | Run benchmarks / resolve paths relative to this directory (absolute or relative to workspace root). The JSON file stays at workspace root; validation fails if the path is missing or not a directory. |
{
"workingDir": "/path/to/project",
"maxIterations": 50
}
Omit the file if defaults are enough.
Technology stack
| Layer | Details |
|---|---|
| Runtime | Node.js ≥ 22 (CI uses 22.x; see .node-version) |
| Package manager | pnpm 10.x (pinned in root packageManager) |
| Language | TypeScript 6.x |
| Core / MCP | @modelcontextprotocol/sdk, workspace package @ergenekonyigit/cursor-autoresearch-core |
| Extension | esbuild bundle, @vscode/vsce, VS Code engine ^1.105.0 |
| Tests | Vitest 4.x (pnpm test runs all packages) |
| Lint | ESLint 10.x (pnpm lint) |
npm packages
Published packages:
Run MCP server directly with npx:
npx -y @ergenekonyigit/cursor-autoresearch-mcp-server
Requirements
- Node.js
- 22 or newer to develop this repository (
engines.nodein the rootpackage.json,.node-version, CI). - 18 or newer to run the published MCP server with
npx(@modelcontextprotocol/sdkdeclares Node ≥ 18; the published autoresearch packages do not set a tighterenginesfield).
- 22 or newer to develop this repository (
- pnpm — only needed when working from a clone of this repo; enable with Corepack (
corepack enable) or install manually to match the pinned version.
Build (from a clone)
git clone https://github.com/ergenekonyigit/cursor-autoresearch.git
cd cursor-autoresearch
pnpm install
pnpm build
The MCP entrypoint after build is packages/mcp-server/dist/index.js if you prefer local path-based setup.
The Install for Cursor and Install for VS Code examples use npx -y @ergenekonyigit/cursor-autoresearch-mcp-server for simpler setup.
Develop this repository
pnpm install
pnpm build
pnpm test
| Command | Purpose |
|---|---|
pnpm lint | ESLint across the repo |
pnpm typecheck | TypeScript --noEmit for all workspace packages |
pnpm build | Build core, mcp-server, and the VS Code extension |
pnpm test | All package tests |
pnpm clean | Remove packages/*/dist |
pnpm package:extension | Produce .vsix under packages/vscode-extension/ |
After pnpm clean, run pnpm build before pnpm test so workspace resolution and Vitest aliases stay consistent.
Run MCP locally (after pnpm build):
AUTORESEARCH_CWD=/path/to/your/project node packages/mcp-server/dist/index.js
Contributor setup, docs deployment, local MCP, and PR expectations: CONTRIBUTING.md. Releases: RELEASING.md. Security reporting: SECURITY.md. Change history: CHANGELOG.md. License: MIT — see LICENSE.
