youtube_downloader_gui: Instructions file for Codex

AGENTS.md

This file describes how an AI coding agent (and humans) should work in this repository.

0) Always read the docs first

Before making changes or running commands, read all README.md files in this repo and follow them.

• Repo overview & dev workflow: README.md
• E2E test runner conventions: testcases/README.md (if present)

If you already read them earlier in the session, re-check when unsure.

1) Python / Poetry requirements (strict)

This project targets Python 3.11 (always set the Poetry env to 3.11 before installing deps or running commands).

• Prefer Poetry-managed environments.
• If Poetry selected another Python (e.g. 3.12+), switch it:

poetry env use python3.11
poetry env info
poetry install

If python3.11 is not available on PATH, use an absolute path to the 3.11 executable.

2) Default rule: use poetry run for scripts

When running any repo scripts, prefer:

• poetry run <command>

This ensures the correct virtualenv + dependencies are used.

3) Running the app: prefer reflex_rerun.sh

When you need to start/restart the Reflex app during development, prefer the repo helper script.

Typical usage:

poetry run ./reflex_rerun.sh

Notes:

• Prefer poetry run ./reflex_rerun.sh over poetry run reflex run.
• This keeps the app startup/restart behavior consistent and helps it run stably on the expected ports: frontend 3000, backend 8000.
• If you must run Reflex directly, still do it via Poetry: poetry run reflex run.

3.5) Recreate the env: use proj_reinstall.sh

To fully rebuild the local Poetry environment and clean Reflex artifacts, run:

./proj_reinstall.sh

Flags:

• --remove-only: only clean artifacts and remove Poetry envs; no new env/install.
• --with-rerun: after reinstall, run poetry run ./reflex_rerun.sh automatically.

The script will auto-run poetry lock if poetry install fails due to a stale lockfile.

4) Running E2E suites: prefer run_test_suite.sh