diff --git a/package-lock.json b/package-lock.json
index 9ab4479..00dd9fa 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -11118,8 +11118,13 @@
             "dependencies": {
                 "@page-agent/llms": "1.4.4",
                 "@page-agent/page-controller": "1.4.4",
-                "chalk": "^5.6.2",
+                "chalk": "^5.6.2"
+            },
+            "devDependencies": {
                 "zod": "^4.3.5"
+            },
+            "peerDependencies": {
+                "zod": "^3.25.0 || ^4.0.0"
             }
         },
         "packages/extension": {
@@ -11132,8 +11137,7 @@
                 "@page-agent/page-controller": "1.4.4",
                 "@page-agent/ui": "1.4.4",
                 "ai-motion": "^0.4.8",
-                "chalk": "^5.6.2",
-                "zod": "^4.3.5"
+                "chalk": "^5.6.2"
             },
             "devDependencies": {
                 "@radix-ui/react-hover-card": "^1.1.15",
@@ -11162,6 +11166,9 @@
                 "tailwindcss": "^4.1.14",
                 "tw-animate-css": "^1.4.0",
                 "wxt": "^0.20.18"
+            },
+            "peerDependencies": {
+                "zod": "^3.25.0 || ^4.0.0"
             }
         },
         "packages/llms": {
@@ -11169,8 +11176,13 @@
             "version": "1.4.4",
             "license": "MIT",
             "dependencies": {
-                "chalk": "^5.6.2",
+                "chalk": "^5.6.2"
+            },
+            "devDependencies": {
                 "zod": "^4.3.5"
+            },
+            "peerDependencies": {
+                "zod": "^3.25.0 || ^4.0.0"
             }
         },
         "packages/page-agent": {
@@ -11181,8 +11193,13 @@
                 "@page-agent/llms": "1.4.4",
                 "@page-agent/page-controller": "1.4.4",
                 "@page-agent/ui": "1.4.4",
-                "chalk": "^5.6.2",
+                "chalk": "^5.6.2"
+            },
+            "devDependencies": {
                 "zod": "^4.3.5"
+            },
+            "peerDependencies": {
+                "zod": "^3.25.0 || ^4.0.0"
             }
         },
         "packages/page-controller": {
diff --git a/packages/core/package.json b/packages/core/package.json
index 4d89cf2..1b8f3f8 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -44,8 +44,13 @@
     },
     "dependencies": {
         "chalk": "^5.6.2",
-        "zod": "^4.3.5",
         "@page-agent/llms": "1.4.4",
         "@page-agent/page-controller": "1.4.4"
+    },
+    "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
+    },
+    "devDependencies": {
+        "zod": "^4.3.5"
     }
 }
diff --git a/packages/core/src/PageAgentCore.ts b/packages/core/src/PageAgentCore.ts
index cc1f418..5f2d35e 100644
--- a/packages/core/src/PageAgentCore.ts
+++ b/packages/core/src/PageAgentCore.ts
@@ -5,7 +5,7 @@
 import { InvokeError, LLM, type Tool } from '@page-agent/llms'
 import type { BrowserState, PageController } from '@page-agent/page-controller'
 import chalk from 'chalk'
-import * as z from 'zod'
+import * as z from 'zod/v4'
 
 import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
 import { tools } from './tools'
diff --git a/packages/core/src/tools/index.ts b/packages/core/src/tools/index.ts
index 69bfbfb..1fcd856 100644
--- a/packages/core/src/tools/index.ts
+++ b/packages/core/src/tools/index.ts
@@ -2,7 +2,7 @@
  * Internal tools for PageAgent.
  * @note Adapted from browser-use
  */
-import * as z from 'zod'
+import * as z from 'zod/v4'
 
 import type { PageAgentCore } from '../PageAgentCore'
 import { waitFor } from '../utils'
diff --git a/packages/core/src/utils/autoFixer.ts b/packages/core/src/utils/autoFixer.ts
index 732189a..d4be0f5 100644
--- a/packages/core/src/utils/autoFixer.ts
+++ b/packages/core/src/utils/autoFixer.ts
@@ -1,6 +1,6 @@
 import { InvokeError, InvokeErrorType } from '@page-agent/llms'
 import chalk from 'chalk'
-import * as z from 'zod'
+import * as z from 'zod/v4'
 
 import type { PageAgentTool } from '../tools'
 
diff --git a/packages/core/vite.config.js b/packages/core/vite.config.js
index d64ca2d..f8d58a1 100644
--- a/packages/core/vite.config.js
+++ b/packages/core/vite.config.js
@@ -30,6 +30,7 @@ export default defineConfig({
 			external: [
 				'chalk',
 				'zod',
+				'zod/v4',
 				// all the internal packages
 				/^@page-agent\//,
 			],
diff --git a/packages/extension/package.json b/packages/extension/package.json
index 136ea86..2444365 100644
--- a/packages/extension/package.json
+++ b/packages/extension/package.json
@@ -43,7 +43,9 @@
         "@page-agent/page-controller": "1.4.4",
         "@page-agent/ui": "1.4.4",
         "ai-motion": "^0.4.8",
-        "chalk": "^5.6.2",
-        "zod": "^4.3.5"
+        "chalk": "^5.6.2"
+    },
+    "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
     }
 }
diff --git a/packages/extension/src/agent/tabTools.ts b/packages/extension/src/agent/tabTools.ts
index 371b14f..25fe1db 100644
--- a/packages/extension/src/agent/tabTools.ts
+++ b/packages/extension/src/agent/tabTools.ts
@@ -6,7 +6,7 @@
  * - switch_to_tab: Switch to an existing tab
  * - close_tab: Close a tab (optionally switch to another)
  */
-import * as z from 'zod'
+import * as z from 'zod/v4'
 
 import type { TabsController } from './TabsController'
 
diff --git a/packages/llms/package.json b/packages/llms/package.json
index dbd2391..ed01acc 100644
--- a/packages/llms/package.json
+++ b/packages/llms/package.json
@@ -37,7 +37,12 @@
         "postpublish": "node -e \"['LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
     },
     "dependencies": {
-        "chalk": "^5.6.2",
+        "chalk": "^5.6.2"
+    },
+    "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
+    },
+    "devDependencies": {
         "zod": "^4.3.5"
     }
 }
diff --git a/packages/llms/src/OpenAIClient.ts b/packages/llms/src/OpenAIClient.ts
index 87fbb51..b78ba44 100644
--- a/packages/llms/src/OpenAIClient.ts
+++ b/packages/llms/src/OpenAIClient.ts
@@ -1,7 +1,7 @@
 /**
  * OpenAI Client implementation
  */
-import * as z from 'zod'
+import * as z from 'zod/v4'
 
 import { InvokeError, InvokeErrorType } from './errors'
 import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
diff --git a/packages/llms/src/types.ts b/packages/llms/src/types.ts
index fff25e0..857375a 100644
--- a/packages/llms/src/types.ts
+++ b/packages/llms/src/types.ts
@@ -1,7 +1,7 @@
 /**
  * Core types for LLM integration
  */
-import type * as z from 'zod'
+import type * as z from 'zod/v4'
 
 /**
  * Message format - OpenAI standard (industry standard)
diff --git a/packages/llms/src/utils.ts b/packages/llms/src/utils.ts
index 4320e7a..a8d9589 100644
--- a/packages/llms/src/utils.ts
+++ b/packages/llms/src/utils.ts
@@ -2,7 +2,7 @@
  * Utility functions for LLM integration
  */
 import chalk from 'chalk'
-import * as z from 'zod'
+import * as z from 'zod/v4'
 
 import type { Tool } from './types'
 
diff --git a/packages/llms/vite.config.js b/packages/llms/vite.config.js
index 420b9c0..13e599e 100644
--- a/packages/llms/vite.config.js
+++ b/packages/llms/vite.config.js
@@ -25,7 +25,7 @@ export default defineConfig({
 		},
 		outDir: resolve(__dirname, 'dist', 'lib'),
 		rollupOptions: {
-			external: ['chalk', 'zod'],
+			external: ['chalk', 'zod', 'zod/v4'],
 		},
 		minify: false,
 		sourcemap: true,
diff --git a/packages/page-agent/package.json b/packages/page-agent/package.json
index 381c2e5..c3e6ee8 100644
--- a/packages/page-agent/package.json
+++ b/packages/page-agent/package.json
@@ -48,7 +48,12 @@
         "@page-agent/llms": "1.4.4",
         "@page-agent/page-controller": "1.4.4",
         "@page-agent/ui": "1.4.4",
-        "chalk": "^5.6.2",
+        "chalk": "^5.6.2"
+    },
+    "peerDependencies": {
+        "zod": "^3.25.0 || ^4.0.0"
+    },
+    "devDependencies": {
         "zod": "^4.3.5"
     }
 }
diff --git a/packages/page-agent/vite.config.js b/packages/page-agent/vite.config.js
index bc210ec..fe286b1 100644
--- a/packages/page-agent/vite.config.js
+++ b/packages/page-agent/vite.config.js
@@ -30,6 +30,7 @@ export default defineConfig({
 			external: [
 				'chalk',
 				'zod',
+				'zod/v4',
 				// all the internal packages
 				/^@page-agent\//,
 			],