The best way to control Claude Code, Codex and more from any computer or phone
perf(cli): short commands like t3 --version no longer load the whole server (#29127)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Andrei committed
Nov 2, 2026 at 15:27 UTC
d01b92c0613936e5204ea2787a9ed6bf7d1ff547
4 files changed
+201
-25
apps/server/src/cli/claudeHistory.ts
+10
-7
@@ -1,8 +1,6 @@
1
import * as Effect from "effect/Effect";
2
import { Argument, Command } from "effect/cli";
3
4
-import { runClaudeHistoryWorker } from "../claudeHistoryWorker.ts";
5
-
4
/** Single-executable builds lack Node, so they use this subcommand instead of claudeHistoryWorker.mjs. */
5
export const claudeHistoryCommand = Command.make("__claude-history", {
6
method: Argument.String("method"),
@@ -11,11 +9,16 @@ export const claudeHistoryCommand = Command.make("__claude-history", {
9
}).pipe(
10
Command.unlisted,
11
Command.withHandler(({ method, sessionId, options }) =>
14
- Effect.promise(() =>
15
- runClaudeHistoryWorker(
16
- method,
17
- sessionId,
18
- options._tag === "Some" ? options.value : undefined,
12
+ // Two effects, so an interrupt during the import never starts the worker.
13
+ Effect.promise(() => import("../claudeHistoryWorker.ts")).pipe(
14
+ Effect.flatMap(({ runClaudeHistoryWorker }) =>
15
+ Effect.promise(() =>
16
+ runClaudeHistoryWorker(
17
+ method,
18
+ sessionId,
19
+ options._tag === "Some" ? options.value : undefined,
20
+ ),
21
+ ),
22
),
23
),
24
),
apps/server/src/cli/deferredImports.test.ts
new
+167
@@ -0,0 +1,167 @@
1
+// @effect-diagnostics nodeBuiltinImport:off - CLI integration uses temporary Node paths.
2
+import * as NodePath from "node:path";
3
+
4
+import * as NodeServices from "@effect/platform-node/NodeServices";
5
+import { assert, it } from "@effect/vitest";
6
+import * as NetService from "@t3tools/shared/Net";
7
+import * as Effect from "effect/Effect";
8
+import * as Exit from "effect/Exit";
9
+import * as Fiber from "effect/Fiber";
10
+import * as FileSystem from "effect/FileSystem";
11
+import * as Layer from "effect/Layer";
12
+import { Command } from "effect/cli";
13
+import { FetchHttpClient } from "effect/http";
14
+import { vi } from "vite-plus/test";
15
+
16
+import { cli } from "../binCli.ts";
17
+import {
18
+ makePersistedServerRuntimeState,
19
+ persistServerRuntimeState,
20
+} from "../serverRuntimeState.ts";
21
+
22
+const hooks = vi.hoisted(() => ({
23
+ importsAttempted: [] as string[],
24
+ historyImportStarted: Promise.withResolvers<void>(),
25
+ releaseHistoryImport: Promise.withResolvers<void>(),
26
+ runClaudeHistoryWorker: vi.fn(async () => {}),
27
+}));
28
+
29
+vi.mock("../server.ts", () => {
30
+ hooks.importsAttempted.push("server");
31
+ throw new Error("server import failed");
32
+});
33
+vi.mock("../orchestration-v2/runtimeLayer.ts", () => {
34
+ hooks.importsAttempted.push("runtimeLayer");
35
+ throw new Error("runtime import failed");
36
+});
37
+vi.mock("../claudeHistoryWorker.ts", async () => {
38
+ hooks.importsAttempted.push("claudeHistoryWorker");
39
+ hooks.historyImportStarted.resolve();
40
+ await hooks.releaseHistoryImport.promise;
41
+ return { runClaudeHistoryWorker: hooks.runClaudeHistoryWorker };
42
+});
43
+
44
+const layerCliRuntime = Layer.mergeAll(NodeServices.layer, NetService.layer);
45
+const runCli = (args: ReadonlyArray<string>) =>
46
+ Command.runWith(cli, { version: "0.0.0" })(args).pipe(Effect.provide(layerCliRuntime));
47
+
48
+it.layer(NodeServices.layer)("CLI deferred imports", (it) => {
49
+ it.effect("runs commands that do not need them without loading them", () =>
50
+ Effect.gen(function* () {
51
+ hooks.importsAttempted.length = 0;
52
+ for (const args of [["--version"], ["--help"], ["project", "--help"], ["thread", "--help"]]) {
53
+ yield* runCli(args);
54
+ }
55
+ assert.deepEqual(hooks.importsAttempted, []);
56
+ }),
57
+ );
58
+
59
+ it.effect("fails a server start on a broken import before resolving config", () =>
60
+ Effect.gen(function* () {
61
+ const fs = yield* FileSystem.FileSystem;
62
+ const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-deferred-server-" });
63
+ const baseDir = NodePath.join(root, "state");
64
+
65
+ for (const command of ["serve", "start"]) {
66
+ const exit = yield* runCli([command, "--base-dir", baseDir]).pipe(Effect.exit);
67
+ assert.isTrue(Exit.hasDies(exit));
68
+ }
69
+
70
+ assert.isFalse(yield* fs.exists(baseDir));
71
+ }),
72
+ );
73
+
74
+ it.effect("keeps server state when the offline project runtime fails to import", () =>
75
+ Effect.gen(function* () {
76
+ const fs = yield* FileSystem.FileSystem;
77
+ const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-deferred-project-" });
78
+ const baseDir = NodePath.join(root, "state");
79
+ const runtimeStatePath = NodePath.join(baseDir, "userdata", "server-runtime.json");
80
+ yield* persistServerRuntimeState({
81
+ path: runtimeStatePath,
82
+ state: yield* makePersistedServerRuntimeState({
83
+ config: { host: "127.0.0.1", devUrl: undefined },
84
+ port: 3_773,
85
+ }),
86
+ });
87
+ const unreachable: typeof globalThis.fetch = () =>
88
+ Promise.reject(new Error("connection refused"));
89
+
90
+ const exit = yield* runCli(["project", "add", root, "--base-dir", baseDir]).pipe(
91
+ Effect.provideService(FetchHttpClient.Fetch, unreachable),
92
+ Effect.exit,
93
+ );
94
+
95
+ assert.isTrue(Exit.hasDies(exit));
96
+ assert.isTrue(yield* fs.exists(runtimeStatePath));
97
+ assert.isFalse(yield* fs.exists(NodePath.join(baseDir, "userdata", "server-owner.sqlite")));
98
+ }),
99
+ );
100
+
101
+ it.effect("forwards live project mutations without importing the offline runtime", () =>
102
+ Effect.gen(function* () {
103
+ const fs = yield* FileSystem.FileSystem;
104
+ const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-deferred-live-project-" });
105
+ const baseDir = NodePath.join(root, "state");
106
+ const workspaceRoot = NodePath.join(root, "workspace");
107
+ yield* fs.makeDirectory(workspaceRoot);
108
+ yield* persistServerRuntimeState({
109
+ path: NodePath.join(baseDir, "userdata", "server-runtime.json"),
110
+ state: yield* makePersistedServerRuntimeState({
111
+ config: { host: "127.0.0.1", devUrl: undefined },
112
+ port: 3_773,
113
+ }),
114
+ });
115
+
116
+ hooks.importsAttempted.length = 0;
117
+ let mutations = 0;
118
+ const fetch: typeof globalThis.fetch = async (_input, init) => {
119
+ const isMutation = init?.method === "POST";
120
+ if (isMutation) mutations++;
121
+ return Response.json(
122
+ isMutation
123
+ ? {
124
+ id: "live-project",
125
+ title: NodePath.basename(workspaceRoot),
126
+ workspaceRoot,
127
+ defaultModelSelection: null,
128
+ scripts: [],
129
+ createdAt: "2026-01-01T00:00:00.000Z",
130
+ updatedAt: "2026-01-01T00:00:00.000Z",
131
+ deletedAt: null,
132
+ }
133
+ : { projects: [], updatedAt: "2026-01-01T00:00:00.000Z" },
134
+ );
135
+ };
136
+
137
+ const exit = yield* runCli(["project", "add", workspaceRoot, "--base-dir", baseDir]).pipe(
138
+ Effect.provideService(FetchHttpClient.Fetch, fetch),
139
+ Effect.exit,
140
+ );
141
+
142
+ assert.isTrue(Exit.isSuccess(exit));
143
+ assert.equal(mutations, 1);
144
+ assert.deepEqual(hooks.importsAttempted, []);
145
+ }),
146
+ );
147
+
148
+ it.effect("never starts the history worker after an interrupted import", () =>
149
+ Effect.gen(function* () {
150
+ const history = yield* runCli(["__claude-history", "getSessionMessages", "session"]).pipe(
151
+ Effect.forkChild,
152
+ );
153
+ yield* Effect.promise(() => hooks.historyImportStarted.promise);
154
+ yield* Fiber.interrupt(history);
155
+ hooks.releaseHistoryImport.resolve();
156
+ yield* Effect.promise(() => import("../claudeHistoryWorker.ts"));
157
+ assert.equal(hooks.runClaudeHistoryWorker.mock.calls.length, 0);
158
+
159
+ yield* runCli(["__claude-history", "getSessionMessages", "session"]);
160
+ yield* runCli(["__claude-history", "forkSession", "session", '{"dir":"/repo"}']);
161
+ assert.deepEqual(hooks.runClaudeHistoryWorker.mock.calls, [
162
+ ["getSessionMessages", "session", undefined],
163
+ ["forkSession", "session", '{"dir":"/repo"}'],
164
+ ]);
165
+ }),
166
+ );
167
+});
apps/server/src/cli/project.ts
+22
-17
@@ -28,7 +28,7 @@ import * as ServerConfig from "../config.ts";
28
import * as SqlitePersistence from "../persistence/Sqlite.ts";
29
import * as ProcessRunner from "../processRunner.ts";
30
import * as ServerOwnership from "../serverOwnership.ts";
31
-import * as RuntimeLayer from "../orchestration-v2/runtimeLayer.ts";
31
+import type * as RuntimeLayer from "../orchestration-v2/runtimeLayer.ts";
32
import * as ProjectEnrichmentService from "../project/ProjectEnrichmentService.ts";
33
import * as ProjectFaviconResolver from "../project/ProjectFaviconResolver.ts";
34
import * as RepositoryIdentityResolver from "../project/RepositoryIdentityResolver.ts";
@@ -201,23 +201,24 @@ const projectCommandUuid = Crypto.Crypto.pipe(
201
),
202
);
203
204
-const layerProjectCliRuntime = RuntimeLayer.layerProjectService.pipe(
205
- Layer.provideMerge(ProjectEnrichmentService.layer),
206
- Layer.provideMerge(RepositoryIdentityResolver.layer),
207
- Layer.provideMerge(
208
- ProjectFaviconResolver.layer.pipe(
209
- Layer.provide(WorkspacePaths.layer),
210
- Layer.provide(T3ProjectFileLoader.layer),
204
+const makeProjectCliRuntimeLayer = (layerProjectService: typeof RuntimeLayer.layerProjectService) =>
205
+ layerProjectService.pipe(
206
+ Layer.provideMerge(ProjectEnrichmentService.layer),
207
+ Layer.provideMerge(RepositoryIdentityResolver.layer),
208
+ Layer.provideMerge(
209
+ ProjectFaviconResolver.layer.pipe(
210
+ Layer.provide(WorkspacePaths.layer),
211
+ Layer.provide(T3ProjectFileLoader.layer),
212
+ ),
213
),
212
- ),
213
- Layer.provideMerge(WorkspacePaths.layer),
214
- Layer.provideMerge(
215
- ServerSettings.layer.pipe(
216
- Layer.provide(Layer.merge(ServerSecretStore.layer, ManagedPolicy.layer)),
214
+ Layer.provideMerge(WorkspacePaths.layer),
215
+ Layer.provideMerge(
216
+ ServerSettings.layer.pipe(
217
+ Layer.provide(Layer.merge(ServerSecretStore.layer, ManagedPolicy.layer)),
218
+ ),
219
),
218
- ),
219
- Layer.provideMerge(SqlitePersistence.layerConfig),
220
-);
220
+ Layer.provideMerge(SqlitePersistence.layerConfig),
221
+ );
222
223
const PROJECT_CLI_LIVE_SERVER_PROBE_TIMEOUT = Duration.seconds(1);
224
const PROJECT_CLI_LIVE_SERVER_REQUEST_TIMEOUT = Duration.seconds(10);
@@ -426,7 +427,11 @@ const runProjectMutation = Effect.fn("runProjectMutation")(function* (
427
);
428
}
429
429
- const layerOfflineRuntime = layerProjectCliRuntime.pipe(
430
+ // Before ownership and clearing, so a failed import leaves server state alone.
431
+ const { layerProjectService } = yield* Effect.promise(
432
+ () => import("../orchestration-v2/runtimeLayer.ts"),
433
+ );
434
+ const layerOfflineRuntime = makeProjectCliRuntimeLayer(layerProjectService).pipe(
435
Layer.provide(ServerConfig.layer(config)),
436
Layer.provide(Layer.succeed(References.MinimumLogLevel, minimumLogLevel)),
437
);
apps/server/src/cli/server.ts
+2
-1
@@ -8,7 +8,6 @@ import * as CliError from "effect/cli/CliError";
8
9
import * as ServerConfig from "../config.ts";
10
import { awaitLauncherLoss } from "../launcherWatch.ts";
11
-import { runServer } from "../server.ts";
11
import { type CliServerFlags, resolveServerConfig, sharedServerCommandFlags } from "./config.ts";
12
13
const encodeCommand = Schema.encodeEffect(Schema.fromJsonString(Schema.String));
@@ -28,6 +27,8 @@ const runServerCommand = Effect.fn("server.runServerCommand")(function* (
27
readonly rejectRunningServer?: boolean;
28
},
29
) {
30
+ // Before config resolution, which claims a port and creates directories.
31
+ const { runServer } = yield* Effect.promise(() => import("../server.ts"));
32
const logLevel = yield* GlobalFlag.LogLevel;
33
const config = yield* resolveServerConfig(flags, logLevel, options);
34
const run = runServer.pipe(Effect.provideService(ServerConfig.ServerConfig, config));