SLL Lookit Experiment Builder

last edited: march 2026, misha

what is this?

a CLI tool for the Social Learning Lab to scaffold online developmental psych experiments for the CHS/Lookit platform

looking to make a study for the lab on CHS from scratch? this will make a "skeleton" code/repo-base to save you some time! I found that so much of the code across our CHS studies is nearly identical (consent forms, webcam setup, recording controls, positioning screens, exit surveys, IRB language, etc), this handles all that boilerplate so you only have to write your actual trials

it also generates python preprocessing scripts and auto-creates a GitHub repo under the lab org

quickstart

prerequisites

• Node.js v18+ (brew install node if you don't have it)
• GitHub CLI (brew install gh) for auto-creating repos under the lab org
• membership in the sociallearninglab GitHub org w/ repo creation permissions

one-time GitHub auth:

gh auth login

run it

npx create-sll-experiment

no cloning or cd'ing needed, it walks you through everything

what it asks you

| prompt | what it's for | example | |---|---|---| | study name | folder + repo name (lowercase, hyphens only) | star-surprise-3 | | study title | shown to participants | Let's Find The Stars! | | PI name | consent form | Misha O'Keeffe | | PI email | consent form contact | [email protected] | | purpose | one paragraph for consent | We investigate how children respond to... | | procedures | one paragraph for consent | Your child will play a card game and... | | debriefing | shown to parents after study | In this study, we were interested in... | | compensation | payment description | $5 USD Amazon.com gift card (default) | | condition names | comma-separated, must be unique | easy, medium, hard | | counterbalancing | adds isFlipped coin flip toggle | Y/n (default: yes) | | experiment type | EFP, jsPsych, or both | pick one | | surprise scale | optional, yes/no → graded → why explanation | y/N (default: no) | | parent text block | optional, yellow overlay telling parents not to answer for their kid (though this can be changed after as well)| Y/n (default: yes) |

what you get

✓ Experiment scaffolded successfully!

  Directory: ./star-surprise-3
  Protocol:  ./star-surprise-3/code/experiment/protocol-efp.js
  Preprocessing: ./star-surprise-3/code/preprocessing/
  Stimuli:   ./star-surprise-3/materials/
  Media URL: https://raw.githubusercontent.com/sociallearninglab/star-surprise-3/main/materials

  Repo: https://github.com/sociallearninglab/star-surprise-3

  Next steps:
    1. Add your stimuli to materials/
    2. Edit the generated protocol with your study-specific frames
    3. Copy protocol-efp.js contents into the CHS protocol editor

star-surprise-3/
├── code/
│   ├── experiment/
│   │   └── protocol-efp.js          ← generated experiment code
│   ├── preprocessing/
│   │   ├── preprocessing.py         ← Lookit JSON → CSV pipeline
│   │   └── email_extraction.py      ← parent email extraction
│   └── analysis/
├── data/
│   ├── raw/
│   └── processed/
├── materials/
│   ├── img/                         ← put images here
│   ├── mp3/                         ← put audio here
│   └── mp4/                         ← put videos here
├── figures/
├── presentation/
├── writeup/
├── README.md
├── .gitignore
└── LICENSE

what you need to do after

this gives you the skeleton, you still need to:

1. add your stimuli (images/audio/video) to materials/
2. write your study-specific trial frames (the generated code has TODO comments showing you where)
3. set up your study on CHS itself (create study, set permissions, etc)
4. get the code onto CHS:
   • EFP: copy contents of code/experiment/protocol-efp.js into the CHS protocol editor (your study's page → Edit study → Protocol configuration)
   • jsPsych: follow the CHS jsPsych deployment instructions

if you don't have GitHub CLI

still works, just creates files locally and tells you how to push manually:

⚠ GitHub CLI (gh) not found or not authenticated
  Creating files locally...

  → To publish to GitHub:
    1. Move this folder to your local GitHub directory if it's not already there
    2. cd into it, then: git init && git add . && git commit -m "initial scaffold" && git push

experiment types

EFP (Ember Frame Player) - lookit-efp

the "go-to" as of now. your experiment will be a single generateProtocol(child, pastSessions) function that returns { frames, sequence }, you paste it into the CHS protocol editor. (current archive examples use this format)

jsPsych on CHS - lookit-jspsych

the newer path, uses standard jsPsych (v8+) w/ CHS-specific plugins (@lookit/record, @lookit/surveys). real JS modules w/ imports, debugger support, syntax highlighting, etc etc. CHS seems to be moving toward this. as of march 2026 the CHS jsPsych plugin library is still pretty limited but will likely grow as more labs adopt it!

both

generates both versions side by side

experiment archive

the experiments/ folder has 9 past lab experiments, each one includes:

• lookit_code/ - the actual experiment protocol
• preprocessing_code/ - python scripts for converting raw Lookit data (6 of 9 have these)
• README.md - study design, conditions, implementation notes

the studies: self-surprise-5cond, memory-game, self-surprise-cogsci-2026, thirdperson-game, social-groups, selective-help, baby-view-baby, baby-view-other-baby, garden-2a

if you're trying to figure out how to do something specific (card grids, surprise scales, video playback, counterbalancing, etc), browse through these, odds are one of them does something similar

how to help out

so glad you asked! i purposely wanted this to be opensource, so you all should have access to either a) make any changes you think would be helpful or b) initiate pull requests

on top of this, i really encourage you to add any CHS experiment / analysis code to the experiments/ folder, i think the more centralized we can make this, the better (and it's a great resource for others who might be looking to create a CHS study and don't know where to start!)

to add an experiment to the archive:

1. create a new folder in experiments/ (eg experiments/your-study-name/)
2. add lookit_code/ w/ your protocol and preprocessing_code/ w/ any python scripts
3. write a short README.md w/ study design, conditions, anything notable
4. open a PR!

some more context

i've spent the past ~year and a half or so helping create online experiments for our lab on CHS and wanted to create a pipeline for helping to continue creating them going forward, especially after my time here in the lab

the main ideas behind wanting to do this:

1. there's already so much boilerplate that goes into these CHS studies, it's quite programmatic by nature, both CHS-side and SLL-side
2. i was finding myself a bit lost by all the studies happening in the lab and wanted a more central place to have the experiment and analysis code
3. i was inspired by SMILE (Todd Gureckis) but there isn't really anything equivalent for CHS (that I'm aware of, at least)
4. a lot of our experiments happen on CHS, so the easier we can make it, the better!

i thought (and hope) that all of these will be helped by having a more established pipeline for how we create CHS studies in our lab :)