The best way to control Claude Code, Codex and more from any computer or phone
feat(cli): choose model options when starting a thread with t3 thread start (#23932)
Co-authored-by: Julius Marminge <julius0216@outlook.com>
Pieterjan Muller committed
Nov 17, 2026 at 05:51 UTC
84d34d40f8455c8024a371d3008ff15b75645f57
3 files changed
+98
-11
apps/server/src/cli/thread.test.ts
+46
@@ -10,6 +10,7 @@ import * as Effect from "effect/Effect";
10
import * as Fiber from "effect/Fiber";
11
import * as FileSystem from "effect/FileSystem";
12
import * as Layer from "effect/Layer";
13
+import * as Option from "effect/Option";
14
import * as Path from "effect/Path";
15
import { ChildProcess, ChildProcessSpawner } from "effect/process";
16
import * as TestClock from "effect/testing/TestClock";
@@ -23,6 +24,7 @@ import {
24
persistServerRuntimeState,
25
} from "../serverRuntimeState.ts";
26
import {
27
+ launchModelSelection,
28
readLatestMessages,
29
resolveProject,
30
threadCommand,
@@ -371,6 +373,50 @@ it.effect("--wait reports its run's result when a later run is the one waiting",
373
}),
374
);
375
376
+it.effect("start sends each --option as a typed model option", () =>
377
+ Effect.gen(function* () {
378
+ const selection = yield* launchModelSelection({
379
+ provider: Option.some("codex"),
380
+ model: Option.some("gpt-6.1-sol"),
381
+ option: ["reasoningEffort=high", " fastMode = false ", "note=a=b"],
382
+ });
383
+
384
+ assert.deepStrictEqual(selection, {
385
+ instanceId: "codex",
386
+ model: "gpt-6.1-sol",
387
+ options: [
388
+ { id: "reasoningEffort", value: "high" },
389
+ { id: "fastMode", value: false },
390
+ { id: "note", value: "a=b" },
391
+ ],
392
+ });
393
+ }),
394
+);
395
+
396
+it.effect("start rejects a repeated --option before reaching the server", () =>
397
+ Effect.gen(function* () {
398
+ const error = yield* Command.runWith(threadCommand, { version: "0.0.0" })([
399
+ "start",
400
+ ".",
401
+ "hi",
402
+ "--provider",
403
+ "codex",
404
+ "--model",
405
+ "gpt-6.1-sol",
406
+ "--option",
407
+ "reasoningEffort=high",
408
+ "--option",
409
+ "reasoningEffort=low",
410
+ ]).pipe(Effect.flip);
411
+
412
+ assert.strictEqual(error.message, "--option reasoningEffort is given more than once.");
413
+ }).pipe(
414
+ Effect.provide(
415
+ Layer.mergeAll(NodeServices.layer, NodeCrypto.layer, NetService.layer, TestConsole.layer),
416
+ ),
417
+ ),
418
+);
419
+
420
/** Serves t3_thread_read pages the way the server does: positions count every item. */
421
const timelineTools = (types: ReadonlyArray<string>) => {
422
const items = types.map((type, position) => ({ position, itemId: `item-${position}`, type }));
apps/server/src/cli/thread.ts
+47
-11
@@ -717,6 +717,45 @@ const launchWorkspaceStrategy = (input: {
717
}),
718
});
719
720
+/**
721
+ * Options are model specific, so they need an explicit model. `true` and
722
+ * `false` become booleans because boolean options such as fastMode only match
723
+ * a boolean.
724
+ */
725
+export const launchModelSelection = Effect.fn("cli.thread.launchModelSelection")(function* (input: {
726
+ readonly provider: Option.Option<string>;
727
+ readonly model: Option.Option<string>;
728
+ readonly option: ReadonlyArray<string>;
729
+}) {
730
+ if (Option.isSome(input.provider) !== Option.isSome(input.model)) {
731
+ return yield* new ThreadUsageError({ detail: "--provider and --model go together." });
732
+ }
733
+ if (Option.isNone(input.provider) || Option.isNone(input.model)) {
734
+ if (input.option.length > 0) {
735
+ return yield* new ThreadUsageError({ detail: "--option needs --provider and --model." });
736
+ }
737
+ return undefined;
738
+ }
739
+ const options: Array<{ readonly id: string; readonly value: string | boolean }> = [];
740
+ for (const entry of input.option) {
741
+ const separator = entry.indexOf("=");
742
+ const id = separator < 0 ? "" : entry.slice(0, separator).trim();
743
+ const value = separator < 0 ? "" : entry.slice(separator + 1).trim();
744
+ if (id.length === 0 || value.length === 0) {
745
+ return yield* new ThreadUsageError({ detail: `--option '${entry}' is not id=value.` });
746
+ }
747
+ if (options.some((option) => option.id === id)) {
748
+ return yield* new ThreadUsageError({ detail: `--option ${id} is given more than once.` });
749
+ }
750
+ options.push({ id, value: value === "true" ? true : value === "false" ? false : value });
751
+ }
752
+ return {
753
+ instanceId: input.provider.value,
754
+ model: input.model.value,
755
+ ...(options.length === 0 ? {} : { options }),
756
+ };
757
+});
758
+
759
const jsonFlag = Flag.Boolean("json").pipe(
760
Flag.withDescription("Print JSON instead of text."),
761
Flag.withDefault(false),
@@ -793,6 +832,12 @@ const threadStartCommand = Command.make("start", {
832
Flag.withDescription("Model slug. Defaults to the project's default model."),
833
Flag.optional,
834
),
835
+ option: Flag.String("option").pipe(
836
+ Flag.withDescription(
837
+ "Model option as id=value, such as effort=high. Repeat for more. Needs --provider and --model.",
838
+ ),
839
+ Flag.atLeast(0),
840
+ ),
841
worktree: Flag.String("worktree").pipe(
842
Flag.withDescription(
843
"Run in a new git worktree based on this branch, tag, or commit, instead of the project folder.",
@@ -811,9 +856,7 @@ const threadStartCommand = Command.make("start", {
856
Effect.gen(function* () {
857
const message = yield* readMessageArgument(flags.message);
858
const workspaceStrategy = yield* launchWorkspaceStrategy(flags);
814
- if (Option.isSome(flags.provider) !== Option.isSome(flags.model)) {
815
- return yield* new ThreadUsageError({ detail: "--provider and --model go together." });
816
- }
859
+ const modelSelection = yield* launchModelSelection(flags);
860
const title = yield* decodeTitle(
861
Option.getOrElse(flags.title, () => titleFromMessage(message)),
862
).pipe(Effect.mapError(() => new ThreadUsageError({ detail: "The title is empty." })));
@@ -828,14 +871,7 @@ const threadStartCommand = Command.make("start", {
871
title,
872
message,
873
...(workspaceStrategy === undefined ? {} : { workspaceStrategy }),
831
- ...(Option.isSome(flags.provider) && Option.isSome(flags.model)
832
- ? {
833
- modelSelection: {
834
- instanceId: flags.provider.value,
835
- model: flags.model.value,
836
- },
837
- }
838
- : {}),
874
+ ...(modelSelection === undefined ? {} : { modelSelection }),
875
},
876
ThreadLaunchResult,
877
);
docs/user/outside-agents.md
+5
@@ -153,6 +153,11 @@ default model and permission mode, and runs in the project folder unless you
153
pass `--worktree <base-branch>`. `send` never interrupts: a busy thread gets
154
the message as its next turn. Pass `-` as the message to read it from stdin.
155
156
+To choose the model, pass `--provider <instance-id> --model <slug>`. Add
157
+`--option id=value` for each model option, such as `--option effort=high`.
158
+Option ids and values depend on the model; `true` and `false` set on/off
159
+options.
160
+
161
`--wait` prints the agent's reply. It exits 1 when the run fails or stops, and
162
2 when the agent waits for an answer you give in the app. Add `--json` for a
163
result that always includes the thread id.