Module 1 — Setup Guide (Windows 11 & macOS)

A step-by-step setup guide for teachers with zero programming experience. Follow it to get a working AI Agent environment on your own laptop. Start with "One-command setup"; if anything fails, use "Manual install" and "Troubleshooting."

Before you start

This guide installs the following tools on your laptop:

• Estimated time: about 20 to 40 minutes (depending on your network).
• Make sure your laptop allows installing software (a normal personal account is fine).
• Stay connected to the internet throughout.

Minimum computer requirements

This workshop runs VS Code, Node.js, Python, and a Chromium browser driven by Codex at the same time. Make sure your laptop meets the specs below ("Recommended" is the threshold for a smoother experience).

Windows 11

macOS

One-command setup

Pick your operating system below and follow the three steps. The scripts are safe to re-run: if something fails midway, reopen Terminal and run it again; installed tools are skipped automatically.

& "$HOME\Downloads\setup-windows.bat"

"%USERPROFILE%\Downloads\setup-windows.bat"

bash ~/Downloads/setup-macos.sh

Manual install (fallback)

If one item fails in the one-command setup, or you prefer to do it step by step, install each tool from the table. After each one, close and reopen Terminal, then confirm with the checklist.

VS Code extensions

Open VS Code, click the square Extensions icon on the left, search for and install the items below; or run the commands in Terminal.

• ms-python.python — Python
• ms-toolsai.jupyter — Jupyter Notebook
• eamodio.gitlens — Git
• dbaeumer.vscode-eslint — JavaScript
• Codex — OpenAI's coding agent (install ID: openai.chatgpt)

code --install-extension ms-python.python
code --install-extension ms-toolsai.jupyter
code --install-extension eamodio.gitlens
code --install-extension dbaeumer.vscode-eslint
code --install-extension openai.chatgpt

Sign in to the Agent

codex "請建立一個名為 hello.txt 的檔案，內容寫上 Hello, AI Agent"

1. Open Terminal, type codex and press Enter.
2. Follow the prompt to sign in; your browser opens a login page. Sign in with your free or ChatGPT Plus account and return to Terminal.
3. Run the "Hello, AI Agent" test below to confirm the agent receives instructions and responds.

codex "Create a file named hello.txt containing the text Hello, AI Agent"

If the agent creates the file and reports back, your AI Agent environment is working.

Let Codex drive a browser (Playwright MCP)

To let the AI Agent open pages, click, fill forms, and take screenshots, install the Playwright MCP plugin for Codex. The one-command setup already installs and registers it; if you went the manual route, run the two steps below.

Step 1 — Download the browser

npx -y playwright install chromium

Step 2 — Register the plugin with Codex

codex mcp add playwright -- npx -y @playwright/mcp@latest

Step 3 — Confirm the plugin is enabled

codex mcp list

You should see playwright with status enabled. Then ask Codex to open a page and screenshot it to confirm it can drive the browser.

Connect to GitHub

To clone a project or upload a site to GitHub, your computer first needs to be "connected" to your GitHub account. We use the GitHub CLI (gh), which signs in entirely through the browser: no SSH keys to generate, and no password typed in the terminal.

Step 1 — Sign in

gh auth login

Use the arrow keys to choose, in order: GitHub.com → HTTPS → Yes when asked to authenticate Git → Login with a web browser. A one-time code appears; press Enter to open the browser, paste the code, and authorize. It also configures git automatically, so future clone / push need no further login.

Step 2 — Confirm sign-in

gh auth status

Step 3 — Set your commit identity (once)

Commits need your name and email. Replace the values below with your own:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Step 4 — Clone a project

gh repo clone your-account/your-repo

Deploy to GitHub Pages

GitHub Pages publishes a static website (e.g. a folder with just an index.html) to a free public URL. In Terminal, first go into your website folder, then run these in order.

Step 1 — Create a local history

git init
git add .
git commit -m "first site"

Step 2 — Create the GitHub repo and push

This one line creates a public repo, sets the remote, and pushes (replace my-site with the name you want):

gh repo create my-site --public --source=. --remote=origin --push

Step 3 — Turn on Pages

Option A (command):

gh api -X POST repos/{owner}/{repo}/pages -f "source[branch]=main" -f "source[path]=/"

Option B (web, more visual): go to the repo's Settings → Pages, set Branch to main and folder to / (root), then Save.

Verify (four tasks)

These four match the Module 1 verification tasks. Paste each command to codex, or run them yourself in Terminal.

Set up the Python project (Excel + Word)

uv init verify-python
cd verify-python
uv add openpyxl python-docx

Then ask the AI Agent to write a program: read an Excel and output a new one, then read a Word and output a modified version.

Start a local web server (JavaScript)

npx http-server

When you see a URL (e.g. http://127.0.0.1:8080), open it in a browser to confirm. Press Ctrl + C to stop.

Let Codex drive a browser (Playwright)

After confirming playwright is enabled in codex mcp list, ask Codex to open a page and screenshot it:

codex "Open https://example.com in a browser and save a full-page screenshot as example.png"

If the agent produces the screenshot, the browser plugin works.

Checklist

Run each command in Terminal; every line should print a version number (not "command not found").

code --version
git --version
node -v
npm -v
uv --version
gh --version
codex --version
codex mcp list

• VS Code opens, with Python / Jupyter / GitLens / ESLint / Codex extensions installed
• All seven commands above print a version or result
• codex mcp list shows playwright with status enabled
• codex signs in and the Hello, AI Agent test passes
• All four verification tasks (Excel, Word, local server, browser) succeed

Troubleshooting