Docs · Drivers

Drivers: Claude Code, Cursor or your own key

A driver is who proposes and runs rounds when no chat is open — for a competition's auto-run and for repository auto-run. One driver per project, switchable any time; it also does the background sensors' AI work.

The three drivers#

DriverWhat runsLimitsStatus
claudeHeadless Claude Code (claude -p) on your Claude subscription — no API keyEnforced by its allowed tools: only researchforge commands and file edits inside the projectUsed in real runs
cursorThe Cursor agent CLI (cursor-agent -p) with the same instructionsInstructions only: headless Cursor needs --force, which allows any commandTested
byokBring your own key: the terminal calls Anthropic, Gemini or OpenAI directly, or a local Ollama model, through researchforge kaggle runRuns through ResearchForge’s own loop, not a coding agentTested

BYOK (bring your own key) means the terminal calls Anthropic, Gemini or OpenAI directly, or a local Ollama model (RESEARCHFORGE_LLM=ollama/<model>). It is independent of any Claude Code or Cursor setup. For a local model there is nothing to sign in: set the variable and pick byok.

Because headless Cursor runs with --force, prefer the Cursor driver on a machine you trust. Claude Code's limits are enforced, not just requested.

Auto-run on Squares in Squares launched 40 of its 46 rounds with the Claude Code driver; Enveda CASMI 2026 and the Gemma 4 Developer Agent used it too. Every round records which driver ran it, shown on the Runs page.

localhost:7842
Runs page where each round shows Claude Code and auto
Runs: each round says which driver ran it and whether auto-run launched it

Sign a driver in#

$ researchforge kaggle driver-login claude # runs claude setup-token; a browser opens once
$ researchforge kaggle driver-login cursor
$ researchforge kaggle driver-login byok # asks for the key at a hidden prompt
$ researchforge kaggle auto-run-key CLAUDE_CODE_OAUTH_TOKEN # store one value: CURSOR_API_KEY, an AI API key, …

Run these in your own terminal; they refuse to run without one, so no other program can pass them a value. Or paste the token on the dashboard's Keys & accounts page. Tokens and keys go to ~/.config/researchforge/auto_run.env (mode 600), are passed only to the driver, and are never shown again or typed into a chat.

Pick or switch#

$ researchforge kaggle driver <slug> # current driver, readiness and setup steps
$ researchforge kaggle driver <slug> cursor # the next launch and sensor call use it
$ researchforge auto-run settings --on --driver claude # a repository project

Or in Automation → Driver and Run configs → Who runs it. A launch already running finishes on its old driver unless you stop it.

localhost:7842
Automation: scheduler and the driver panel with Claude Code ready
Automation: the scheduler and the Driver panel, with what the driver is allowed to do

Usage limits#

If the driver hits its usage limit — Claude's weekly limit, for example — auto-run reads the reset time from the message, tells you once and waits until then, instead of failing every cycle. To keep going, switch driver in Run configs.

What a driver may and may not do#

  • Propose and run rounds on ideas in the pool, within rounds per launch, a daily maximum and a launch time limit.
  • Ask you a question; only the ideas it names wait.
  • Never submit to Kaggle, answer a submission question, approve a repository plan, or ship.
  • Never ask you to run a command on your machine.
localhost:7842
Auto-run panel with rounds per launch, max per day and Start now
The auto-run panel: rounds per launch, a daily maximum, Start now and the last launch

What it costs#

With an API key, every call is metered per model, purpose and round on the dashboard's Insights page. A coding agent's tokens are spent inside its own session and are not visible to ResearchForge, so Insights says so instead of showing a zero cost. See Timeline and Insights.