Skip to main content
This guide is for contributors running the Diffraction checkout and trusted application commands on their own machine. To upload uncommitted changes for a hosted isolated review, use the installed CLI.

​
Prepare Diffraction

Use Node.js 24.x, pnpm 11, an authenticated Codex CLI, and GitHub CLI authentication for PR lookup. From the Diffraction checkout:
Prepare the workspace
The dashboard runs at http://localhost:3000. Local dashboard access requires WorkOS authentication. Contributors need access to the configured staging workspace and must follow the repository’s local authentication setup. Credentials go in the ignored web/.env.development.local; public identity configuration remains in the auth slice’s versioned config.

​
Review a pull request

Prepare a trusted application checkout. Supported Node apps use automatic configuration; add an optional configuration file for custom setup. For PR mode, the checkout must be clean and match the PR’s exact head SHA. In another terminal, replace the example path and PR number:
Run a local review
Open http://localhost:3000/reviews to follow real progress, then inspect target recordings, screenshots, traces, and findings. Runs are stored under .diffraction/local-reviews/, which is ignored by Git. An exit code of 1 can mean a recorded flow failed or findings were found. Inspect the run evidence and command output before treating it as a tool failure.

​
Reuse a plan or record without a PR

A reused plan must match the repository and exact PR head and avoids new planning inference. The standalone command without --pr writes recorder artifacts under .diffraction/runs/; it is separate from the PR dashboard run directory. Install each browser selected by the application’s resolved configuration.

​
Local execution boundaries

Local execution is for trusted checkouts. It runs application commands on your machine and does not provide the production sandbox boundary for hostile PR code. This mode uses Codex planning and deterministic analysis. It does not call OpenRouter, perform Stagehand exploration or multimodal analysis, or publish GitHub results. Local artifact routes are limited to loopback development access. To preview this documentation site separately, run pnpm docs:dev from the Diffraction root and open http://localhost:3001.