feat: add free model resolution for --model free

  Resolves --model free to a random free opencode model before
  prompting. Supports --variant any for random variant selection.

  Closes #21863

Author: caretak3r

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

@@ -644,22 +644,26 @@ export const RunCommand = cmd({
         process.exit(1)
       })
 
+      const resolved = await Provider.resolveSelection(args.model, args.variant)
+      const model = resolved.model
+      const variant = resolved.variant
+
       if (args.command) {
         await sdk.session.command({
           sessionID,
           agent,
-          model: args.model,
+          model,
           command: args.command,
           arguments: message,
-          variant: args.variant,
+          variant,
         })
       } else {
-        const model = args.model ? Provider.parseModel(args.model) : undefined
+        const modelObj = model ? Provider.parseModel(model) : undefined
         await sdk.session.prompt({
           sessionID,
           agent,
-          model,
-          variant: args.variant,
+          model: modelObj,
+          variant,
           parts: [...files, { type: "text", text: message }],
         })
       }

packages/opencode/src/cli/cmd/tui/app.tsx

@@ -388,6 +388,7 @@ function App(props: { onSnapshot?: () => Promise<string[]> }) {
           })
         local.model.set({ providerID, modelID }, { recent: true })
       }
+      if (args.variant) local.model.variant.set(args.variant)
       // Handle --session without --fork immediately (fork is handled in createEffect below)
       if (args.sessionID && !args.fork) {
         route.navigate({

packages/opencode/src/cli/cmd/tui/context/args.tsx

@@ -2,6 +2,7 @@ import { createSimpleContext } from "./helper"
 
 export interface Args {
   model?: string
+  variant?: string
   agent?: string
   prompt?: string
   continue?: boolean

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

@@ -16,6 +16,7 @@ import { win32DisableProcessedInput, win32InstallCtrlCGuard } from "./win32"
 import { TuiConfig } from "@/config/tui"
 import { Instance } from "@/project/instance"
 import { writeHeapSnapshot } from "v8"
+import { Provider } from "@/provider/provider"
 
 declare global {
   const OPENCODE_WORKER_PATH: string
@@ -100,6 +101,10 @@ export const TuiThreadCommand = cmd({
       .option("agent", {
         type: "string",
         describe: "agent to use",
+      })
+      .option("variant", {
+        type: "string",
+        describe: "model variant (provider-specific reasoning effort, e.g., high, max, minimal)",
       }),
   handler: async (args) => {
     // Keep ENABLE_PROCESSED_INPUT cleared even if other code flips it.
@@ -130,6 +135,9 @@ export const TuiThreadCommand = cmd({
         return
       }
       const cwd = Filesystem.resolve(process.cwd())
+      const pick = await Provider.resolveSelection(args.model, args.variant)
+      const model = pick.model
+      const variant = pick.variant
 
       const worker = new Worker(file, {
         env: Object.fromEntries(
@@ -217,7 +225,8 @@ export const TuiThreadCommand = cmd({
             continue: args.continue,
             sessionID: args.session,
             agent: args.agent,
-            model: args.model,
+            model,
+            variant,
             prompt,
             fork: args.fork,
           },

packages/opencode/src/provider/provider.ts

@@ -1697,6 +1697,50 @@ export namespace Provider {
     return runPromise((svc) => svc.defaultModel())
   }
 
+  const FREE = "free"
+  export const ANY = "any"
+
+  function free(model: Model) {
+    const extra = model.cost.experimentalOver200K
+    return (
+      model.providerID === ProviderID.opencode &&
+      model.cost.input === 0 &&
+      model.cost.output === 0 &&
+      model.cost.cache.read === 0 &&
+      model.cost.cache.write === 0 &&
+      (!extra || (extra.input === 0 && extra.output === 0 && extra.cache.read === 0 && extra.cache.write === 0))
+    )
+  }
+
+  function listed(model: Model) {
+    return model.id === "big-pickle" || model.id.endsWith("-free")
+  }
+
+  function variants(model: Model) {
+    return Object.keys(model.variants ?? {})
+      .toSorted()
+      .filter((item) => item !== "default")
+  }
+
+  export async function resolveSelection(model?: string, variant?: string) {
+    if (!model) return { model, variant }
+    if (model !== FREE) return { model, variant }
+    const provider = (await list())[ProviderID.opencode]
+    const models = sort(Object.values(provider?.models ?? {}).filter((item) => free(item) && listed(item)))
+    const pick = models[Math.floor(Math.random() * models.length)]
+    if (!pick) throw new Error("No free opencode models found")
+    const next = variant === "any" ? variants(pick) : []
+    const value = variant !== "any" ? variant : next[Math.floor(Math.random() * next.length)]
+    return {
+      model: `${pick.providerID}/${pick.id}`,
+      variant: value,
+    }
+  }
+
+  export async function resolveModel(model: string) {
+    return (await resolveSelection(model)).model!
+  }
+
   const priority = ["gpt-5", "claude-sonnet-4", "big-pickle", "gemini-3-pro"]
   export function sort<T extends { id: string }>(models: T[]) {
     return sortBy(

packages/opencode/test/cli/cmd/run.test.ts

@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, mock, spyOn, test } from "bun:test"
+import * as SDK from "@opencode-ai/sdk/v2"
+import { Provider } from "../../../src/provider/provider"
+
+const seen = {
+  prompt: [] as any[],
+  command: [] as any[],
+  variant: [] as any[],
+}
+
+function setup() {
+  spyOn(Provider, "resolveSelection").mockImplementation(async (model, variant) => ({
+    model: model === "free" ? "opencode/freebie" : model,
+    variant: variant === "any" ? "high" : variant,
+  }))
+  spyOn(SDK, "createOpencodeClient").mockImplementation(
+    () =>
+      ({
+        config: {
+          get: async () => ({ data: { share: "manual" } }),
+        },
+        event: {
+          subscribe: async () => ({
+            stream: (async function* () {})(),
+          }),
+        },
+        session: {
+          create: async () => ({ data: { id: "session-1" } }),
+          prompt: async (input: any) => {
+            seen.prompt.push(input)
+            seen.variant.push(input.variant)
+            return {}
+          },
+          command: async (input: any) => {
+            seen.command.push(input)
+            seen.variant.push(input.variant)
+            return {}
+          },
+        },
+      }) as any,
+  )
+}
+
+describe("run command", () => {
+  afterEach(() => {
+    mock.restore()
+    seen.prompt.length = 0
+    seen.command.length = 0
+    seen.variant.length = 0
+  })
+
+  async function call(extra?: Record<string, unknown>) {
+    setup()
+    const { RunCommand } = await import("../../../src/cli/cmd/run")
+    const tty = Object.getOwnPropertyDescriptor(process.stdin, "isTTY")
+
+    Object.defineProperty(process.stdin, "isTTY", {
+      configurable: true,
+      value: true,
+    })
+
+    try {
+      await RunCommand.handler({
+        _: [],
+        $0: "opencode",
+        message: ["hi"],
+        command: undefined,
+        continue: false,
+        session: undefined,
+        fork: false,
+        share: false,
+        model: "free",
+        agent: undefined,
+        format: "default",
+        file: undefined,
+        title: undefined,
+        attach: "http://127.0.0.1:4096",
+        password: undefined,
+        dir: undefined,
+        port: undefined,
+        variant: undefined,
+        thinking: false,
+        "dangerously-skip-permissions": false,
+        "--": [],
+        ...extra,
+      } as any)
+    } finally {
+      if (tty) Object.defineProperty(process.stdin, "isTTY", tty)
+      else delete (process.stdin as { isTTY?: boolean }).isTTY
+    }
+  }
+
+  test("resolves free before prompting", async () => {
+    await call()
+
+    expect(seen.prompt).toHaveLength(1)
+    expect(String(seen.prompt[0].model.providerID)).toBe("opencode")
+    expect(String(seen.prompt[0].model.modelID)).toBe("freebie")
+  })
+
+  test("passes the resolved model to command sessions", async () => {
+    await call({ command: "echo" })
+
+    expect(seen.command).toHaveLength(1)
+    expect(seen.command[0].model).toBe("opencode/freebie")
+  })
+
+  test("passes the resolved any variant to sessions", async () => {
+    await call({ variant: "any" })
+
+    expect(seen.prompt).toHaveLength(1)
+    expect(seen.variant[0]).toBe("high")
+  })
+})

packages/opencode/test/cli/tui/thread.test.ts

@@ -10,11 +10,14 @@ import * as Network from "../../../src/cli/network"
 import * as Win32 from "../../../src/cli/cmd/tui/win32"
 import { TuiConfig } from "../../../src/config/tui"
 import { Instance } from "../../../src/project/instance"
+import { Provider } from "../../../src/provider/provider"
 
 const stop = new Error("stop")
 const seen = {
   tui: [] as string[],
   inst: [] as string[],
+  model: [] as (string | undefined)[],
+  variant: [] as (string | undefined)[],
 }
 
 function setup() {
@@ -25,6 +28,8 @@ function setup() {
   // https://github.com/oven-sh/bun/issues/7823 and #12823.
   spyOn(App, "tui").mockImplementation(async (input) => {
     if (input.directory) seen.tui.push(input.directory)
+    seen.model.push(input.args.model)
+    seen.variant.push(input.args.variant)
     throw stop
   })
   spyOn(Rpc, "client").mockImplementation(() => ({
@@ -47,21 +52,26 @@ function setup() {
     seen.inst.push(input.directory)
     return input.fn()
   })
+  spyOn(Provider, "resolveSelection").mockImplementation(async (model, variant) => ({
+    model: model === "free" ? "opencode/freebie" : model,
+    variant: variant === "any" ? "high" : variant,
+  }))
 }
 
 describe("tui thread", () => {
   afterEach(() => {
     mock.restore()
   })
 
-  async function call(project?: string) {
+  async function call(project?: string, model?: string, variant?: string) {
     const { TuiThreadCommand } = await import("../../../src/cli/cmd/tui/thread")
     const args: Parameters<NonNullable<typeof TuiThreadCommand.handler>>[0] = {
       _: [],
       $0: "opencode",
       project,
       prompt: "hi",
-      model: undefined,
+      model,
+      variant,
       agent: undefined,
       session: undefined,
       continue: false,
@@ -76,7 +86,12 @@ describe("tui thread", () => {
     return TuiThreadCommand.handler(args)
   }
 
-  async function check(project?: string) {
+  async function check(
+    project?: string,
+    model?: string,
+    variant?: string,
+    expected?: { model?: string; variant?: string },
+  ) {
     setup()
     await using tmp = await tmpdir({ git: true })
     const cwd = process.cwd()
@@ -87,6 +102,8 @@ describe("tui thread", () => {
     const type = process.platform === "win32" ? "junction" : "dir"
     seen.tui.length = 0
     seen.inst.length = 0
+    seen.model.length = 0
+    seen.variant.length = 0
     await fs.symlink(tmp.path, link, type)
 
     Object.defineProperty(process.stdin, "isTTY", {
@@ -104,9 +121,11 @@ describe("tui thread", () => {
     try {
       process.chdir(tmp.path)
       process.env.PWD = link
-      await expect(call(project)).rejects.toBe(stop)
+      await expect(call(project, model, variant)).rejects.toBe(stop)
       expect(seen.inst[0]).toBe(tmp.path)
       expect(seen.tui[0]).toBe(tmp.path)
+      if (expected?.model) expect(seen.model[0]).toBe(expected.model)
+      if (expected?.variant) expect(seen.variant[0]).toBe(expected.variant)
     } finally {
       process.chdir(cwd)
       if (pwd === undefined) delete process.env.PWD
@@ -125,4 +144,12 @@ describe("tui thread", () => {
   test("uses the real cwd after resolving a relative project from PWD", async () => {
     await check(".")
   })
+
+  test("resolves the free model alias before launching the tui", async () => {
+    await check(undefined, "free", undefined, { model: "opencode/freebie" })
+  })
+
+  test("passes the resolved any variant before launching the tui", async () => {
+    await check(undefined, "free", "any", { model: "opencode/freebie", variant: "high" })
+  })
 })