Menu
How to develop the frontend and backend together. When you want to make changes to the UI, use this.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | full-stack-dev |
| description | How to develop the frontend and backend together. When you want to make changes to the UI, use this. |
We have a frontend React app in www/. It is pretty lightweight for the moment. It has some views to list eval sets, scans, and samples, from the data warehouse DB.
It embeds the inspect_ai and inspect_scout frontend components.
If you want to make changes to inspect_ai and inspect_scout, you can link them to this project.
It's perfectly okay to make changes to inspect_ai and inspect_scout. We can contribute changes upstream.
Env files are generated from Pulumi stack outputs using scripts/dev/generate-env.py (run from the repo root, i.e. ~/dev/hawk).
CLI-only env (for hawk CLI usage):
uv run python scripts/dev/generate-env.py <stack> > hawk/.env
Full local dev env (includes HAWK_API_* vars for running FastAPI locally):
uv run python scripts/dev/generate-env.py <stack> --api > hawk/.env
The --api flag adds HAWK_API_* vars (database URL, S3 bucket, middleman, ECR repos, etc.) plus VITE_* vars for the frontend, all pointing at the deployed stack's infrastructure.
Available stacks: stg, dev-mish1, dev-faber, etc.
To run FastAPI locally against a deployed stack's DB/S3/etc.:
cd hawk
uv run python ../scripts/dev/generate-env.py dev-mish1 --api > .env # if not already done
set -a && source .env && set +a
uv run fastapi dev hawk/api/server.py --port 8080
The backend takes ~15-20 seconds to start due to heavy imports. If port 8080 is in use, pick another port and update VITE_API_BASE_URL.
Alternatively, to skip running the backend locally and point the frontend at a deployed API:
VITE_API_BASE_URL=https://api-mish1.hawk.staging.metr-dev.org pnpm dev
The frontend uses pnpm (specified in package.json packageManager). npm run dev also works.
cd www
pnpm install # if needed
set -a && source ../.env && set +a # picks up VITE_* vars
pnpm dev
The dev server runs on http://localhost:3000/. The backend API URL is configured via VITE_API_BASE_URL (defaults to http://localhost:8080).
cd ~/dev/inspect_ai/src/inspect_ai/_view/www
pnpm install
pnpm build:lib --watch
For Scout:
cd ~/dev/inspect_scout/src/inspect_scout/_view/www
pnpm install
pnpm build:lib --watch
Use when the user asks to update, sync, or refresh the Hawk docs (quickstart, configuration reference, infrastructure description and diagrams) to reflect changes since the last documentation sync. Triggers on "update the docs", "sync docs", "docs are stale", "refresh quickstart", "update the architecture diagram", or after merging infra/config/CLI changes that affect user-visible setup.
Debug stuck Hawk/Inspect AI evaluations. Use when user mentions "stuck eval", "eval not progressing", "eval hanging", "samples not completing", "eval set frozen", "runner stuck", "500 errors in eval", "retry loop", "eval timeout", or asks why an evaluation isn't finishing.
How to create and use our alembic database migration tool. Use when making changes to models.py.
Monitor Hawk job status, view logs, and diagnose issues. Use when the user wants to check job progress, view error logs, debug a failing job, or generate a monitoring report for a Hawk evaluation run.
Run smoke tests on a deployed environment to ensure basic functionality.
View and analyze Hawk evaluation results. Use when the user wants to see eval-set results, check evaluation status, list samples, view transcripts, or analyze agent behavior from a completed evaluation run.