From 42b25a2cb59cf6d95df35e44977bfc9ce62925a1 Mon Sep 17 00:00:00 2001
From: Hunter Bown <hmbown@gmail.com>
Date: Sun, 31 May 2026 02:27:32 -0700
Subject: [PATCH] docs: add macos python FAQ (#2409)

Harvested from #2407 with thanks to @axobase001.

Adds a first-time macOS Python FAQ and completes the virtualenv flow with the final run command.

Fixes #2351.
---
 docs/GUIDE.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/GUIDE.md b/docs/GUIDE.md
index 60362570..fa58b696 100644
--- a/docs/GUIDE.md
+++ b/docs/GUIDE.md
@@ -453,6 +453,32 @@ Approvals are part of the safety model. Shell commands, paid tools, writes, and
 actions outside the expected workspace can have side effects. Approval prompts
 let you keep control while still letting the model do useful work.
 
+### How do I run a Python file on macOS?
+
+Open Terminal in the folder that contains the file and run:
+
+```bash
+python3 your_file.py
+```
+
+If macOS says `python3` is missing, install Python from
+[python.org](https://www.python.org/downloads/macos/) or with Homebrew:
+
+```bash
+brew install python
+```
+
+Inside CodeWhale, ask the agent to inspect the file and run it with
+`python3 your_file.py`. If the script needs packages, install them in a virtual
+environment first:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -r requirements.txt
+python3 your_file.py
+```
+
 ### Where is my config stored?
 
 New CodeWhale config uses `~/.codewhale/config.toml`. Legacy