local-direnv-vscode-setup.md

To make this the default in Local, please vote

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.
• Configure VS Code to inherit environment variables from the current Local shell session

Contents

• Why do you need this?
• Prereqs
• Install the Local direnv add‑on from the release tarball
• Hook direnv into your shell (per OS) — if not already done
• Start your Local site and allow the .envrc
• Make VS Code pick up the same environment
• Day‑to‑day usage
• Optional: extend per plugin/theme (keep the add‑on as source of truth)
• Troubleshooting tips

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.

Screenshot from debugging Read Offline

---

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 .

${\bf\large\color{red}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.