@devries-cameron20 / t3code-1 / commits / d13fc84670
Fork 0

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

feat(claude): idle compaction has a global default and per-instance overrides (#23037)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Julius Marminge committed Oct 21, 2026 at 12:47 UTC d13fc846700e5bb7d63e1bfaabb1e55733912b21
10 files changed +154 -23
apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
+14
@@ -97,6 +97,7 @@ import {
97 type ProviderThreadId,
98 type RunId,
99 type ThreadId,
100 + resolveIdleCompaction,
101 } from "@t3tools/contracts";
102
103 import * as Cause from "effect/Cause";
@@ -133,6 +134,7 @@ import {
134 type CompiledClaudeModelSelection,
135 } from "../../claudeModelOptions.ts";
136 import * as ServerConfig from "../../config.ts";
137 +import * as ServerSettings from "../../serverSettings.ts";
138 import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion";
139 import { spawnAndCollect } from "@t3tools/provider-core/server/snapshotProbe";
140 import { signalProcessGroup } from "@t3tools/provider-core/server/processGroup";
@@ -3886,6 +3888,7 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
3888 adapterOptions: ClaudeAdapterV2Options,
3889 ) {
3890 const mcpSessions = yield* McpProviderSessions.McpProviderSessions;
3891 + const serverSettings = yield* Effect.serviceOption(ServerSettings.ServerSettingsService);
3892 const { attachmentsDir, fileSystem, path, crypto, idAllocator, queryRunner } = adapterOptions;
3893 const subagentModelCatalog = scopeClaudeModelCatalog(
3894 BUNDLED_CLAUDE_MODEL_CATALOG,
@@ -9036,6 +9039,17 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
9039 if (request.dialogKind !== "resume_return") {
9040 return { behavior: "cancelled" as const };
9041 }
9042 + const idleCompaction = Option.isSome(serverSettings)
9043 + ? yield* serverSettings.value.getSettings.pipe(
9044 + Effect.map((settings) =>
9045 + resolveIdleCompaction(settings, adapterOptions.instanceId),
9046 + ),
9047 + Effect.orElseSucceed(() => adapterOptions.settings.idleCompaction),
9048 + )
9049 + : adapterOptions.settings.idleCompaction;
9050 + if (idleCompaction === "off") {
9051 + return { behavior: "completed" as const, result: "continue" as const };
9052 + }
9053 const ageMinutes =
9054 typeof request.payload.sessionAgeMinutes === "number" &&
9055 Number.isFinite(request.payload.sessionAgeMinutes)
apps/server/src/orchestration-v2/IdleCompactionService.ts
+6 -3
@@ -1,6 +1,7 @@
1 import {
2 CommandId,
3 MessageId,
4 + resolveIdleCompaction,
5 resolveProjectProviderInstanceEnabled,
6 type RunId,
7 type ThreadId,
@@ -18,8 +19,9 @@ import * as Orchestrator from "./Orchestrator.ts";
19 import * as ProjectionStore from "./ProjectionStore.ts";
20
21 /**
21 - * Beta: when a Claude run completes, waits until shortly before its prompt
22 - * cache expires and sends `/compact` as a visible T3 Code turn. Timers live in
22 + * Beta: when a run completes on a Claude instance set to compact before the
23 + * cache expires, waits until shortly before its prompt cache expires and sends
24 + * `/compact` as a visible T3 Code turn. Timers live in
25 * memory, so a server restart skips compactions that were still waiting.
26 */
27 export const make = Effect.gen(function* () {
@@ -32,7 +34,6 @@ export const make = Effect.gen(function* () {
34 // Loops once after the wait: the thread may have moved on.
35 while (true) {
36 const current = yield* settings.getSettings;
35 - if (!current.compactIdleThreads) return;
37 const records = yield* projections.getThreadRecords(
38 threadId,
39 [
@@ -47,6 +48,8 @@ export const make = Effect.gen(function* () {
48 { messageRunIds: [runId], turnItemStatuses: ["pending", "running", "waiting"] },
49 );
50 if (
51 + resolveIdleCompaction(current, records.thread.providerInstanceId) !==
52 + "beforeCacheExpires" ||
53 !resolveProjectProviderInstanceEnabled(
54 current,
55 records.thread.projectId,
apps/server/src/provider/ProviderInstanceRegistry.test.ts
+1
@@ -97,6 +97,7 @@ const makeClaudeConfig = (overrides: Partial<ClaudeSettings>): ClaudeSettings =>
97 customModels: [],
98 launchArgs: "",
99 autoCompactWindow: "",
100 + idleCompaction: "default",
101 ...overrides,
102 });
103
apps/web/src/components/ChatView.tsx
+5
@@ -70,6 +70,7 @@ import {
70 type RunId,
71 type RunAttemptId,
72 ProviderInteractionMode,
73 + resolveIdleCompaction,
74 RuntimeMode,
75 } from "@t3tools/contracts";
76 import { deriveThreadTitleSeed } from "@t3tools/client-runtime/operations";
@@ -4011,6 +4012,10 @@ export default function ChatView(props: ChatViewProps) {
4012 : null;
4013 const resumeCompactionTokens =
4014 activeContextWindow &&
4015 + resolveIdleCompaction(
4016 + settings,
4017 + activeProviderInstanceId ?? ProviderInstanceId.make("claudeAgent"),
4018 + ) !== "off" &&
4019 !resumeCompactionPermanentlyDismissed &&
4020 !nativeResumeCompactionDismissed &&
4021 !compactDisabled &&
apps/web/src/components/settings/SettingsPanels.tsx
+26 -10
@@ -6,6 +6,7 @@ import { Link, useNavigate } from "@tanstack/react-router";
6 import { useEffect, useRef, useState } from "react";
7 import {
8 type DesktopUpdateChannel,
9 + IDLE_COMPACTION_MODES,
10 ProviderDriverKind,
11 type ProviderInstanceId,
12 type SidebarProjectGroupingMode,
@@ -997,11 +998,11 @@ export function GeneralSettingsPanel() {
998 serverScoped
999 settingKeys={["compactIdleThreads"]}
1000 {...searchableSetting("compact-idle-threads")}
1000 - description="Compact long idle Claude threads just before their prompt cache expires, so coming back costs less."
1001 + description="When to compact an idle Claude thread over 200,000 tokens: after you return, just before its prompt cache expires, or never. Each Claude provider can override this."
1002 resetAction={
1003 settings.compactIdleThreads !== DEFAULT_UNIFIED_SETTINGS.compactIdleThreads ? (
1004 <SettingResetButton
1004 - label="compact idle Claude threads"
1005 + label="compact idle threads"
1006 onClick={() =>
1007 updateSettings({
1008 compactIdleThreads: DEFAULT_UNIFIED_SETTINGS.compactIdleThreads,
@@ -1011,14 +1012,29 @@ export function GeneralSettingsPanel() {
1012 ) : null
1013 }
1014 control={
1014 - <ScopedSwitch
1015 - settingKeys={["compactIdleThreads"]}
1016 - checked={settings.compactIdleThreads}
1017 - onCheckedChange={(checked) =>
1018 - updateSettings({ compactIdleThreads: Boolean(checked) })
1019 - }
1020 - aria-label="Compact idle Claude threads (beta)"
1021 - />
1015 + <Select
1016 + value={settings.compactIdleThreads}
1017 + onValueChange={(value) => {
1018 + const mode = IDLE_COMPACTION_MODES.find((candidate) => candidate.value === value);
1019 + if (mode) updateSettings({ compactIdleThreads: mode.value });
1020 + }}
1021 + >
1022 + <SelectTrigger size="sm" className="w-full sm:w-56" aria-label="Compact idle threads">
1023 + <SelectValue>
1024 + {
1025 + IDLE_COMPACTION_MODES.find((mode) => mode.value === settings.compactIdleThreads)
1026 + ?.label
1027 + }
1028 + </SelectValue>
1029 + </SelectTrigger>
1030 + <SelectPopup align="end" alignItemWithTrigger={false}>
1031 + {IDLE_COMPACTION_MODES.map((mode) => (
1032 + <SelectItem hideIndicator key={mode.value} value={mode.value}>
1033 + {mode.label}
1034 + </SelectItem>
1035 + ))}
1036 + </SelectPopup>
1037 + </Select>
1038 }
1039 />
1040
apps/web/src/components/settings/settingsSearch.ts
+2 -2
@@ -338,10 +338,10 @@ export const SETTINGS_SEARCH_ITEMS = [
338 },
339 {
340 id: "compact-idle-threads",
341 - title: "Compact idle Claude threads (beta)",
341 + title: "Compact idle threads",
342 to: "/settings/general",
343 scope: "environment-defaults",
344 - searchTerms: ["context compaction idle cache tokens usage summary beta experimental"],
344 + searchTerms: ["claude context compaction idle cache tokens usage summary resume"],
345 },
346 {
347 id: "auto-settle-merged-threads",
docs/user/composer.md
+2 -5
@@ -239,11 +239,8 @@ Provider commands must start the message to run. T3 Code commands such as
239 Send `/compact` in an existing conversation to reduce context usage when the
240 provider supports it. Web and desktop also offer compaction from the context meter.
241
242 -Enable **Compact idle Claude threads (beta)** in **Settings > General** to compact
243 -an idle Claude thread with at least 200,000 tokens of context shortly before its
244 -prompt cache expires, so coming back does not reprocess the whole conversation.
245 -The cache lasts 1 hour on Claude subscriptions and 5 minutes with an API key. The
246 -compaction appears in the thread as a `/compact` turn sent by T3 Code.
242 +Claude instances can also compact idle threads for you. See
243 +[compact long conversations](./providers-claude.md#compact-long-conversations).
244
245 ## Goals
246
docs/user/providers-claude.md
+10
@@ -57,6 +57,16 @@ history for that message. The cache lasts about an hour on a Claude
57 subscription and 5 minutes with an API key, Bedrock, or Vertex. See [commands and skills](./composer.md#commands-and-skills) for using
58 composer commands.
59
60 +**Compact idle threads** in **Settings > General** controls this for threads
61 +over 200,000 tokens. Each Claude provider's settings can override it:
62 +
63 +- **When you return** shows the **Compact** chip described above. This is the default.
64 +- **Before the cache expires (beta)** compacts an idle thread shortly before its
65 + prompt cache expires, so coming back does not reprocess the whole conversation.
66 + The compaction appears in the thread as a `/compact` turn sent by T3 Code.
67 +- **Never** skips idle compaction and Claude's resume prompt. **Auto-compact after**
68 + still applies, and you can still compact by hand.
69 +
70 ## Usage limits
71
72 If your Claude subscription runs out of usage mid-turn, the thread shows which
packages/contracts/src/settings.test.ts
+25
@@ -9,6 +9,7 @@ import {
9 ClaudeSettings,
10 DEFAULT_SERVER_SETTINGS,
11 requiredScopesForProjectMutation,
12 + resolveIdleCompaction,
13 resolveProjectProviderInstanceEnabled,
14 resolveProviderInstanceEnabled,
15 ServerSettings,
@@ -134,6 +135,30 @@ describe("custom model settings", () => {
135 });
136 });
137
138 +describe("resolveIdleCompaction", () => {
139 + it("lets a Claude instance override the global default", () => {
140 + const settings = decodeServerSettings({
141 + compactIdleThreads: "off",
142 + providerInstances: {
143 + claude_work: { driver: "claudeAgent", config: { idleCompaction: "onReturn" } },
144 + claude_personal: { driver: "claudeAgent" },
145 + },
146 + });
147 + expect(resolveIdleCompaction(settings, ProviderInstanceId.make("claude_work"))).toBe(
148 + "onReturn",
149 + );
150 + expect(resolveIdleCompaction(settings, ProviderInstanceId.make("claude_personal"))).toBe("off");
151 + expect(resolveIdleCompaction(settings, ProviderInstanceId.make("claudeAgent"))).toBe("off");
152 + });
153 +
154 + it("keeps the legacy beta switch's behavior", () => {
155 + expect(decodeServerSettings({ compactIdleThreads: true }).compactIdleThreads).toBe(
156 + "beforeCacheExpires",
157 + );
158 + expect(decodeServerSettings({}).compactIdleThreads).toBe("onReturn");
159 + });
160 +});
161 +
162 describe("ClientSettings notifications", () => {
163 it("requires opt-in when existing settings omit notification preferences", () => {
164 expect(decodeClientSettings({}).notificationMode).toBe("off");
packages/contracts/src/settings.ts
+63 -3
@@ -6,6 +6,7 @@ import {
6 type AuthEnvironmentScope,
7 } from "./auth.ts";
8 import * as Effect from "effect/Effect";
9 +import * as Option from "effect/Option";
10 import * as Duration from "effect/Duration";
11 import * as Schema from "effect/Schema";
12 import * as SchemaTransformation from "effect/SchemaTransformation";
@@ -643,6 +644,34 @@ export type CodexSettings = typeof CodexSettings.Type;
644
645 const CLAUDE_AUTO_COMPACT_WINDOW_PATTERN = /^(?:|[1-9]\d{5}|1000000)$/;
646
647 +export const IDLE_COMPACTION_MODES = [
648 + { value: "onReturn", label: "When you return" },
649 + { value: "beforeCacheExpires", label: "Before the cache expires (beta)" },
650 + { value: "off", label: "Never" },
651 +] as const;
652 +export const IdleCompactionMode = Schema.Literals(IDLE_COMPACTION_MODES.map((mode) => mode.value));
653 +export type IdleCompactionMode = typeof IdleCompactionMode.Type;
654 +
655 +// `compactIdleThreads` was a beta on/off switch for compacting before the cache expires.
656 +const LegacyCompactIdleThreads = Schema.Boolean.pipe(
657 + Schema.decodeTo(
658 + IdleCompactionMode,
659 + SchemaTransformation.transform({
660 + decode: (enabled): IdleCompactionMode => (enabled ? "beforeCacheExpires" : "onReturn"),
661 + encode: (mode) => mode === "beforeCacheExpires",
662 + }),
663 + ),
664 +);
665 +const IdleCompactionModeSetting = Schema.Union([IdleCompactionMode, LegacyCompactIdleThreads]);
666 +
667 +const INSTANCE_IDLE_COMPACTION_MODES = [
668 + { value: "default", label: "Use default" },
669 + ...IDLE_COMPACTION_MODES,
670 +] as const;
671 +const InstanceIdleCompaction = Schema.Literals(
672 + INSTANCE_IDLE_COMPACTION_MODES.map((mode) => mode.value),
673 +);
674 +
675 export const ClaudeSettings = makeProviderSettingsSchema(
676 {
677 enabled: Schema.Boolean.pipe(
@@ -694,9 +723,22 @@ export const ClaudeSettings = makeProviderSettingsSchema(
723 },
724 }),
725 ),
726 + idleCompaction: InstanceIdleCompaction.pipe(
727 + Schema.withDecodingDefault(Effect.succeed("default" as const)),
728 + Schema.annotateKey({
729 + title: "Compact idle threads",
730 + description:
731 + "When to compact an idle thread over 200,000 tokens: after you return, just before its prompt cache expires, or never. Overrides the default in General settings.",
732 + providerSettingsForm: {
733 + control: "select",
734 + options: INSTANCE_IDLE_COMPACTION_MODES,
735 + clearWhenEmpty: "omit",
736 + },
737 + }),
738 + ),
739 },
740 {
699 - order: ["binaryPath", "homePath", "autoCompactWindow", "launchArgs"],
741 + order: ["binaryPath", "homePath", "autoCompactWindow", "idleCompaction", "launchArgs"],
742 },
743 );
744 export type ClaudeSettings = typeof ClaudeSettings.Type;
@@ -1160,7 +1202,9 @@ export const ServerSettings = Schema.Struct({
1202 sidebarAutoSettleAfterDays: Schema.NullOr(SidebarAutoSettleAfterDays).pipe(
1203 Schema.withDecodingDefault(Effect.succeed(DEFAULT_SIDEBAR_AUTO_SETTLE_AFTER_DAYS)),
1204 ),
1163 - compactIdleThreads: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
1205 + compactIdleThreads: IdleCompactionModeSetting.pipe(
1206 + Schema.withDecodingDefault(Effect.succeed("onReturn" as const)),
1207 + ),
1208 snoozeLimitedThreads: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
1209 autoResumeLimitedThreads: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
1210 sidebarAutoSettleKeepPullRequests: Schema.Boolean.pipe(
@@ -1334,6 +1378,22 @@ export const resolveProjectProviderInstanceEnabled = (
1378 : isUnconfiguredDefaultInstanceEnabled(instanceId);
1379 };
1380
1381 +const decodeClaudeSettings = Schema.decodeUnknownOption(ClaudeSettings);
1382 +
1383 +export const resolveIdleCompaction = (
1384 + settings: Pick<ServerSettings, "providerInstances" | "compactIdleThreads">,
1385 + instanceId: ProviderInstanceId,
1386 +): IdleCompactionMode => {
1387 + const instance = Object.hasOwn(settings.providerInstances, instanceId)
1388 + ? settings.providerInstances[instanceId]
1389 + : undefined;
1390 + const override = decodeClaudeSettings(instance?.config ?? {}).pipe(
1391 + Option.map((config) => config.idleCompaction),
1392 + Option.getOrElse(() => "default" as const),
1393 + );
1394 + return override === "default" ? settings.compactIdleThreads : override;
1395 +};
1396 +
1397 export const ServerSettingsOperation = Schema.Literals([
1398 "normalize",
1399 "check-exists",
@@ -1475,7 +1535,7 @@ export const ServerSettingsPatch = Schema.Struct({
1535 deviceHosts: Schema.optionalKey(SshDeviceHostConfigs),
1536 easDeviceHosts: Schema.optionalKey(EasDeviceHostConfigs),
1537 sidebarAutoSettleAfterDays: Schema.optionalKey(Schema.NullOr(SidebarAutoSettleAfterDays)),
1478 - compactIdleThreads: Schema.optionalKey(Schema.Boolean),
1538 + compactIdleThreads: Schema.optionalKey(IdleCompactionMode),
1539 sidebarAutoSettleKeepPullRequests: Schema.optionalKey(Schema.Boolean),
1540 sidebarAutoSettleOnMerge: Schema.optionalKey(Schema.Boolean),
1541 autoResumeLimitedThreads: Schema.optionalKey(Schema.Boolean),