perf: implement lazy command loading to improve CLI startup time and add a startup benchmark script.

Author: edy

packages/opencode/script/bench-startup.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env bun
+
+import { spawnSync } from "child_process"
+import path from "path"
+
+const dir = path.resolve(import.meta.dirname, "..")
+
+const commands = [
+  ["--version"],
+  ["--help"],
+  ["completion"],
+  ["debug", "paths"],
+]
+
+console.log("=== Startup Benchmark ===")
+for (const cmd of commands) {
+  const times: number[] = []
+  for (let i = 0; i < 5; i++) {
+    const start = performance.now()
+    spawnSync("bun", ["run", "--conditions=browser", "src/index.ts", ...cmd], {
+      cwd: dir,
+      stdio: "ignore",
+    })
+    const end = performance.now()
+    times.push(end - start)
+  }
+  times.sort((a, b) => a - b)
+  const median = times[Math.floor(times.length / 2)]
+  console.log(`${cmd.join(" ").padEnd(20)} median: ${median.toFixed(2)}ms (${times.map((t) => t.toFixed(0)).join(", ")} ms)`)
+}

packages/opencode/src/cli/cmd/tui.ts

@@ -69,11 +69,8 @@ export function resolveThreadDirectory(project?: string, envPWD = process.env.PW
   return Filesystem.resolve(cwd)
 }
 
-export const TuiThreadCommand = cmd({
-  command: "$0 [project]",
-  describe: "start opencode tui",
-  builder: (yargs) =>
-    withNetworkOptions(yargs)
+export const tuiBuilder = (yargs: any) =>
+  withNetworkOptions(yargs)
       .positional("project", {
         type: "string",
         describe: "path to start opencode in",
@@ -140,7 +137,12 @@ export const TuiThreadCommand = cmd({
       .option("demo", {
         type: "boolean",
         hidden: true,
-      }),
+      })
+
+export const TuiThreadCommand = cmd({
+  command: "$0 [project]",
+  describe: "start opencode tui",
+  builder: tuiBuilder,
   handler: async (args) => {
     if (args.replay === true) {
       UI.error("--replay is not supported; replay is enabled by default")

packages/opencode/src/cli/lazy-command.ts

@@ -0,0 +1,19 @@
+import type { CommandModule } from "yargs"
+
+export function lazyCommand<T = {}>(
+  moduleObj: CommandModule<{}, T>,
+  loader: () => Promise<any>,
+  exportName?: string,
+): CommandModule<{}, T> {
+  return {
+    command: moduleObj.command,
+    aliases: moduleObj.aliases,
+    describe: moduleObj.describe,
+    builder: moduleObj.builder as any,
+    async handler(args) {
+      const mod = await loader()
+      const target = exportName ? mod[exportName] : (mod.default || Object.values(mod)[0])
+      return target.handler(args)
+    },
+  }
+}

packages/opencode/src/cli/ui.ts

@@ -1,5 +1,4 @@
 import { EOL } from "os"
-import { Schema } from "effect"
 import { logo as glyphs } from "./logo"
 
 const wordmark = [
@@ -9,7 +8,10 @@ const wordmark = [
   `▀▀▀▀ █▀▀▀ ▀▀▀▀ ▀  ▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀`,
 ]
 
-export class CancelledError extends Schema.TaggedErrorClass<CancelledError>()("UICancelledError", {}) {}
+export class CancelledError extends Error {
+  readonly _tag = "UICancelledError"
+  override readonly name = "UICancelledError"
+}
 
 export const Style = {
   TEXT_HIGHLIGHT: "\x1b[96m",

packages/opencode/src/index.ts

@@ -18,10 +18,9 @@ import { PluginCommand } from "./cli/cmd/plug"
 import { DbCommand } from "./cli/cmd/db"
 import { UI } from "./cli/ui"
 import { InstallationVersion } from "@opencode-ai/core/installation/version"
-import { FormatError } from "./cli/error"
 import { EOL } from "os"
 import { errorMessage } from "./util/error"
-import { Heap } from "./cli/heap"
+import { lazyCommand } from "./cli/lazy-command"
 
 const args = hideBin(process.argv)
 
@@ -63,7 +62,10 @@ const cli = yargs(args)
       process.env.OPENCODE_PURE = "1"
     }
 
-    Heap.start()
+    if (process.env.OPENCODE_AUTO_HEAP_SNAPSHOT) {
+      const { Heap } = await import("./cli/heap")
+      Heap.start()
+    }
 
     process.env.AGENT = "1"
     process.env.OPENCODE = "1"
@@ -75,22 +77,22 @@ const cli = yargs(args)
   })
   .usage("")
   .completion("completion", "generate shell completion script")
-  .command(McpCommand)
-  .command(TuiThreadCommand)
-  .command(AttachCommand)
-  .command(RunCommand)
-  .command(GenerateCommand)
-  .command(DebugCommand)
-  .command(ProvidersCommand)
-  .command(AgentCommand)
-  .command(UpgradeCommand)
-  .command(UninstallCommand)
-  .command(ServeCommand)
-  .command(ModelsCommand)
-  .command(ExportCommand)
-  .command(SessionCommand)
-  .command(PluginCommand)
-  .command(DbCommand)
+  .command(lazyCommand(McpCommand, () => import("./cli/cmd/mcp"), "McpCommand"))
+  .command(lazyCommand(TuiThreadCommand, () => import("./cli/cmd/tui"), "TuiThreadCommand"))
+  .command(lazyCommand(AttachCommand, () => import("./cli/cmd/attach"), "AttachCommand"))
+  .command(lazyCommand(RunCommand, () => import("./cli/cmd/run"), "RunCommand"))
+  .command(lazyCommand(GenerateCommand, () => import("./cli/cmd/generate"), "GenerateCommand"))
+  .command(lazyCommand(DebugCommand, () => import("./cli/cmd/debug"), "DebugCommand"))
+  .command(lazyCommand(ProvidersCommand, () => import("./cli/cmd/providers"), "ProvidersCommand"))
+  .command(lazyCommand(AgentCommand, () => import("./cli/cmd/agent"), "AgentCommand"))
+  .command(lazyCommand(UpgradeCommand, () => import("./cli/cmd/upgrade"), "UpgradeCommand"))
+  .command(lazyCommand(UninstallCommand, () => import("./cli/cmd/uninstall"), "UninstallCommand"))
+  .command(lazyCommand(ServeCommand, () => import("./cli/cmd/serve"), "ServeCommand"))
+  .command(lazyCommand(ModelsCommand, () => import("./cli/cmd/models"), "ModelsCommand"))
+  .command(lazyCommand(ExportCommand, () => import("./cli/cmd/export"), "ExportCommand"))
+  .command(lazyCommand(SessionCommand, () => import("./cli/cmd/session"), "SessionCommand"))
+  .command(lazyCommand(PluginCommand, () => import("./cli/cmd/plug"), "PluginCommand"))
+  .command(lazyCommand(DbCommand, () => import("./cli/cmd/db"), "DbCommand"))
   .fail((msg, err) => {
     if (
       msg?.startsWith("Unknown argument") ||
@@ -116,6 +118,7 @@ try {
     await cli.parse()
   }
 } catch (e) {
+  const { FormatError } = await import("./cli/error")
   const formatted = FormatError(e)
   if (formatted) UI.error(formatted)
   if (formatted === undefined) {