The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 08:30 UTC
feat(terminal): allow configuring the interactive shell (#37924)
Co-authored-by: Shantanu Ojha <shantanuojha@Shantanus-MacBook-Pro.local>
Julius Marminge committed
Nov 16, 2026 at 22:26 UTC
9795f45f23f6944c4dacdcf36a4c34b8ac193e8d
5 files changed
+187
-13
apps/server/src/project/ProjectSetupScriptRunner.test.ts
+19
-6
@@ -5,6 +5,7 @@ import {
5
ProjectId,
6
TerminalNotRunningError,
7
type TerminalEvent,
8
+ type TerminalOpenInput,
9
type TerminalSessionSnapshot,
10
} from "@t3tools/contracts";
11
import * as HostProcess from "@t3tools/shared/HostProcess";
@@ -48,14 +49,19 @@ const makeHarness = Effect.fn(function* (options: {
49
readonly shell?: string | null;
50
}) {
51
const listeners = new Set<(event: TerminalEvent) => Effect.Effect<void>>();
52
+ const opens: TerminalOpenInput[] = [];
53
const writes = yield* Queue.unbounded<string>();
54
const outputLines = yield* Queue.unbounded<string>();
55
const terminals = Layer.mock(TerminalManager.TerminalManager)({
54
- open: () =>
55
- (options.opening
56
- ? Deferred.succeed(options.opening, undefined).pipe(Effect.andThen(Effect.never))
57
- : Effect.void
58
- ).pipe(Effect.as(openSnapshot(options.history ?? ""))),
56
+ open: (input) =>
57
+ Effect.sync(() => opens.push(input)).pipe(
58
+ Effect.andThen(
59
+ options.opening
60
+ ? Deferred.succeed(options.opening, undefined).pipe(Effect.andThen(Effect.never))
61
+ : Effect.void,
62
+ ),
63
+ Effect.as(openSnapshot(options.history ?? "")),
64
+ ),
65
getShell: () =>
66
options.shell === null
67
? Effect.fail(new TerminalNotRunningError({ threadId, terminalId }))
@@ -102,7 +108,7 @@ const makeHarness = Effect.fn(function* (options: {
108
});
109
const emit = (terminalEvent: TerminalEvent) =>
110
Effect.forEach([...listeners], (listener) => listener(terminalEvent), { discard: true });
105
- return { start, listeners, writes, outputLines, emit };
111
+ return { start, listeners, writes, outputLines, emit, opens };
112
});
113
114
const setup = Effect.fn(function* (
@@ -120,6 +126,13 @@ const setup = Effect.fn(function* (
126
});
127
128
describe("ProjectSetupScriptRunner", () => {
129
+ it.effect("keeps setup scripts independent of the interactive shell preference", () =>
130
+ Effect.gen(function* () {
131
+ const { opens } = yield* setup();
132
+ expect(opens[0]?.env?.T3CODE_TERMINAL_SHELL).toBe("");
133
+ }),
134
+ );
135
+
136
it.effect("writes immediately when the spawned fallback is PowerShell", () =>
137
Effect.gen(function* () {
138
const { writes } = yield* setup({
apps/server/src/project/ProjectSetupScriptRunner.ts
+2
@@ -503,6 +503,8 @@ export const make = Effect.gen(function* () {
503
}),
504
// Before client attachment, truecolor probes wait for terminal replies nobody can send.
505
COLORTERM: "",
506
+ // Project scripts keep the default shell; the preference is for interactive terminals only.
507
+ T3CODE_TERMINAL_SHELL: "",
508
};
509
const observe = input.observeCompletion;
510
const completionToken = observe ? (yield* random.uuidV4()).replaceAll("-", "") : null;
apps/server/src/terminal/Manager.test.ts
+91
-4
@@ -18,6 +18,8 @@ import {
18
TerminalProviderInstanceNotFoundError,
19
} from "@t3tools/contracts";
20
import * as HostProcess from "@t3tools/shared/HostProcess";
21
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
22
+import * as NodePtyAdapter from "./NodePtyAdapter.ts";
23
import * as Clock from "effect/Clock";
24
import * as Deferred from "effect/Deferred";
25
import * as Duration from "effect/Duration";
@@ -321,7 +323,7 @@ const createManager = (
323
managedBinaryCacheDir: options.managedBinaryCacheDir,
324
managedBinaryToolsDir: options.managedBinaryToolsDir,
325
}),
324
- });
326
+ }).pipe(Effect.provideService(SpawnExecutableResolution, (command) => command));
327
const eventsRef = yield* Ref.make<ReadonlyArray<TerminalEvent>>([]);
328
const unsubscribe = yield* manager.subscribe((event) =>
329
Ref.update(eventsRef, (events) => [...events, event]),
@@ -2213,6 +2215,91 @@ it.layer(
2215
}),
2216
);
2217
2218
+ it.effect.each([
2219
+ { platform: "win32", shell: String.raw`C:\Program Files\Git\bin\bash.exe` },
2220
+ { platform: "linux", shell: "/opt/custom shell/bin/bash" },
2221
+ ] as const)("prefers the configured terminal shell on $platform: $shell", ({ platform, shell }) =>
2222
+ Effect.gen(function* () {
2223
+ const { manager, ptyAdapter } = yield* createManager(5, {
2224
+ env: { T3CODE_TERMINAL_SHELL: ` ${shell} `, SHELL: "/bin/zsh" },
2225
+ }).pipe(Effect.provide(layerWithHostPlatform(platform)));
2226
+
2227
+ yield* manager.open(openInput());
2228
+
2229
+ expect(ptyAdapter.spawnInputs[0]?.shell).toBe(shell);
2230
+ }),
2231
+ );
2232
+
2233
+ it.effect("lets script terminals keep the default shell without changing other terminals", () =>
2234
+ Effect.gen(function* () {
2235
+ const gitBash = String.raw`C:\Program Files\Git\bin\bash.exe`;
2236
+ const { manager, ptyAdapter } = yield* createManager(5, {
2237
+ env: { T3CODE_TERMINAL_SHELL: gitBash },
2238
+ }).pipe(Effect.provide(layerWithHostPlatform("win32")));
2239
+
2240
+ yield* manager.open(openInput({ env: { T3CODE_TERMINAL_SHELL: "" } }));
2241
+ yield* manager.open(openInput({ terminalId: "interactive" }));
2242
+
2243
+ expect(ptyAdapter.spawnInputs.map((input) => input.shell)).toEqual(["pwsh.exe", gitBash]);
2244
+ }),
2245
+ );
2246
+
2247
+ // POSIX exec failures are asynchronous in node-pty; ConPTY has a separate readiness protocol.
2248
+ it.effect.skipIf(HostProcess.Platform.defaultValue() === "win32")(
2249
+ "resolves configured shells and falls back from invalid paths with the real PTY adapter",
2250
+ () =>
2251
+ Effect.gen(function* () {
2252
+ const fs = yield* FileSystem.FileSystem;
2253
+ const path = yield* Path.Path;
2254
+ const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-real-shell-" });
2255
+ const nonExecutable = path.join(baseDir, "not-executable");
2256
+ yield* fs.writeFileString(nonExecutable, "#!/bin/sh\nexit 0\n");
2257
+ yield* fs.chmod(nonExecutable, 0o644);
2258
+ const ptyAdapter = yield* PtyAdapter.PtyAdapter.pipe(Effect.provide(NodePtyAdapter.layer));
2259
+ const toolsDir = path.join(baseDir, "tools");
2260
+ const customShell = path.join(toolsDir, "custom-shell");
2261
+ yield* fs.makeDirectory(toolsDir);
2262
+ yield* fs.writeFileString(customShell, "#!/bin/sh\nexec /bin/sh\n");
2263
+ yield* fs.chmod(customShell, 0o755);
2264
+ const spacedDir = path.join(baseDir, "shells ");
2265
+ const spacedShell = path.join(spacedDir, "custom-shell");
2266
+ yield* fs.makeDirectory(spacedDir);
2267
+ yield* fs.writeFileString(spacedShell, "#!/bin/sh\nexec /bin/sh\n");
2268
+ yield* fs.chmod(spacedShell, 0o755);
2269
+ for (const { shell, searchPath, cwd, expectedShell } of [
2270
+ { shell: path.join(baseDir, "missing"), searchPath: "/bin", expectedShell: "/bin/sh" },
2271
+ { shell: nonExecutable, searchPath: "/bin", expectedShell: "/bin/sh" },
2272
+ { shell: "custom-shell", searchPath: "./tools", expectedShell: customShell },
2273
+ { shell: "custom-shell", searchPath: toolsDir, expectedShell: customShell },
2274
+ { shell: "custom-shell", searchPath: '"./tools"', expectedShell: customShell },
2275
+ { shell: "custom-shell", searchPath: ":/bin", cwd: toolsDir, expectedShell: customShell },
2276
+ { shell: "custom-shell", searchPath: `${spacedDir}:/bin`, expectedShell: spacedShell },
2277
+ ] as ReadonlyArray<{
2278
+ shell: string;
2279
+ searchPath: string;
2280
+ cwd?: string;
2281
+ expectedShell: string;
2282
+ }>) {
2283
+ const spawnedShells: string[] = [];
2284
+ const manager = yield* TerminalManager.makeWithOptions({
2285
+ logsDir: path.join(baseDir, "logs"),
2286
+ ptyAdapter: {
2287
+ spawn: (input) => {
2288
+ spawnedShells.push(input.shell);
2289
+ return ptyAdapter.spawn(input);
2290
+ },
2291
+ },
2292
+ shellResolver: () => "/bin/sh",
2293
+ env: { ...process.env, T3CODE_TERMINAL_SHELL: shell, PATH: searchPath },
2294
+ });
2295
+ const snapshot = yield* manager.open(openInput({ cwd: cwd ?? baseDir }));
2296
+ expect(spawnedShells).toEqual([expectedShell]);
2297
+ expect(snapshot.status).toBe("running");
2298
+ yield* manager.close({ threadId: "thread-1" });
2299
+ }
2300
+ }),
2301
+ );
2302
+
2303
it.effect("preserves Windows Path casing when appending managed ACP binaries", () =>
2304
Effect.gen(function* () {
2305
const fileSystem = yield* FileSystem.FileSystem;
@@ -2282,8 +2369,8 @@ it.layer(
2369
const ptyAdapter = new FakePtyAdapter();
2370
const { manager } = yield* createManager(5, {
2371
ptyAdapter,
2285
- shellResolver: () => "C:\\missing\\custom-shell.exe",
2372
env: {
2373
+ T3CODE_TERMINAL_SHELL: "C:\\missing\\custom-shell.exe",
2374
ComSpec: "C:\\Windows\\System32\\cmd.exe",
2375
PATH: "C:\\Windows\\System32",
2376
SystemRoot: "C:\\Windows",
@@ -2730,13 +2817,13 @@ it.layer(
2817
}),
2818
);
2819
2733
- it.effect("starts bash as a login shell on macOS only", () =>
2820
+ it.effect("starts bash as a login shell on macOS and Windows", () =>
2821
Effect.gen(function* () {
2822
for (const [platform, shell, args] of [
2823
["darwin", "/bin/bash", ["-l"]],
2824
["darwin", "/opt/homebrew/bin/bash", ["-l"]],
2825
["linux", "/bin/bash", undefined],
2739
- ["win32", "C:\\Program Files\\Git\\bin\\bash.exe", undefined],
2826
+ ["win32", "C:\\Program Files\\Git\\bin\\bash.exe", ["--login", "-i"]],
2827
["darwin", "/bin/zsh", ["-o", "nopromptsp"]],
2828
["linux", "/bin/zsh", ["-o", "nopromptsp"]],
2829
["win32", "pwsh.exe", POWERSHELL_ARGS],
apps/server/src/terminal/Manager.ts
+45
-2
@@ -43,7 +43,7 @@ import { makeKeyedCoalescingWorker } from "@t3tools/shared/KeyedCoalescingWorker
43
import * as KeyedLock from "@t3tools/shared/KeyedLock";
44
import { AgentScope } from "@t3tools/shared/AgentScope";
45
import * as HostProcess from "@t3tools/shared/HostProcess";
46
-import { mergePathEntries } from "@t3tools/shared/shell";
46
+import { SpawnExecutableResolution, mergePathEntries } from "@t3tools/shared/shell";
47
48
import { acpRegistryManagedBinaryDirectories } from "@t3tools/provider-acp-registry/server";
49
import { getTerminalLabel } from "@t3tools/shared/terminalLabels";
@@ -601,6 +601,9 @@ function shellCandidateFromCommand(
601
if (platform === "win32" && (shellName === "pwsh.exe" || shellName === "powershell.exe")) {
602
return { shell: command, args: ["-NoLogo", "-NoExit", "-Command", POWERSHELL_UTF8_SETUP] };
603
}
604
+ if (platform === "win32" && (shellName === "bash.exe" || shellName === "bash")) {
605
+ return { shell: command, args: ["--login", "-i"] };
606
+ }
607
if (platform !== "win32" && shellName === "zsh") {
608
return { shell: command, args: ["-o", "nopromptsp"] };
609
}
@@ -651,7 +654,10 @@ const resolveShellCandidates = Effect.fn("terminal.resolveShellCandidates")(func
654
shellResolver: () => string,
655
platform: NodeJS.Platform,
656
env: NodeJS.ProcessEnv,
657
+ terminalShell: string | undefined,
658
) {
659
+ // This is an executable path, not a command line; spaces belong to the path.
660
+ const configured = shellCandidateFromCommand(terminalShell?.trim() || null, platform);
661
const requested = shellCandidateFromCommand(
662
yield* normalizeShellCommand(shellResolver(), platform),
663
platform,
@@ -659,6 +665,7 @@ const resolveShellCandidates = Effect.fn("terminal.resolveShellCandidates")(func
665
666
if (platform === "win32") {
667
return uniqueShellCandidates([
668
+ configured,
669
requested,
670
shellCandidateFromCommand("pwsh.exe", platform),
671
shellCandidateFromCommand(windowsPowerShellPath(env), platform),
@@ -670,6 +677,7 @@ const resolveShellCandidates = Effect.fn("terminal.resolveShellCandidates")(func
677
}
678
679
return uniqueShellCandidates([
680
+ configured,
681
requested,
682
shellCandidateFromCommand(yield* normalizeShellCommand(env.SHELL, platform), platform),
683
shellCandidateFromCommand("/bin/zsh", platform),
@@ -1781,6 +1789,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
1789
const platform = yield* HostProcess.Platform;
1790
const architecture = yield* HostProcess.Architecture;
1791
const agentScope = yield* AgentScope;
1792
+ const resolveExecutable = yield* SpawnExecutableResolution;
1793
// Inherit the full environment minus createTerminalSpawnEnv's blocklist; allowlists silently drop user tooling variables.
1794
const baseEnv = options.env ?? process.env;
1795
const shellResolver = options.shellResolver ?? (() => defaultShellResolver(platform, baseEnv));
@@ -2728,8 +2737,41 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
2737
);
2738
}
2739
2740
+ // PATH lookup must use the child's working directory, not the server's.
2741
+ const lookupEnv =
2742
+ platform === "win32"
2743
+ ? spawnEnv
2744
+ : {
2745
+ ...spawnEnv,
2746
+ PATH: (spawnEnv.PATH ?? spawnEnv.Path ?? spawnEnv.path ?? "")
2747
+ .split(":")
2748
+ // An empty entry means the working directory, which resolve("") yields.
2749
+ .map((entry) => path.resolve(session.cwd, entry.replace(/^"+|"+$/g, "")))
2750
+ .join(":"),
2751
+ };
2752
+ // POSIX node-pty can return a PTY before exec fails, so validate before accepting a candidate.
2753
+ const executable =
2754
+ platform !== "win32"
2755
+ ? resolveExecutable(
2756
+ candidate.shell.includes("/")
2757
+ ? path.resolve(session.cwd, candidate.shell)
2758
+ : candidate.shell,
2759
+ platform,
2760
+ lookupEnv,
2761
+ )
2762
+ : candidate.shell;
2763
+ if (executable === undefined) {
2764
+ return yield* trySpawn(
2765
+ shellCandidates,
2766
+ spawnEnv,
2767
+ session,
2768
+ index + 1,
2769
+ new PtyAdapter.PtySpawnError({ adapter: "terminal-manager", shell: candidate.shell }),
2770
+ );
2771
+ }
2772
+
2773
const launch = yield* agentScope.wrap({
2732
- command: candidate.shell,
2774
+ command: executable,
2775
args: candidate.args ?? [],
2776
name: "terminal",
2777
env: spawnEnv,
@@ -2806,6 +2848,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
2848
shellResolver,
2849
platform,
2850
baseEnv,
2851
+ session.runtimeEnv?.T3CODE_TERMINAL_SHELL ?? baseEnv.T3CODE_TERMINAL_SHELL,
2852
).pipe(Effect.provideService(FileSystem.FileSystem, fileSystem));
2853
const terminalEnv = createTerminalSpawnEnv(
2854
baseEnv,
docs/user/terminal.md
+30
-1
@@ -1,4 +1,33 @@
1
-# Terminal history
1
+# Terminal
2
+
3
+## Choose a shell
4
+
5
+Set `T3CODE_TERMINAL_SHELL` in the environment that launches the T3 Code server
6
+to choose the executable used for new terminals. Use an executable name or its
7
+full path, without surrounding quotes or command-line arguments. An unset or
8
+blank value keeps the platform default. If the executable cannot be started,
9
+T3 Code tries its usual fallback shells.
10
+
11
+On Windows, to use Git Bash from a standard Git for Windows installation, run
12
+this in PowerShell:
13
+
14
+```powershell
15
+[Environment]::SetEnvironmentVariable('T3CODE_TERMINAL_SHELL', 'C:\Program Files\Git\bin\bash.exe', 'User')
16
+```
17
+
18
+Fully quit T3 Code, then reopen it from the Start menu and create a new terminal.
19
+If the app still inherits the old environment, sign out of Windows and sign in
20
+again. Git Bash starts as an interactive login shell. Use `bin\bash.exe`, not
21
+`git-bash.exe`, which launches a separate terminal window.
22
+
23
+To restore the default, remove the variable with the same command using `$null`
24
+as its second argument, then restart T3 Code.
25
+
26
+This setting belongs to the machine hosting the server, including when you
27
+connect from another device. It does not change provider-run commands or the
28
+shell used by automatic project setup and settle scripts.
29
+
30
+## Terminal history
31
32
Each terminal keeps up to 5,000 lines and 8 MiB of scrollback on its environment
33
server. T3 Code removes the oldest output when either limit is reached. A long