From a30696f9bfefc58d640316c6a864c9bb255de690 Mon Sep 17 00:00:00 2001
From: Tyler Gannon <tyler@pagerguild.com>
Date: Tue, 3 Feb 2026 15:18:41 -0600
Subject: feat(plugin): add shell.env hook for manipulating environment in
 tools and shell (#12012)

---
 packages/web/src/content/docs/plugins.mdx | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

(limited to 'packages/web/src/content')

diff --git a/packages/web/src/content/docs/plugins.mdx b/packages/web/src/content/docs/plugins.mdx
index ba530a6d9..394fecc40 100644
--- a/packages/web/src/content/docs/plugins.mdx
+++ b/packages/web/src/content/docs/plugins.mdx
@@ -192,6 +192,10 @@ Plugins can subscribe to events as seen below in the Examples section. Here is a
 
 - `todo.updated`
 
+#### Shell Events
+
+- `shell.env`
+
 #### Tool Events
 
 - `tool.execute.after`
@@ -254,6 +258,23 @@ export const EnvProtection = async ({ project, client, $, directory, worktree })
 
 ---
 
+### Inject environment variables
+
+Inject environment variables into all shell execution (AI tools and user terminals):
+
+```javascript title=".opencode/plugins/inject-env.js"
+export const InjectEnvPlugin = async () => {
+  return {
+    "shell.env": async (input, output) => {
+      output.env.MY_API_KEY = "secret"
+      output.env.PROJECT_ROOT = input.cwd
+    },
+  }
+}
+```
+
+---
+
 ### Custom tools
 
 Plugins can also add custom tools to opencode:
-- 
cgit v1.2.3