@devries-cameron20 / t3code-1 / commits / 9795f45f23
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

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