feat: multi-location .env loading with last-wins merge strategy

Read .env from two locations and merge with cascading priority:
1. ~/.config/opencode/.env (global defaults)
2. <projectDir>/.opencode/.env (project overrides, wins)

BREAKING: .env values now override OS environment variables,
matching the opencode-cli convention (local overrides user).

Author: wagnert

AGENTS.md

@@ -111,7 +111,7 @@ import path from "path"
   This is intentional — the plugin must never crash or block OpenCode startup.
 - Use empty `catch {}` blocks (no error variable needed).
 - Return empty objects/records on failure, not `null` or `undefined`.
-- Never overwrite existing environment variables (`if (!(key in target))`).
+- Last Wins: `.env` values intentionally override existing environment variables.
 
 ```typescript
 // Correct pattern for this plugin
@@ -127,27 +127,25 @@ try {
 
 The plugin has two phases, both in a single file:
 
-1. **Init phase** (runs once at plugin load): Reads `.env` → sets `process.env`
-2. **Hook phase** (runs on every shell invocation): Reads `.env` → sets `output.env`
+1. **Init phase** (runs once at plugin load): Reads global + project `.env` → merges (last wins) → sets `process.env`
+2. **Hook phase** (runs on every shell invocation): Reads global + project `.env` → merges → sets `output.env`
 
 ```typescript
 export const ShellEnvPlugin: Plugin = async (input) => {
-  // Phase 1: Init-time injection into process.env
-  const parsed = loadEnvFile(input.directory)
-  for (const [key, value] of Object.entries(parsed)) {
-    if (!(key in process.env)) {
-      process.env[key] = value
-    }
+  const projectDir = input.directory
+
+  // Phase 1: Merge global + project .env, inject into process.env (last wins)
+  const merged = loadMergedEnv(projectDir)
+  for (const [key, value] of Object.entries(merged)) {
+    process.env[key] = value
   }
 
   return {
-    // Phase 2: Shell-time injection via hook
+    // Phase 2: Shell-time injection via hook (re-reads .env on every invocation)
     "shell.env": async (_input, output) => {
-      const envVars = loadEnvFile(input.directory)
+      const envVars = loadMergedEnv(projectDir)
       for (const [key, value] of Object.entries(envVars)) {
-        if (!(key in output.env)) {
-          output.env[key] = value
-        }
+        output.env[key] = value
       }
     },
   }
@@ -156,12 +154,14 @@ export const ShellEnvPlugin: Plugin = async (input) => {
 
 ### Key Design Rules
 
-1. **Never overwrite** existing env vars — OS-level exports always take precedence.
-2. **Never throw** — all errors are silently caught and ignored.
-3. **No external dependencies** beyond `@opencode-ai/plugin` and Node.js built-ins.
-4. **Re-read `.env` on every shell invocation** — picks up changes without restart.
-5. **Read `.env` once at init** — populates `process.env` for downstream plugins.
-6. **Source lives in `src/`**, not `plugins/` — avoids conflicts with the opencode-link symlinker.
+1. **Last Wins** — `.env` values override OS environment variables. Project `.env` overrides global `.env`.
+2. **Two locations** — reads `~/.config/opencode/.env` (global) and `<projectDir>/.opencode/.env` (project).
+3. **Never throw** — all errors are silently caught and ignored.
+4. **No external dependencies** beyond `@opencode-ai/plugin` and Node.js built-ins.
+5. **Re-read `.env` on every shell invocation** — picks up changes without restart.
+6. **Read `.env` once at init** — populates `process.env` for downstream plugins.
+7. **Source lives in `src/`**, not `plugins/` — avoids conflicts with the opencode-link symlinker.
+8. **Global config path** — uses `os.homedir() + "/.config/opencode"`, consistent with opencode-cli.
 
 ### Skill Documents
 

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.2.0
+
+- **BREAKING:** Switch from "never overwrite" to "last wins" merge strategy
+  - `.env` values now override existing OS environment variables
+  - This matches the opencode-cli convention (local overrides user)
+- Add multi-location `.env` loading with cascading merge:
+  1. `~/.config/opencode/.env` — global defaults (user email, shared API keys)
+  2. `<projectDir>/.opencode/.env` — project-specific overrides (wins)
+- Refactor `loadEnvFile()` → `loadEnvFromPath()` + `loadMergedEnv()` + `getGlobalConfigDir()`
+- Update AGENTS.md, README.md, and skill document with new behavior
+
 ## 1.1.1
 
 - Fix skills directory structure for plugin linker compatibility

README.md

@@ -1,20 +1,31 @@
 # opencode-plugin-shell-env
 
-Loads `.opencode/.env` variables into OpenCode's shell environment and MCP server processes.
+Loads `.env` variables into OpenCode's shell environment, MCP server processes, and `process.env` for downstream plugins.
 
 ## Problem
 
-OpenCode's `opencode.json` supports environment variable references like `{env:N8N_MCP_BEARER_TOKEN}`, but these only resolve **OS-level environment variables** (i.e., variables exported in the shell). An `.opencode/.env` file is **not** read by default.
+OpenCode's `opencode.json` supports environment variable references like `{env:N8N_MCP_BEARER_TOKEN}`, but these only resolve **OS-level environment variables** (i.e., variables exported in the shell). An `.env` file is **not** read by default.
 
 ## Solution
 
-This plugin hooks into OpenCode's `shell.env` lifecycle event and injects variables from `<projectRoot>/.opencode/.env` into every shell command and MCP server process spawned by OpenCode.
+This plugin hooks into OpenCode's `shell.env` lifecycle event and injects variables from `.env` files into every shell command, MCP server process, and `process.env` for downstream plugins.
+
+### .env Loading Order (Last Wins)
+
+The plugin reads `.env` files from two locations and merges them — more specific sources override less specific ones:
+
+| Priority | Source | Purpose |
+|----------|--------|---------|
+| 1 (base) | `~/.config/opencode/.env` | Global defaults (user email, shared API keys) |
+| 2 (wins) | `<projectDir>/.opencode/.env` | Project-specific overrides |
+
+Both layers **override** existing OS environment variables. If a key appears in both files, the project-level value wins.
 
 ### Behavior
 
-- Reads `<projectRoot>/.opencode/.env` on every shell invocation
-- **Does NOT overwrite** variables already present in the environment
-- Silently skips if `.opencode/.env` is missing or unreadable
+- Reads both `.env` files at init and on every shell invocation
+- **Last Wins:** project `.env` > global `.env` > OS environment
+- Silently skips missing or unreadable `.env` files
 - Parses standard `.env` syntax
 
 ### Supported `.env` Syntax

skills/shell-env/shell-env-usage/SKILL.md

@@ -14,11 +14,20 @@ metadata:
 
 ## Overview
 
-The `shell-env` plugin loads environment variables from `.opencode/.env` and makes them available in two ways:
+The `shell-env` plugin loads environment variables from `.env` files and makes them available in two ways:
 
 1. **`process.env`** (at plugin init) — for all plugins loaded after `shell-env`
 2. **`shell.env` hook** (on every shell invocation) — for shell commands and MCP server processes
 
+The plugin reads `.env` files from **two locations** and merges them with a "last wins" strategy:
+
+| Priority | Source | Purpose |
+|----------|--------|---------|
+| 1 (base) | `~/.config/opencode/.env` | Global defaults (user email, shared API keys) |
+| 2 (wins) | `<projectDir>/.opencode/.env` | Project-specific overrides |
+
+Both layers **override** existing OS environment variables. If a key appears in both files, the project-level value wins. This matches the "last wins" convention used by the opencode-cli plugin discovery (local overrides user).
+
 This eliminates the need for each plugin to implement its own `.env` file parsing.
 
 ## When to Use This Skill
@@ -33,36 +42,50 @@ This eliminates the need for each plugin to implement its own `.env` file parsin
 
 ### Phase 1: Plugin Initialization (`process.env`)
 
-When OpenCode loads the `shell-env` plugin, it reads `.opencode/.env` and injects all variables into `process.env` **before** subsequent plugins are initialized.
+When OpenCode loads the `shell-env` plugin, it reads `.env` files from both locations, merges them (last wins), and injects all variables into `process.env` **before** subsequent plugins are initialized.
 
 ```
 Plugin loading order (.opencode/package.json dependencies):
-  1. shell-env        ← reads .env, sets process.env
+  1. shell-env        ← reads global + project .env, sets process.env
   2. time-tracking    ← can read process.env.OPENCODE_USER_EMAIL
   3. other-plugin     ← can read process.env.MY_SECRET
 ```
 
 **Rules:**
-- Existing `process.env` values are **never overwritten** (OS-level exports take precedence)
-- If `.opencode/.env` is missing or unreadable, the plugin silently continues
+- `.env` values **override** existing OS environment variables (last wins)
+- Project `.env` overrides global `.env` for the same key
+- If either `.env` file is missing or unreadable, the plugin silently continues
 - Variables are available immediately after plugin init — no async delay
 
 ### Phase 2: Shell Execution (`shell.env` hook)
 
-On every shell command or MCP server process, the plugin re-reads `.opencode/.env` and injects variables into the shell environment.
+On every shell command or MCP server process, the plugin re-reads both `.env` files and injects merged variables into the shell environment.
 
 ```
 Shell command execution:
   1. OpenCode calls "shell.env" hook
-  2. shell-env injects .env variables into output.env
-  3. Shell command runs with merged environment
+  2. shell-env reads global + project .env, merges (last wins)
+  3. Merged variables injected into output.env
+  4. Shell command runs with merged environment
 ```
 
 **Rules:**
 - Re-reads `.env` on every invocation (picks up changes without restart)
-- Existing shell environment variables are **never overwritten**
+- `.env` values **override** existing shell environment variables
 - MCP servers configured in `opencode.json` see the variables via `{env:KEY}`
 
+### Global vs. Project `.env`
+
+```
+~/.config/opencode/.env          ← shared across all projects
+  OPENCODE_USER_EMAIL=user@example.com
+  TEMPO_API_TOKEN=tempo_xyz789
+
+<projectDir>/.opencode/.env      ← project-specific, overrides global
+  N8N_MCP_BEARER_TOKEN=n8n_api_abc123
+  OPENCODE_USER_EMAIL=other@example.com   ← wins over global
+```
+
 ## Configuration
 
 ### Prerequisites
@@ -225,7 +248,7 @@ Without `shell-env`, `{env:N8N_MCP_BEARER_TOKEN}` only resolves if the variable
 |---------|-------|----------|
 | `process.env.KEY` is `undefined` | shell-env loaded after the plugin | Move shell-env to first position in `.opencode/package.json` dependencies |
 | `process.env.KEY` is `undefined` | `.opencode/.env` file missing | Create `.opencode/.env` with the variable |
-| `process.env.KEY` has wrong value | OS-level export overrides `.env` | Remove the OS-level export or update it |
+| `process.env.KEY` has wrong value | Project `.env` overrides global `.env` and OS exports | Check both `~/.config/opencode/.env` and `.opencode/.env` |
 | MCP server doesn't see variable | shell-env not installed | Install and link the plugin |
 
 ### Variable not available in MCP server

src/shell-env.ts

@@ -1,11 +1,12 @@
 import type { Plugin } from "@opencode-ai/plugin"
 import fs from "fs"
+import os from "os"
 import path from "path"
 
 /**
  * ShellEnvPlugin - Loads .env variables into OpenCode's process and shell environment.
  *
- * This plugin provides environment variables from `.opencode/.env` to:
+ * This plugin provides environment variables from `.env` files to:
  *
  * 1. **process.env** (at plugin init) — so that subsequent plugins loaded after
  *    this one can read the variables via `process.env.KEY`. This eliminates the
@@ -19,10 +20,25 @@ import path from "path"
  * time-tracking plugin reads OPENCODE_USER_EMAIL from process.env, and the n8n
  * MCP server reads N8N_MCP_BEARER_TOKEN via the shell.env hook.
  *
- * Behavior:
- * - Reads `<projectRoot>/.opencode/.env` once at init and on every shell invocation
- * - Does NOT overwrite variables already present in the environment
- * - Silently skips if `.opencode/.env` is missing or unreadable
+ * ## .env Loading Order (Last Wins)
+ *
+ * The plugin reads `.env` files from two locations and merges them with a
+ * "last wins" strategy — more specific sources override less specific ones:
+ *
+ * | Priority | Source                          | Purpose                              |
+ * |----------|---------------------------------|--------------------------------------|
+ * | 1 (base) | `~/.config/opencode/.env`       | Global defaults (user email, shared keys) |
+ * | 2 (wins) | `<projectDir>/.opencode/.env`   | Project-specific overrides           |
+ *
+ * Both layers override existing OS environment variables. If a key appears in
+ * both files, the project-level value wins. This matches the "last wins"
+ * convention used by the opencode-cli plugin discovery (local overrides user).
+ *
+ * ## Behavior
+ *
+ * - Reads both `.env` files once at init and on every shell invocation
+ * - Last Wins: project `.env` overrides global `.env` overrides OS env
+ * - Silently skips missing or unreadable `.env` files
  *
  * **Important:** This plugin must be listed BEFORE other plugins in the OpenCode
  * configuration so that `process.env` is populated before they initialize.
@@ -34,7 +50,7 @@ import path from "path"
  */
 
 /**
- * Parses a .env file and returns a Record of key-value pairs.
+ * Parses a .env file content string and returns a Record of key-value pairs.
  *
  * Supports:
  * - KEY=VALUE
@@ -101,12 +117,10 @@ function parseDotenv(content: string): Record<string, string> {
 }
 
 /**
- * Reads the .env file and returns the parsed variables.
+ * Reads a .env file from the given path and returns the parsed variables.
  * Returns an empty record if the file is missing or unreadable.
  */
-function loadEnvFile(projectDir: string): Record<string, string> {
-  const envPath = path.join(projectDir, ".opencode", ".env")
-
+function loadEnvFromPath(envPath: string): Record<string, string> {
   if (!fs.existsSync(envPath)) {
     return {}
   }
@@ -120,28 +134,62 @@ function loadEnvFile(projectDir: string): Record<string, string> {
   }
 }
 
+/**
+ * Returns the global OpenCode config directory path.
+ *
+ * Uses the same convention as opencode-cli:
+ *   os.homedir() + "/.config/opencode"
+ *
+ * No XDG_CONFIG_HOME or platform-specific logic — consistent with opencode-cli.
+ */
+function getGlobalConfigDir(): string {
+  return path.join(os.homedir(), ".config", "opencode")
+}
+
+/**
+ * Merges .env variables from global and project locations using "last wins".
+ *
+ * Loading order (later entries override earlier ones):
+ *   1. ~/.config/opencode/.env         (global defaults)
+ *   2. <projectDir>/.opencode/.env     (project overrides)
+ *
+ * @param projectDir - The project working directory (input.directory)
+ * @returns Merged key-value record with project values winning over global
+ */
+function loadMergedEnv(projectDir: string): Record<string, string> {
+  const globalEnvPath = path.join(getGlobalConfigDir(), ".env")
+  const projectEnvPath = path.join(projectDir, ".opencode", ".env")
+
+  const globalEnv = loadEnvFromPath(globalEnvPath)
+  const projectEnv = loadEnvFromPath(projectEnvPath)
+
+  // Spread merge: project values override global values (last wins)
+  return { ...globalEnv, ...projectEnv }
+}
+
 export const ShellEnvPlugin: Plugin = async (input) => {
   const projectDir = input.directory
 
-  // Phase 1: Inject .env variables into process.env at plugin init time.
+  // Phase 1: Inject merged .env variables into process.env at plugin init time.
   // This makes them available to all plugins loaded AFTER this one via
   // process.env, eliminating the need for each plugin to parse .env itself.
-  const parsed = loadEnvFile(projectDir)
-  for (const [key, value] of Object.entries(parsed)) {
-    if (!(key in process.env)) {
-      process.env[key] = value
-    }
+  //
+  // Last Wins: .env values OVERRIDE existing OS environment variables.
+  // This is intentional — explicit .env configuration takes precedence
+  // over inherited shell environment, matching the opencode-cli convention.
+  const merged = loadMergedEnv(projectDir)
+  for (const [key, value] of Object.entries(merged)) {
+    process.env[key] = value
   }
 
   return {
-    // Phase 2: Inject .env variables into shell execution environment.
+    // Phase 2: Inject merged .env variables into shell execution environment.
     // This makes them available to shell commands and MCP server processes.
+    // Re-reads .env files on every invocation to pick up changes without restart.
     "shell.env": async (_input, output) => {
-      const envVars = loadEnvFile(projectDir)
+      const envVars = loadMergedEnv(projectDir)
       for (const [key, value] of Object.entries(envVars)) {
-        if (!(key in output.env)) {
-          output.env[key] = value
-        }
+        output.env[key] = value
       }
     },
   }