Auto-PsyNet

Auto-PsyNet (apsy)

A Claude Code plugin that automates the lifecycle of online behavioral experiments built on PsyNet: from a raw research idea → preregistered plan → working PsyNet code → LLM-piloted (and human) deployment → analysis → publication-ready paper. Subjects can be humans, LLM agents, or both.

Also available as a Cursor Marketplace plugin → auto-psynet-cursor. Same logic, gates, ethics policy, and bin/ engines; install with /add-plugin apsy in Cursor 2.5+.

Install

Inside a Claude Code session (requires Claude Code with plugin support):

# Add the marketplace from GitHub, then install the plugin:
/plugin marketplace add Haoyu-Hu/auto-psynet
/plugin install apsy@auto-psynet

# Then:
/apsy:setup           # one-time config (interpreter, project-dir, LLM backend, AWS, ...)
/apsy:install         # install psynet + dallinger (offers a managed venv)
/apsy:doctor          # verify the runtime

Developing locally? Point the marketplace at your checkout instead of GitHub — the plugin source is a repo-root relative path, so it resolves against whichever copy you added:

/plugin marketplace add /path/to/auto-psynet      # your local clone
/plugin install apsy@auto-psynet

If /plugin install reports "This plugin uses a source type your Claude Code version does not support," update Claude Code to a recent version (claude update) and re-run /plugin marketplace update auto-psynet before installing.

Quick start — a new study

/apsy:idea "<your research question>"   # → preregistered plan (gate G1)
/apsy:build                              # → working PsyNet code (gate G2)

/apsy:services start                     # Redis + Postgres for local debug
/apsy:debug                              # launch psynet debug local
/apsy:export                             # export data while it runs
/apsy:debug stop                         # clean shutdown
/apsy:services stop

/apsy:pilot                              # LLM-agent participants (gate G3)
/apsy:analyze                            # preregistered analysis (gates G5/G6/G7)
/apsy:paper                              # paper draft + OSF reproducibility package

For real human deployment, /apsy:deploy triggers gate G4 — explicit human approval + IRB attestation + a spend cap required at every autonomy level (see config/ethics-policy.md).

New here? The G1–G7 references above are the plugin's seven quality gates (preregistration discipline, no p-hacking, no synthetic-as-human, no unethical deployment). For a plain-English introduction to what gates are, why they exist, and what each one checks, read GATES.md. How often the plugin pauses to ask you vs. acts on its own is controlled by the per-experiment autonomy level (defaults to supervised); see AUTONOMY.md for the three levels and how to switch between them.

Browsing the command surface

For a single browsable reference document with every command's purpose, arguments, outputs, and the gates it triggers, see COMMANDS.md. In-CLI, the same content is available via /apsy:help:

/apsy:help                  # list every command + a one-line description
/apsy:help <name>           # detailed help for one command (e.g. /apsy:help debug)
/apsy:help --search redis   # filter by keyword

Or use /apsy:auto "<free-text intent>" to let the smart router pick the right command for you.

Pipeline

FORMULATE →[G1] BUILD →[G2] PILOT & DEPLOY →[G3/G4] ANALYZE →[G5/G6/G7] PUBLISH
   idea→plan     experiment code    LLM-pilot · humans     data → findings    paper
                         ╰────────────── iterate ──────────────╯

Seven quality gates (G1-G7) gate transitions — what each one checks is explained in GATES.md; runnable rubrics live in config/gates/. /apsy:run walks the whole pipeline autonomously, honoring autonomy_level (see AUTONOMY.md — supervised / semi_autonomous / autonomous; G4 is always hard at every level).

Project organization

Set APSY_PROJECT_DIR once (via /apsy:setup or /apsy:project-dir) and every new study gets a consistent home; exports + PsyNet's hardcoded data paths are routed into it:

$APSY_PROJECT_DIR/
├── pleasantness-rating/          ← per-experiment dir
│   ├── experiment.py  config.txt  requirements.txt  constraints.txt
│   └── .apsy/                    ← state + reports + paper draft
├── color-gsp/
└── data/                         ← (optional ~/psynet-data symlink)
    ├── export/<study>/           ← exports land here
    └── assets/  launch-data/     ← PsyNet's other hardcoded dirs