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 22, 19:30 UTC
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),