# Script Reference

These scripts are the public operator entrypoints for this repo.

## Summary

| Script | Purpose | External Systems |
| --- | --- | --- |
| `scripts/refresh_master.py` | Restore `train.py` from the current local promoted master and rebuild live metadata | Local files only |
| `scripts/hf_job.py` | Preflight, render, launch, inspect, and tail managed HF Jobs | Hugging Face Jobs, local files |
| `scripts/opencode_worker.py` | Create, run, and clean isolated OpenCode experiment worktrees | Git worktrees, OpenCode, local files |
| `scripts/hermes_worker.py` | Create, print delegate payloads for, and clean isolated Hermes experiment worktrees | Git worktrees, Hermes delegation, local files |
| `scripts/pi_worker.py` | Create, run, and clean isolated Pi experiment worktrees | Git worktrees, Pi, local files |
| `scripts/print_opencode_kickoff.py` | Print a parent-session kickoff prompt | Local files only |
| `scripts/print_hermes_kickoff.py` | Print a Hermes parent-session kickoff prompt | Local files only |
| `scripts/print_pi_kickoff.py` | Print a Pi Agent parent-session kickoff prompt | Local files only |
| `scripts/print_claude_kickoff.py` | Print a Claude Code-native kickoff prompt | Local files only |
| `scripts/print_codex_kickoff.py` | Print a Codex-native kickoff prompt | Local files only |
| `scripts/setup_hermes_profile.py` | Create or update a local Hermes profile home and wire in repo skills | Local Hermes config, local files |
| `scripts/parse_metric.py` | Parse the final metric block from a run log | Local files only |
| `scripts/submit_patch.py` | Append a run to `research/results.tsv` and locally promote if it wins | Local files, optional Hugging Face Jobs logs |
| `scripts/sync_upstream.py` | Diff or apply upstream-tracked core files from `karpathy/autoresearch` | GitHub raw files |
| `scripts/trackio_reporter.py` | Sync jobs to Trackio and render a local dashboard | Hugging Face Jobs, Trackio, local files |

## `scripts/refresh_master.py`

- Inputs:
  - `--fetch-dag`
  - `--force`
- Environment:
  - none
- Outputs:
  - rewrites `train.py`, `train_orig.py`, and files under `research/live/`
- Use when:
  - starting any fresh benchmark run
  - restoring the checkout to the current promoted local master

## `scripts/hf_job.py`

- Inputs:
  - `preflight`, `render`, `launch`, `inspect`, `logs`
- Environment:
  - `AUTOLAB_HF_BUCKET` required for `prepare` and `experiment`
  - `AUTOLAB_HF_NAMESPACE` optional
  - `AUTOLAB_CAMPAIGN` optional
  - `AUTOLAB_EXPERIMENT_ID` optional
  - `AUTOLAB_WORKER_ID` optional
  - `AUTOLAB_HYPOTHESIS` optional
  - `AUTOLAB_HF_PREPARE_FLAVOR`, `AUTOLAB_HF_PREPARE_TIMEOUT`
  - `AUTOLAB_HF_EXPERIMENT_FLAVOR`, `AUTOLAB_HF_EXPERIMENT_TIMEOUT`
  - `AUTOLAB_HF_CLI` optional
  - `AUTOLAB_HF_SECRETS` optional
- Outputs:
  - rendered job bundles under `.runtime/`
  - job metadata under `.runtime/hf-jobs/`
  - cached logs under `.runtime/hf-logs/`
  - streamed logs when requested
- Use when:
  - validating a workspace before launch
  - starting and monitoring managed benchmark runs

## `scripts/opencode_worker.py`

- Inputs:
  - `create`, `run`, `cleanup`
- Environment:
  - `AUTOLAB_OPENCODE_BIN` optional override for the OpenCode executable
- Outputs:
  - isolated worktrees under `.runtime/worktrees/`
  - worker state under `.runtime/opencode-workers/`
  - experiment notes under `research/experiments/`
  - reserved run logs under `research/live/`
- Use when:
  - launching an `experiment-worker` in a filesystem-isolated checkout
  - keeping parallel paid runs from colliding in the main checkout

## `scripts/hermes_worker.py`

- Inputs:
  - `create`, `delegate`, `cleanup`
- Environment:
  - none required; the emitted payload exports `AUTOLAB_*` vars inside the child shell
- Outputs:
  - isolated worktrees under `.runtime/worktrees/`
  - shared worker state under `.runtime/opencode-workers/`
  - experiment notes under `research/experiments/`
  - reserved run logs under `research/live/`
  - a ready-to-paste `delegate_task(...)` payload for Hermes
- Use when:
  - reserving an isolated experiment worktree for a Hermes child worker
  - emitting the exact worker goal, context, toolsets, and iteration budget
  - keeping the parent Hermes session in the main checkout

## `scripts/pi_worker.py`

- Inputs:
  - `create`, `run`, `cleanup`
- Environment:
  - `AUTOLAB_PI_BIN` optional override for the Pi executable
- Outputs:
  - isolated worktrees under `.runtime/worktrees/`
  - shared worker state under `.runtime/opencode-workers/`
  - experiment notes under `research/experiments/`
  - reserved run logs under `research/live/`
  - Pi worker sessions under `.runtime/pi-worker-sessions/`
- Use when:
  - launching a Pi `experiment-worker` in a filesystem-isolated checkout
  - keeping parallel paid runs from colliding in the main checkout
  - sharing the same experiment reservation state as OpenCode and Hermes

## `scripts/print_opencode_kickoff.py`

- Inputs:
  - optional `--campaign`, `--gpu-slots`, `--max-ideas`
- Environment:
  - none
- Outputs:
  - a standard parent-session prompt to stdout
- Use when:
  - starting a fresh OpenCode planning session in the pre-training project root

## `scripts/print_hermes_kickoff.py`

- Inputs:
  - optional `--campaign`, `--gpu-slots`, `--max-ideas`
- Environment:
  - none
- Outputs:
  - a standard Hermes parent-session prompt to stdout
- Use when:
  - starting a fresh Hermes planning session in the pre-training project root
  - reminding the parent session to stay within Hermes' 3-child delegation cap

## `scripts/print_pi_kickoff.py`

- Inputs:
  - optional `--campaign`, `--gpu-slots`, `--max-ideas`
- Environment:
  - none
- Outputs:
  - a standard parent-session prompt for the secondary Pi Agent workflow
- Use when:
  - starting a Pi session that should follow the same local-master and HF Jobs workflow as OpenCode
  - reminding the parent session to use `pi-subagents` project roles and `scripts/pi_worker.py`

## `scripts/print_claude_kickoff.py`

- Inputs:
  - optional `--campaign`, `--gpu-slots`, `--max-ideas`
- Environment:
  - none
- Outputs:
  - a standard parent-session prompt for the secondary Claude Code-native workflow
- Use when:
  - starting a Claude Code session that should follow the same local-master and HF Jobs workflow as OpenCode

## `scripts/print_codex_kickoff.py`

- Inputs:
  - optional `--campaign`, `--gpu-slots`, `--max-ideas`
- Environment:
  - none
- Outputs:
  - a standard parent-session prompt for the secondary Codex-native workflow
- Use when:
  - starting a Codex session that should follow the same local-master and HF Jobs workflow as OpenCode

## `scripts/setup_hermes_profile.py`

- Inputs:
  - optional `--profile`, `--hermes-bin`, `--dry-run`
- Environment:
  - optional `HERMES_HOME` to choose the source home when cloning fallback profile files
- Outputs:
  - a local profile home under `~/.hermes/profiles/<profile>/`
  - a repo-skill entry under `skills.external_dirs` in the profile config
  - a fallback `~/.local/bin/<profile>` wrapper when Hermes does not expose `profile` subcommands
- Use when:
  - bootstrapping the repo's Hermes adapter without committing local Hermes state
  - ensuring the Hermes parent stays on `worktree: false` by default

## `scripts/parse_metric.py`

- Inputs:
  - a path to a job or local run log
- Environment:
  - none
- Outputs:
  - JSON metric block to stdout
- Use when:
  - extracting `val_bpb`, timing, and utilization metrics after a completed run

## `scripts/submit_patch.py`

- Inputs:
  - `--comment`
  - optional `--priority`, `--parent-hash`, `--job-id`, `--log`, `--dry-run`
- Environment:
  - `AUTOLAB_HF_CLI` optional when the command needs to fetch uncached HF Job logs
  - `AUTOLAB_HF_NAMESPACE` optional when the command needs to fetch uncached HF Job logs
- Outputs:
  - appends a row to `research/results.tsv`
  - updates `train_orig.py` and `research/live/` only when the result beats current master
- Use when:
  - recording a completed managed benchmark run
  - promoting a new local master after a real improvement

## `scripts/sync_upstream.py`

- Inputs:
  - optional `--check`, `--apply`, `--branch`, `--timeout`
- Environment:
  - none
- Outputs:
  - unified diffs against upstream-tracked files
  - optional in-place updates for `prepare.py`, `train.py`, `program.md`, `pyproject.toml`, and `uv.lock`
- Use when:
  - comparing the repo's upstream-tracked files against `karpathy/autoresearch`
  - explicitly applying upstream file updates without touching the local results ledger

## `scripts/trackio_reporter.py`

- Inputs:
  - `sync`, `dashboard`, `summary`
- Environment:
  - `AUTOLAB_TRACKIO_PROJECT` optional, defaults to `autolab`
  - `AUTOLAB_HF_NAMESPACE` recommended
  - `AUTOLAB_HF_CLI` optional
  - `AUTOLAB_TRACKIO_BIN` optional
- Outputs:
  - local reporter state and markdown summaries under `.runtime/`
  - merged job views from `.runtime/hf-jobs/*.json` and `.runtime/worktrees/*/.runtime/hf-jobs/*.json`
  - Trackio runs and dashboard output
- Use when:
  - checking active jobs
  - finding duplicate experiment or hypothesis launches
  - monitoring experiment results locally