diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..96de0ff
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,17 @@
+# BlockSmith Environment Variables
+#
+# This file is automatically copied to .env when you first run direnv allow.
+# Edit .env (not this file) with your actual API keys.
+
+# Required: Gemini API Key (default provider)
+# Get yours at: https://aistudio.google.com/apikey
+# GEMINI_API_KEY=your-gemini-api-key-here
+
+# Optional: OpenAI API Key (if using OpenAI models)
+# Get yours at: https://platform.openai.com/api-keys
+# OPENAI_API_KEY=your-openai-api-key-here
+
+# Optional: Blender path (only needed for GLB/GLTF export)
+# Uncomment and set if blender is not in your PATH
+# BLENDER_PATH=/Applications/Blender.app/Contents/MacOS/Blender  # macOS
+# BLENDER_PATH=/usr/bin/blender  # Linux
diff --git a/.envrc b/.envrc
new file mode 100644
index 0000000..3bb5416
--- /dev/null
+++ b/.envrc
@@ -0,0 +1,26 @@
+# BlockSmith direnv configuration
+#
+# This file automatically sets up your environment when you cd into the repo.
+#
+# First time setup:
+#   1. Install direnv: https://direnv.net/docs/installation.html
+#   2. Run: direnv allow
+#   3. Edit .env with your actual API keys
+#
+# direnv will automatically create .env from .env.example if it doesn't exist.
+
+# Auto-create .env from example if it doesn't exist
+if [ ! -f .env ]; then
+  if [ -f .env.example ]; then
+    echo "Creating .env from .env.example..."
+    cp .env.example .env
+    echo "✓ Created .env - please edit it with your API keys"
+  else
+    echo "⚠️  Warning: .env.example not found"
+    echo "Please ensure you have the template file or create .env manually"
+    exit 1
+  fi
+fi
+
+# Load environment variables from .env
+dotenv .env
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index a3b900e..f4f3064 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -2,6 +2,46 @@
 
 Quick guide for testing BlockSmith locally before it's published to PyPI.
 
+## Environment Setup (Recommended: direnv)
+
+For a better development experience, use **direnv** to automatically manage environment variables:
+
+**Install direnv:**
+```bash
+# macOS
+brew install direnv
+
+# Linux (Ubuntu/Debian)
+sudo apt install direnv
+
+# Add to your shell (~/.bashrc, ~/.zshrc, etc.)
+eval "$(direnv hook bash)"  # or zsh, fish, etc.
+```
+
+**Setup (automatic):**
+```bash
+cd blocksmith
+direnv allow  # Creates .env from template automatically
+```
+
+Edit `.env` with your actual API keys:
+```bash
+GEMINI_API_KEY=your-actual-key-here
+```
+
+**Benefits:**
+- ✅ Project-scoped (only loaded in this directory)
+- ✅ Auto-loads when entering repo, unloads when leaving
+- ✅ No need for manual `export` or `source` commands
+- ✅ `.env` is gitignored (prevents accidental commits)
+
+**Alternative (manual export):** If you prefer not to use direnv, you can manually export environment variables:
+```bash
+export GEMINI_API_KEY="your-key-here"
+```
+
+For detailed setup instructions, see the [main README](README.md#2-set-up-api-key).
+
 ## Quick Start (Using uv - Recommended)
 
 **uv** is much faster than pip/venv. Install it first:
@@ -23,13 +63,12 @@ uv venv
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 uv pip install -e .
 
-# Set your API key
-export GEMINI_API_KEY="your-key-here"
-
 # Test it!
 python examples/quickstart.py
 ```
 
+**Note:** Make sure you've configured your API key using the Environment Setup section above.
+
 ## Alternative: Standard pip/venv
 
 If you prefer the standard Python workflow:
@@ -44,13 +83,12 @@ source venv/bin/activate  # On Windows: venv\Scripts\activate
 # Install in editable mode
 pip install -e .
 
-# Set API key
-export GEMINI_API_KEY="your-key-here"
-
 # Test
 python examples/quickstart.py
 ```
 
+**Note:** Make sure you've configured your API key using the Environment Setup section above.
+
 ## Install Blender
 
 BlockSmith requires Blender for GLTF/GLB export:
@@ -88,6 +126,8 @@ export BLENDER_PATH="/usr/bin/blender"
 set BLENDER_PATH="C:\Program Files\Blender Foundation\Blender\blender.exe"
 ```
 
+If using direnv, add this to your `.env` file instead.
+
 ## Quick Test
 
 ```python
@@ -129,7 +169,19 @@ blocksmith/
 ## Troubleshooting
 
 ### "No API key found"
-Set your LLM API key:
+
+**If using direnv:**
+1. Make sure you ran `direnv allow`
+2. Check that `.env` exists and contains your key:
+   ```bash
+   cat .env  # Should show GEMINI_API_KEY=your-key
+   ```
+3. Verify it's loaded:
+   ```bash
+   echo $GEMINI_API_KEY  # Should print your key
+   ```
+
+**If using manual export:**
 ```bash
 export GEMINI_API_KEY="your-key"
 # or
diff --git a/README.md b/README.md
index f22e1e4..bc5604f 100644
--- a/README.md
+++ b/README.md
@@ -98,7 +98,43 @@ BlockSmith uses **Gemini 2.5 Pro** by default (best quality for block models).
 
 If you need help with this, let me know. OR, just use OpenAI, or even a free and local model if you want. If you run into a lot of issues with 429/rate limit errors, it's worth adding your billing info to get more use out of Gemini.
 
-**Set the environment variable:**
+**Configure your API key:**
+
+#### Option 1: direnv (Recommended)
+
+direnv automatically loads environment variables when you `cd` into the project:
+
+```bash
+# Install direnv
+# macOS
+brew install direnv
+
+# Linux (Ubuntu/Debian)
+sudo apt install direnv
+
+# Then add to your shell (~/.bashrc, ~/.zshrc, etc.)
+eval "$(direnv hook bash)"  # or zsh, fish, etc.
+```
+
+**Setup (automatic):**
+```bash
+cd blocksmith
+direnv allow  # Creates .env from template automatically
+```
+
+Then edit `.env` with your API key:
+```bash
+GEMINI_API_KEY=your-actual-key-here
+```
+
+That's it! Your keys are now:
+- ✅ Project-scoped (only loaded in this directory)
+- ✅ Auto-loaded when you `cd` into the repo
+- ✅ Never accidentally committed (`.env` is gitignored)
+
+#### Option 2: Shell RC file (Global)
+
+Add to your shell configuration file:
 
 ```bash
 # macOS/Linux - Add to ~/.bashrc or ~/.zshrc
@@ -119,7 +155,7 @@ set GEMINI_API_KEY=your-key-here
 echo $GEMINI_API_KEY  # Should print your key
 ```
 
-### 3. Install Blender (Optional)
+### 3. Install Blender (Optional, for GLB/GLTF only)
 
 **Skip this if you only need BBModel, JSON, or Python DSL formats!**
 
@@ -374,6 +410,19 @@ bs.generate("a tower").save("tower.glb")
 **Problem:** `Exception: No GEMINI_API_KEY found`
 
 **Solution:**
+
+**If using direnv:**
+1. Make sure you ran `direnv allow` in the project directory
+2. Check that `.env` exists and contains your key:
+   ```bash
+   cat .env  # Should show GEMINI_API_KEY=your-key
+   ```
+3. Verify it's loaded:
+   ```bash
+   echo $GEMINI_API_KEY  # Should print your key
+   ```
+
+**If using shell RC file:**
 1. Make sure you set the environment variable:
    ```bash
    export GEMINI_API_KEY="your-key-here"
diff --git a/examples/README.md b/examples/README.md
index 3930df6..148cd66 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -8,6 +8,14 @@ Make sure you have BlockSmith installed and your API key set:
 
 ```bash
 pip install blocksmith
+```
+
+**Set your API key:**
+
+**Option 1: direnv (Recommended)** - See [main README](../README.md#2-set-up-api-key) for setup
+
+**Option 2: Manual export**
+```bash
 export GEMINI_API_KEY="your-key-here"
 ```
 
diff --git a/tests/integration/README.md b/tests/integration/README.md
index e736458..2363544 100644
--- a/tests/integration/README.md
+++ b/tests/integration/README.md
@@ -16,7 +16,8 @@
 ## Running Integration Tests
 
 ```bash
-# Source your API key first
+# If using direnv, variables are already loaded (skip this step)
+# If NOT using direnv, load your API key first:
 source .env
 
 # Run all integration tests
@@ -29,6 +30,8 @@ pytest tests/integration/test_generation.py -v -s
 pytest tests/integration/test_generation.py::TestBasicGeneration::test_simple_generation -v -s
 ```
 
+**Note:** If you're using direnv (see [main README](../../README.md#2-set-up-api-key)), environment variables are automatically loaded when you `cd` into the repo - no need to run `source .env`.
+
 ## What Gets Tested
 
 - ✅ Basic model generation with real LLM