diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 00000000..f34031d1
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,35 @@
+# GitHub Copilot Development Environment
+
+**Primary agent instructions**: See [`AGENTS.md`](../AGENTS.md) for complete repository context.
+
+## Environment Setup
+
+GitHub Copilot agents use uv/Python (not Nix) because Nix causes Bash tool calls to hang. Setup is handled by `.github/workflows/copilot-setup-steps.yml`:
+
+```bash
+uv sync --extra dev
+```
+
+## Available Tools
+
+All tools must be run via `uv run`:
+
+| Tool | Command |
+|------|---------|
+| **pytest** | `uv run pytest tests/ -v` |
+| **ruff** | `uv run ruff check src/` |
+| **mypy** | `uv run mypy src/` |
+| **deepwork** | `uv run deepwork` |
+
+## Running Tests
+
+```bash
+# All tests
+uv run pytest tests/ -v
+
+# Specific test file
+uv run pytest tests/test_example.py -v
+
+# With coverage
+uv run pytest tests/ --cov=deepwork --cov-report=html
+```
diff --git a/.github/workflows/copilot-setup-steps.yml b/.github/workflows/copilot-setup-steps.yml
index 2e6004ed..e97cd89f 100644
--- a/.github/workflows/copilot-setup-steps.yml
+++ b/.github/workflows/copilot-setup-steps.yml
@@ -15,22 +15,49 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      # TODO this will cause all of copilot agents Bash tool calls to silently hang (which it won't complain about)
+      # NOTE: Nix would be the preferred environment, but it causes Copilot agent
+      # Bash tool calls to silently hang. Using uv/Python setup as a workaround.
       # - name: Install Nix
       #   uses: cachix/install-nix-action@v31
       #   with:
       #     nix_path: nixpkgs=channel:nixos-unstable
       # - uses: nicknovitski/nix-develop@v1
 
-      # - name: Cache UV dependencies
-      #   uses: actions/cache@v4
-      #   with:
-      #     path: |
-      #       ~/.cache/uv
-      #       .venv
-      #     key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
-      #     restore-keys: |
-      #       ${{ runner.os }}-uv-
-
-      # - name: Install dependencies
-      #   run: uv sync --extra dev
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Cache UV dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/uv
+            .venv
+          key: ${{ runner.os }}-uv-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Verify environment setup
+        run: |
+          echo "Python version:"
+          python --version
+          echo ""
+          echo "UV version:"
+          uv --version
+          echo ""
+          echo "Pytest available:"
+          uv run pytest --version
+          echo ""
+          echo "Ruff available:"
+          uv run ruff --version
+          echo ""
+          echo "Environment setup complete!"