diff --git a/.changeset/headless-docs-url.md b/.changeset/headless-docs-url.md
new file mode 100644
index 00000000000..092f30f5f92
--- /dev/null
+++ b/.changeset/headless-docs-url.md
@@ -0,0 +1,5 @@
+---
+"@kilocode/cli": patch
+---
+
+Show the docs URL in an alert dialog when the browser cannot be opened on headless systems instead of silently failing.
diff --git a/packages/opencode/src/cli/cmd/tui/app.tsx b/packages/opencode/src/cli/cmd/tui/app.tsx
index 80b70b2e837..ffe7e86cb6c 100644
--- a/packages/opencode/src/cli/cmd/tui/app.tsx
+++ b/packages/opencode/src/cli/cmd/tui/app.tsx
@@ -685,8 +685,15 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {
         name: "docs.open",
         title: "Open docs",
         run: () => {
-          open(KiloApp.DOCS_URL).catch(() => {}) // kilocode_change
           dialog.clear()
+          open(KiloApp.DOCS_URL).catch(() => {
+            dialog.replace(() => (
+              <DialogAlert
+                title="Cannot open browser"
+                message={`No display detected.\n\nOpen the docs manually:\n${KiloApp.DOCS_URL}`}
+              />
+            ))
+          }) // kilocode_change
         },
         category: "System",
       },