Getting Started¶

Prerequisites¶

Python 3.10+
SSH access to an HPC cluster with SLURM or SGE
Claude Code CLI installed and authenticated on the HPC cluster

Installation¶

pip install researchloop

Initialize a project¶

researchloop init

This creates a researchloop.toml configuration file and an artifacts/ directory in the current directory.

Configure¶

Edit researchloop.toml with your cluster and study settings:

shared_secret = "change-me"
orchestrator_url = "https://your-server.fly.dev"

[[cluster]]
name = "hpc"
host = "login.cluster.example.com"
user = "researcher"
key_path = "~/.ssh/id_ed25519"
scheduler_type = "slurm"
working_dir = "/scratch/researcher/researchloop"

[cluster.job_options]
gres = "gpu:1"
mem = "64G"
cpus-per-task = "8"

[[study]]
name = "my-research"
cluster = "hpc"
description = "Investigating feature X"
max_sprint_duration_hours = 8
red_team_max_rounds = 3

See the Configuration page for all available options.

Start the orchestrator¶

researchloop serve

This starts the FastAPI server on port 8080 (configurable). The server provides:

REST API for sprint and study management
Web dashboard at /dashboard/
Webhook endpoints for sprint runners
Slack Events API handler

Connect the CLI¶

If running the orchestrator on a remote server, connect the CLI:

researchloop connect https://your-server.fly.dev
# Prompts for the dashboard password

Check connection status:

researchloop status

Verify cluster connectivity¶

Test that the orchestrator can reach your HPC cluster:

researchloop cluster list
researchloop cluster check

Create a study¶

Scaffold a study directory with a starter CLAUDE.md:

researchloop study init my-research

Edit studies/my-research/CLAUDE.md to describe your research area, background, goals, and constraints. This context is given to Claude at the start of every sprint.

Then add claude_md_path to your study config in researchloop.toml:

[[study]]
name = "my-research"
cluster = "hpc"
claude_md_path = "./studies/my-research/CLAUDE.md"

Run your first sprint¶

researchloop sprint run "implement baseline model and evaluate on test set" --study my-research

This will:

Create a sprint record in the database
Render all pipeline prompts (research, red-team, fix, report, summarize)
Generate a self-contained job script
SSH to the cluster, create the sprint directory, and upload the script
Submit the job via sbatch
Send a notification that the sprint has started

Monitor progress¶

From the CLI¶

researchloop sprint list
researchloop sprint show sp-a3f7b2

From the dashboard¶

Open http://localhost:8080/dashboard/ in your browser. The sprint detail page shows:

Current pipeline step
Live progress from progress.md
Script output from output.log
Tool usage log
Report (markdown rendered to HTML)
Downloadable artifacts

Click "Refresh" to pull the latest status from the cluster.

From Slack¶

If Slack is configured, the bot will notify you when sprints complete or fail. You can also check status with sprint list.

Run an auto-loop¶

Auto-loops chain multiple sprints together. After each sprint completes, Claude analyzes the results and generates the next research idea:

researchloop loop start --study my-research --count 5 --context "focus on improving F1 score"

Monitor loop progress:

researchloop loop status

Stop a running loop:

researchloop loop stop loop-abc123