Getting Started

Prerequisites

Before starting, make sure you have the pieces that LegoFlow cannot create for you:

• Claude Code, which is the recommended way to operate LegoFlow.
• LLM endpoints for Curator, Tracer, and Evaluator jobs.
• GitHub token(s), used by Curator when collecting pull requests.
• A GPU server if you plan to run training or evaluate self-hosted models.
• Optional Docker credentials, useful when large runs pull many task images.
• Optional Cloudflare credentials, only needed if you want to publish dashboards.

Claude Code plugin installation

The easiest way to use LegoFlow is through plugin skills. Think of these as guided commands that know the project layout, check the right files, and ask for confirmation before expensive jobs start.

Install all plugins once per machine. From the repository root, first register each local plugin directory as a Claude Code marketplace:

claude plugin marketplace add ./.claude/plugins
claude plugin marketplace add ./blocks/curator/.claude/plugins
claude plugin marketplace add ./blocks/tracer/.claude/plugins
claude plugin marketplace add ./blocks/trainer/.claude/plugins
claude plugin marketplace add ./blocks/evaluator/.claude/plugins

Then install the plugin from each marketplace. The format is <plugin-name>@<marketplace-name>, as defined by each local marketplace.json:

claude plugin install root@root-block
claude plugin install curator@curator-block
claude plugin install tracer@tracer
claude plugin install trainer@trainer-block
claude plugin install evaluator@evaluator-block

In any active Claude Code session, run /reload-plugins once to pick them up, or restart the session. You should then see root and block skills such as /root:setup, /root:check, /curator:create-tasks, and /tracer:dashboard. These skills are the main entry points for LegoFlow: they guide users through setup, checks, runs, and inspection without requiring them to memorize the underlying scripts.

Codex plugin installation

LegoFlow also ships Codex plugins in plugins/. Register this repository as a local marketplace and install the plugins before starting Codex:

codex plugin marketplace add .
codex plugin add root@legoflow
codex plugin add curator@legoflow
codex plugin add tracer@legoflow
codex plugin add trainer@legoflow
codex plugin add evaluator@legoflow

Restart Codex after installation. Codex does not use the Claude Code marketplace commands above. Invoke native skills such as $curator-check and $tracer-run.

cd LegoFlow
codex

The available Codex plugin directories are:

plugins/root/
plugins/curator/
plugins/tracer/
plugins/trainer/
plugins/evaluator/

Each directory contains a .codex-plugin/plugin.json manifest and skills. The Codex skills are thin wrappers that read and follow the corresponding canonical Claude Code skill under .claude/plugins/; do not maintain a separate Codex workflow.

Codex uses the following namespaced native skills:

$root-check
$curator-check
$curator-create-tasks
$tracer-run
$trainer-run
$evaluator-dashboard

Curator's native Codex skills are:

Use check -> confirm -> run with either agent. Run the relevant check first, review its report, and wait for explicit confirmation before launching expensive or stateful work.

Project setup

The setup flow has two parts.

1) Block Setup Skill

Once the plugins are loaded, use the setup skill for the block you want to run. For the full tree, start with /root:setup. It checks shared tooling, verifies the root config.yaml, and can walk into each child block's setup flow. It does not launch the pipeline; it only gets the workspace ready for a real check.

2) Configure the Run

Every block has a config.yaml. Think of it as the checklist LegoFlow reads before that block runs. The root config.yaml mostly holds orchestration metadata:

runtime_info:  input:    cloudflare:      account_id: ""              # Optional: only needed for dashboard publishing      api_token: ""               # Optional: prefer an env/secret; never commit a real token      pages_project_prefix: "legoflow"  # Optional: dashboard project prefix    docker:      registry: ""                # Optional: leave empty for Docker Hub/default registry      username: ""                # Optional: needed only for authenticated image pulls      password: ""                # Optional: prefer an env/secret; never commit a real password      mirror: ""                  # Optional: use only if your network needs a Docker mirror      host: ""                    # Optional: leave empty for the default Docker daemon

Cloudflare settings are mainly used for dashboard publishing. Docker credentials are only needed for authenticated image pulls, especially in Tracer when pulling SWE task images and in Evaluator when pulling test-case images. Each block explains its own config.yaml in its Configuration Guide.

Work through one independent run per block before launching the cascaded root pipeline. Continue with Running Block by Block.