Local (localwp.com) + direnv + VS Code

This guide wires up Local (localwp.com) with direnv so your terminal & VS Code always use the correct WordPress environment for each Local site. It includes:

Installing the Local direnv add‑on from the 1.0.0 release tarball.
Shell hook instructions for macOS, Windows, and Linux.

Why do you need this?

When vibe coding in VS Code or similar, AI tends to want to do wp cli commands, direnv and a correct .envrc will make this possible.

1) Prereqs

Local v5+ installed.
direnv installed:
- macOS (Homebrew): brew install direnv
- Linux: use your distro package manager (e.g., sudo apt install direnv, sudo dnf install direnv, or sudo pacman -S direnv)
- Windows (recommended: Git Bash or PowerShell):
  - Scoop: scoop install direnv
  - Chocolatey: choco install direnv

After installing, you must hook direnv into your shell (next sections).

2) Install the Local direnv add‑on from the release tarball

You should download the packaged add‑on and place it in Local’s add‑ons folder. When extracted, the archive creates a packages folder — rename it to local-addon-direnv.

2.1. Find your Local add‑ons folder

macOS: ~/Library/Application Support/Local/addons
Windows: %APPDATA%\Local\addons (typically C:\Users\<you>\AppData\Roaming\Local\addons)
Linux: ~/.config/Local/addons

If the addons folder does not exist yet, create it.

2.2. Download the release tarball

URL: https://github.com/gravitywiz/local-addon-direnv/releases/download/1.0.0/direnv-1.0.0.tgz

macOS / Linux (terminal):

# Choose a download location, e.g. ~/Downloads
cd ~/Downloads
curl -LO https://github.com/gravitywiz/local-addon-direnv/releases/download/1.0.0/direnv-1.0.0.tgz

Windows:

Easiest: download with your browser to Downloads.

Or PowerShell:

cd $env:USERPROFILE\Downloads
Invoke-WebRequest -Uri https://github.com/gravitywiz/local-addon-direnv/releases/download/1.0.0/direnv-1.0.0.tgz -OutFile direnv-1.0.0.tgz

2.3. Extract and rename to `local-addon-direnv`

The archive extracts to a folder named packages. You must rename it to local-addon-direnv before installing/enabling in Local.

macOS (Terminal):

cd ~/Downloads
tar -xzf direnv-1.0.0.tgz
# A folder named "packages" appears; move it into Local's add-ons and rename:
mv packages ~/Library/Application\ Support/Local/addons/local-addon-direnv

Linux (Terminal):

cd ~/Downloads
tar -xzf direnv-1.0.0.tgz
mv packages ~/.config/Local/addons/local-addon-direnv

Windows (PowerShell):

cd $env:USERPROFILE\Downloads
# If 'tar' is available (Win10/11 usually has bsdtar):
tar -xzf direnv-1.0.0.tgz
# Move & rename into Local's add-ons folder:
Move-Item -Force .\packages "$env:APPDATA\Local\addons\local-addon-direnv"

If tar is unavailable, extract with 7‑Zip (GUI) or File Explorer (using a helper like 7‑Zip). After extracting, manually move the resulting packages folder into %APPDATA%\Local\addons\ and rename it to local-addon-direnv.

2.4. Enable the add‑on in Local

Open Local → Add‑ons → Install from disk, select the local-addon-direnv folder you just placed, and Enable it.

What it does: On site create/start, the add‑on generates a site‑specific .envrc in <site>/app/ that sets environment variables so WP‑CLI and other tools automatically target that Local site (even outside “Open Site Shell”).

3) Hook direnv into your shell (per OS) — if not already done

Pick your shell and add the corresponding hook line to your shell config. Then restart the shell.

macOS

zsh (default on macOS): add to ~/.zshrc
```
eval "$(direnv hook zsh)"
```
bash: add to ~/.bashrc
```
eval "$(direnv hook bash)"
```
fish: add to ~/.config/fish/config.fish
```
direnv hook fish | source
```

Linux

bash: add to ~/.bashrc
```
eval "$(direnv hook bash)"
```
zsh: add to ~/.zshrc
```
eval "$(direnv hook zsh)"
```
fish: add to ~/.config/fish/config.fish
```
direnv hook fish | source
```

Windows

You have a few good options. Choose one:

Git Bash (recommended on Windows): edit ~/.bashrc
```
eval "$(direnv hook bash)"
```
PowerShell (advanced/experimental): add a hook to your PowerShell profile so it loads for every session. In PowerShell, run:
```
if (!(Test-Path -LiteralPath $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force | Out-Null }
Add-Content -Path $PROFILE -Value 'Invoke-Expression (direnv hook powershell)'
# Then restart PowerShell
```
Notes:
- direnv evaluates .envrc with a bash sub-shell. Ensure Git Bash or WSL is installed and available if your .envrc uses bash syntax (most do).
- If you hit issues with PowerShell hooks, use Git Bash as your VS Code terminal for best compatibility.

4) Start your Local site and allow the `.envrc`

cd "/path/to/Local Sites/<site>/app"
direnv status    # expect: ".envrc is blocked"
direnv allow
wp option get home   # should print your Local site URL

If the URL matches your Local site, everything is wired up.

5) Make VS Code pick up the same environment

Option A — VS Code “direnv” extension

Install the direnv extension.
Open <site>/app in VS Code; when prompted, Allow the .envrc.
- Optional, in direnv settings: "direnv.restart.automatic": true // Automatically restart the direnv process when changes are detected
The Integrated Terminal (and shell-type tasks) inherit the environment.

Option B — Launch VS Code from a direnv-enabled shell

cd "/path/to/Local Sites/<site>/app"
code .

VS Code will inherit the environment from the current shell.

Windows tip: In VS Code, set your default Integrated Terminal shell to Git Bash for the best direnv experience on Windows.

6) Day‑to‑day usage

From anywhere under <site>/app (theme, plugin, etc.):

wp option get siteurl
wp plugin list

No need to use “Open Site Shell”—the environment is already wired up by direnv.

7) Optional: extend per plugin/theme (keep the add‑on as source of truth)

If you work inside a plugin/theme folder, layer a local .envrc that sources the site‑level one:

# <site>/app/public/wp-content/plugins/my-plugin/.envrc
source_up        # pull in the site-level .envrc from app/
export WP_ENV=local

Then:

direnv allow

8) Troubleshooting tips

Edited a .envrc? Run direnv allow again (or VS Code: “Direnv: Allow/Reload environment”).
VS Code not picking it up? Ensure you installed the “direnv” extension and clicked Allow for the workspace’s .envrc; or reopen VS Code from <site>/app after direnv allow.
On Windows PowerShell, if variables don’t load, switch the VS Code terminal to Git Bash or use WSL for full compatibility.
Need to re-run the zsh fix? Return to Step 1.

That’s it! Your shell and VS Code should now “just know” which Local WordPress site you’re in, so wp, PHP tools, and scripts behave correctly per-site.

soderlind/local-direnv-vscode-setup.md