diff --git a/README.md b/README.md
index 3ebfb1627cf6..5dc45b964d6a 100644
--- a/README.md
+++ b/README.md
@@ -97,6 +97,22 @@ OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bas
 XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash
 ```
 
+#### Shell Completion
+
+OpenCode can generate shell completion scripts with `opencode completion`.
+
+```bash
+# Bash
+SHELL="$(command -v bash)" opencode completion >> ~/.bashrc
+source ~/.bashrc
+
+# Zsh
+SHELL="$(command -v zsh)" opencode completion >> ~/.zshrc
+source ~/.zshrc
+```
+
+On macOS, you may want to use `~/.bash_profile` or `~/.zprofile` instead.
+
 ### Agents
 
 OpenCode includes two built-in agents you can switch between with the `Tab` key.
diff --git a/README.zh.md b/README.zh.md
index 46d9f761cbd0..9219c49346fd 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -97,6 +97,22 @@ OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bas
 XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash
 ```
 
+#### Shell 补全
+
+OpenCode 支持通过 `opencode completion` 生成 shell 补全脚本。
+
+```bash
+# Bash
+SHELL="$(command -v bash)" opencode completion >> ~/.bashrc
+source ~/.bashrc
+
+# Zsh
+SHELL="$(command -v zsh)" opencode completion >> ~/.zshrc
+source ~/.zshrc
+```
+
+在 macOS 上，你可能更想写入 `~/.bash_profile` 或 `~/.zprofile`。
+
 ### Agents
 
 OpenCode 内置两种 Agent，可用 `Tab` 键快速切换：
diff --git a/packages/opencode/src/cli/completion.ts b/packages/opencode/src/cli/completion.ts
new file mode 100644
index 000000000000..cdc9f0bbb781
--- /dev/null
+++ b/packages/opencode/src/cli/completion.ts
@@ -0,0 +1,4 @@
+export function isShellCompletionInvocation(argv: readonly string[]) {
+  if (argv.includes("--get-yargs-completions")) return true
+  return argv.find((arg) => !arg.startsWith("-")) === "completion"
+}
diff --git a/packages/opencode/src/index.ts b/packages/opencode/src/index.ts
index 4c8e447041c0..831549b06f4f 100644
--- a/packages/opencode/src/index.ts
+++ b/packages/opencode/src/index.ts
@@ -39,6 +39,7 @@ import { PluginCommand } from "./cli/cmd/plug"
 import { Heap } from "./cli/heap"
 import { drizzle } from "drizzle-orm/bun-sqlite"
 import { ensureProcessMetadata } from "@opencode-ai/core/util/opencode-process"
+import { isShellCompletionInvocation } from "./cli/completion"
 
 const processMetadata = ensureProcessMetadata("main")
 
@@ -55,6 +56,7 @@ process.on("uncaughtException", (e) => {
 })
 
 const args = hideBin(process.argv)
+const shellCompletionInvocation = isShellCompletionInvocation(args)
 
 function show(out: string) {
   const text = out.trimStart()
@@ -88,6 +90,8 @@ const cli = yargs(args)
     type: "boolean",
   })
   .middleware(async (opts) => {
+    if (shellCompletionInvocation) return
+
     if (opts.pure) {
       process.env.OPENCODE_PURE = "1"
     }
diff --git a/packages/opencode/src/provider/models.ts b/packages/opencode/src/provider/models.ts
index 77e217eb7f8c..973f270dde18 100644
--- a/packages/opencode/src/provider/models.ts
+++ b/packages/opencode/src/provider/models.ts
@@ -8,6 +8,7 @@ import { Flock } from "@opencode-ai/core/util/flock"
 import { Hash } from "@opencode-ai/core/util/hash"
 import { AppFileSystem } from "@opencode-ai/core/filesystem"
 import { withTransientReadRetry } from "@/util/effect-http-client"
+import { isShellCompletionInvocation } from "@/cli/completion"
 
 const Cost = Schema.Struct({
   input: Schema.Finite,
@@ -181,7 +182,7 @@ export const layer: Layer.Layer<Service, never, AppFileSystem.Service | HttpClie
       )
     })
 
-    if (!Flag.OPENCODE_DISABLE_MODELS_FETCH && !process.argv.includes("--get-yargs-completions")) {
+    if (!Flag.OPENCODE_DISABLE_MODELS_FETCH && !isShellCompletionInvocation(process.argv.slice(2))) {
       // Schedule.spaced runs the effect once, then waits between completions.
       yield* Effect.forkScoped(refresh().pipe(Effect.repeat(Schedule.spaced("60 minutes")), Effect.ignore))
     }
diff --git a/packages/opencode/test/cli/completion.test.ts b/packages/opencode/test/cli/completion.test.ts
new file mode 100644
index 000000000000..caeb1507dd1c
--- /dev/null
+++ b/packages/opencode/test/cli/completion.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, test } from "bun:test"
+import { isShellCompletionInvocation } from "../../src/cli/completion"
+
+describe("isShellCompletionInvocation", () => {
+  test("matches the yargs completion command", () => {
+    expect(isShellCompletionInvocation(["completion"])).toBe(true)
+    expect(isShellCompletionInvocation(["--pure", "completion"])).toBe(true)
+  })
+
+  test("matches yargs completion probe calls", () => {
+    expect(isShellCompletionInvocation(["--get-yargs-completions", "opencode"])).toBe(true)
+  })
+
+  test("ignores normal cli invocations", () => {
+    expect(isShellCompletionInvocation([])).toBe(false)
+    expect(isShellCompletionInvocation(["run", "fix this"])).toBe(false)
+    expect(isShellCompletionInvocation(["./completion"])).toBe(false)
+  })
+})
diff --git a/packages/web/src/content/docs/index.mdx b/packages/web/src/content/docs/index.mdx
index 90e7eafb2f31..93d2f32c2f5c 100644
--- a/packages/web/src/content/docs/index.mdx
+++ b/packages/web/src/content/docs/index.mdx
@@ -88,6 +88,22 @@ You can also install it with the following commands:
   paru -S opencode-bin              # Arch Linux (Latest from AUR)
   ```
 
+### Shell completion
+
+OpenCode can generate shell completion scripts with `opencode completion`.
+
+```bash
+# Bash
+SHELL="$(command -v bash)" opencode completion >> ~/.bashrc
+source ~/.bashrc
+
+# Zsh
+SHELL="$(command -v zsh)" opencode completion >> ~/.zshrc
+source ~/.zshrc
+```
+
+On macOS, you may want to use `~/.bash_profile` or `~/.zprofile` instead.
+
 #### Windows
 
 :::tip[Recommended: Use WSL]
diff --git a/packages/web/src/content/docs/zh-cn/index.mdx b/packages/web/src/content/docs/zh-cn/index.mdx
index ed278e2397dc..f2f5d861fe71 100644
--- a/packages/web/src/content/docs/zh-cn/index.mdx
+++ b/packages/web/src/content/docs/zh-cn/index.mdx
@@ -88,6 +88,22 @@ curl -fsSL https://opencode.ai/install | bash
   paru -S opencode-bin              # Arch Linux (Latest from AUR)
   ```
 
+### Shell 补全
+
+OpenCode 支持通过 `opencode completion` 生成 shell 补全脚本。
+
+```bash
+# Bash
+SHELL="$(command -v bash)" opencode completion >> ~/.bashrc
+source ~/.bashrc
+
+# Zsh
+SHELL="$(command -v zsh)" opencode completion >> ~/.zshrc
+source ~/.zshrc
+```
+
+在 macOS 上，你可能更想写入 `~/.bash_profile` 或 `~/.zprofile`。
+
 #### Windows
 
 :::tip[推荐：使用 WSL]