Docs · Start here

Install ResearchForge and pick how it runs

ResearchForge is open-source autoresearch: a command-line tool that runs ML experiments for you, measures each one against a frozen baseline, and keeps or rejects it with a reason. Install it once, then pick a track.

Install#

Every path starts with the same pip install. Then add the skills for your editor — or use no editor at all.

Claude Code

  1. 1
    pip install researchforge
  2. 2
    researchforge claude install --user

    or install the Claude Code plugin (below)

  3. 3
    /overnight <competition-url>

    from the plugin: /researchforge:overnight

Cursor

  1. 1
    pip install researchforge
  2. 2
    researchforge cursor install --user
  3. 3
    @overnight <competition-url>

    in the agent chat

No editor

  1. 1
    pip install researchforge
  2. 2
    export RESEARCHFORGE_LLM=ollama/qwen3:14b

    a local model, or ANTHROPIC_API_KEY / GEMINI_API_KEY / OPENAI_API_KEY

  3. 3
    researchforge kaggle overnight <competition-url>
  4. 4
    researchforge kaggle run <slug>

Claude Code plugin. Instead of researchforge claude install, you can install the same skills from the plugin marketplace. Plugin skills are namespaced (/researchforge:overnight). Use one or the other, not both, or every skill appears twice.

inside Claude Code
› /plugin marketplace add forger-labs-hq/researchforge
› /plugin install researchforge@researchforge
Check the install with researchforge --version and researchforge doctor. The doctor names anything missing (git, Python, Docker) and how to fix it.

Pick how it runs#

Something has to propose each experiment. That is either the AI in your editor, or a model ResearchForge calls itself. ResearchForge always does the running, measuring and record-keeping.

Drive it fromWho proposesKeyEditor stays openStart with
Claude CodeClaude, in your Claude Code sessionNone — your Claude planYes — or turn on auto-run/overnight <url>
CursorCursor’s agentNone — your Cursor planYes — or turn on auto-run@overnight <url>
BYOK (your API key)Claude, Gemini or OpenAI, called directly from the terminalANTHROPIC_API_KEY, GEMINI_API_KEY or OPENAI_API_KEYNo — runs headlessresearchforge kaggle run <slug>
Local modelYour Ollama model, called by ResearchForgeNone — RESEARCHFORGE_LLM=ollama/<model>No — runs headlessresearchforge kaggle run <slug>
In every mode the loop runs on the machine where you start it, so that machine stays on. Want your laptop free? Start it on an always-on server over SSH.

Or start without an editor. Open the dashboard with researchforge dashboard, add the competition under + New competition, set your keys under Keys & accounts and pick a driver for auto-run. You can open Claude Code or Cursor later and continue with /overnight <slug> — or never.

localhost:7842
Dashboard: + New competition with a Kaggle URL, a folder and Gather facts
Starting a competition from the dashboard — every view is in the dashboard docs
API key or local model — pick one
$ export ANTHROPIC_API_KEY=sk-ant-... # or GEMINI_API_KEY / OPENAI_API_KEY
$ export RESEARCHFORGE_LLM=ollama/qwen3:14b # local model, no key (after: ollama pull qwen3:14b)
$ export OLLAMA_HOST=http://gpu-box:11434 # only if Ollama runs on another machine

Choose a track#

Whichever track you pick, four short pages answer the usual next questions:

localhost:7842
Dashboard Home: projects, experiments, ideas waiting and questions for you
What you see once a competition is running: researchforge dashboard, at localhost:7842

Requirements#

  • Python 3.12+ and git. macOS, Linux or Windows.
  • For Kaggle Overnight: a Kaggle account and API token (~/.kaggle/kaggle.json or KAGGLE_USERNAME / KAGGLE_KEY), or paste it on the dashboard's Keys & accounts page.
  • Optional: Docker, to run repository experiments in containers.
  • Optional: pip install "researchforge[serve]" for the live read-only monitor (researchforge serve, researchforge hub).

Upgrade#

$ pip install --upgrade researchforge
$ researchforge --version

Skills and rules installed with claude install / cursor install refresh themselves after an upgrade. Ones you edited are left alone. Plugin users update from /plugin. What changed in each release is in the changelog.