diff --git a/.envrc b/.envrc
new file mode 100644
index 0000000..63e22a3
--- /dev/null
+++ b/.envrc
@@ -0,0 +1 @@
+layout python python3.13
diff --git a/.gitignore b/.gitignore
index 947d73e..6ef3e46 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,7 @@
 .worktrees/
 .claude/
 .venv/
+.direnv/
 .pytest_cache/
 __pycache__/
 *.pyc
diff --git a/AGENTS.md b/AGENTS.md
index b29f4b8..4fff97e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,6 +21,7 @@ Do not invent architecture outside these plans unless explicitly requested.
 ### Workspace and tools
 
 - Do not use git worktrees.
+- Local Python venv is direnv-managed via `.envrc` (Python 3.13). After fresh checkout: `direnv allow`, then `pip install -e ./l4d2host -e ./l4d2web pytest`. See README **Local development** for details.
 
 ### Naming and boundaries
 
diff --git a/README.md b/README.md
index 67fe5ff..15266a2 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,15 @@ Implementation plans remain the source of truth for architecture and task sequen
 
 See `deploy/README.md` for the Linux test deployment contract, including the runtime user, target filesystem layout, systemd units, privileged helpers, sudoers rules, admin bootstrap, and overlay reference rules.
 
+## Local development
+
+This repo uses [direnv](https://direnv.net/) to auto-activate a Python 3.13 venv on `cd` (matching the Debian Trixie production target). With direnv installed and hooked into your shell:
+
+1. `direnv allow` once per fresh checkout (and after any `.envrc` change).
+2. `cd` out and back in — `.direnv/python-3.13/` is created and put on `PATH`.
+3. `pip install -e ./l4d2host -e ./l4d2web` to install both packages editable.
+4. `pip install pytest` to run the test suites (`pytest tests/` inside either subproject).
+
 ## Tech Stack (planned)
 
 - Python 3.12+