Skip to content

Commit 98da75e

Browse files
feat(claude): idle compaction is configurable per provider instance
Each Claude instance now has a "Compact idle threads" setting: When you return (the existing Compact chip and resume prompt), Before the cache expires (the former global beta toggle), or Never. Never hides the chip and answers Claude's resume prompt with "keep full history". Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 0bdf33a commit 98da75e

10 files changed

Lines changed: 87 additions & 47 deletions

File tree

‎apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8987,6 +8987,9 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
89878987
if (request.dialogKind !== "resume_return") {
89888988
return { behavior: "cancelled" as const };
89898989
}
8990+
if (adapterOptions.settings.idleCompaction === "off") {
8991+
return { behavior: "completed" as const, result: "continue" as const };
8992+
}
89908993
const ageMinutes =
89918994
typeof request.payload.sessionAgeMinutes === "number" &&
89928995
Number.isFinite(request.payload.sessionAgeMinutes)

‎apps/server/src/orchestration-v2/IdleCompactionService.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import {
22
CommandId,
33
MessageId,
4+
resolveClaudeIdleCompaction,
45
resolveProjectProviderInstanceEnabled,
56
type RunId,
67
type ThreadId,
@@ -18,8 +19,9 @@ import * as Orchestrator from "./Orchestrator.ts";
1819
import * as ProjectionStore from "./ProjectionStore.ts";
1920

2021
/**
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
2325
* memory, so a server restart skips compactions that were still waiting.
2426
*/
2527
export const make = Effect.gen(function* () {
@@ -32,7 +34,6 @@ export const make = Effect.gen(function* () {
3234
// Loops once after the wait: the thread may have moved on.
3335
while (true) {
3436
const current = yield* settings.getSettings;
35-
if (!current.compactIdleThreads) return;
3637
const records = yield* projections.getThreadRecords(
3738
threadId,
3839
[
@@ -47,6 +48,8 @@ export const make = Effect.gen(function* () {
4748
{ messageRunIds: [runId], turnItemStatuses: ["pending", "running", "waiting"] },
4849
);
4950
if (
51+
resolveClaudeIdleCompaction(current, records.thread.providerInstanceId) !==
52+
"beforeCacheExpires" ||
5053
!resolveProjectProviderInstanceEnabled(
5154
current,
5255
records.thread.projectId,

‎apps/server/src/provider/ProviderInstanceRegistry.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,7 @@ const makeClaudeConfig = (overrides: Partial<ClaudeSettings>): ClaudeSettings =>
9797
customModels: [],
9898
launchArgs: "",
9999
autoCompactWindow: "",
100+
idleCompaction: "onReturn",
100101
...overrides,
101102
});
102103

‎apps/web/src/components/ChatView.tsx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ import {
7070
type RunId,
7171
type RunAttemptId,
7272
ProviderInteractionMode,
73+
resolveClaudeIdleCompaction,
7374
RuntimeMode,
7475
} from "@t3tools/contracts";
7576
import { deriveThreadTitleSeed } from "@t3tools/client-runtime/operations";
@@ -4011,6 +4012,10 @@ export default function ChatView(props: ChatViewProps) {
40114012
: null;
40124013
const resumeCompactionTokens =
40134014
activeContextWindow &&
4015+
resolveClaudeIdleCompaction(
4016+
settings,
4017+
activeProviderInstanceId ?? ProviderInstanceId.make("claudeAgent"),
4018+
) !== "off" &&
40144019
!resumeCompactionPermanentlyDismissed &&
40154020
!nativeResumeCompactionDismissed &&
40164021
!compactDisabled &&

‎apps/web/src/components/settings/SettingsPanels.tsx‎

Lines changed: 0 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -993,35 +993,6 @@ export function GeneralSettingsPanel() {
993993
}
994994
/>
995995

996-
<SettingsRow
997-
serverScoped
998-
settingKeys={["compactIdleThreads"]}
999-
{...searchableSetting("compact-idle-threads")}
1000-
description="Compact long idle Claude threads just before their prompt cache expires, so coming back costs less."
1001-
resetAction={
1002-
settings.compactIdleThreads !== DEFAULT_UNIFIED_SETTINGS.compactIdleThreads ? (
1003-
<SettingResetButton
1004-
label="compact idle Claude threads"
1005-
onClick={() =>
1006-
updateSettings({
1007-
compactIdleThreads: DEFAULT_UNIFIED_SETTINGS.compactIdleThreads,
1008-
})
1009-
}
1010-
/>
1011-
) : null
1012-
}
1013-
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-
/>
1022-
}
1023-
/>
1024-
1025996
{supportsAutoSettlement ? (
1026997
<>
1027998
<SettingsRow

‎apps/web/src/components/settings/settingsSearch.ts‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -336,13 +336,6 @@ export const SETTINGS_SEARCH_ITEMS = [
336336
requiresThreadAutoSettlement: true,
337337
scope: "project-defaults",
338338
},
339-
{
340-
id: "compact-idle-threads",
341-
title: "Compact idle Claude threads (beta)",
342-
to: "/settings/general",
343-
scope: "environment-defaults",
344-
searchTerms: ["context compaction idle cache tokens usage summary beta experimental"],
345-
},
346339
{
347340
id: "auto-settle-merged-threads",
348341
title: "Auto-settle merged threads",

‎docs/user/composer.md‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -239,11 +239,8 @@ Provider commands must start the message to run. T3 Code commands such as
239239
Send `/compact` in an existing conversation to reduce context usage when the
240240
provider supports it. Web and desktop also offer compaction from the context meter.
241241

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).
247244

248245
## Goals
249246

‎docs/user/providers-claude.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,16 @@ history for that message. The cache lasts about an hour on a Claude
5757
subscription and 5 minutes with an API key, Bedrock, or Vertex. See [commands and skills](./composer.md#commands-and-skills) for using
5858
composer commands.
5959

60+
**Compact idle threads** in each Claude provider's settings controls this for
61+
threads over 200,000 tokens:
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** keeps the full history and skips Claude's resume prompt. You can still
68+
compact by hand.
69+
6070
## Usage limits
6171

6272
If your Claude subscription runs out of usage mid-turn, the thread shows which

‎packages/contracts/src/settings.test.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import {
99
ClaudeSettings,
1010
DEFAULT_SERVER_SETTINGS,
1111
requiredScopesForProjectMutation,
12+
resolveClaudeIdleCompaction,
1213
resolveProjectProviderInstanceEnabled,
1314
resolveProviderInstanceEnabled,
1415
ServerSettings,
@@ -134,6 +135,26 @@ describe("custom model settings", () => {
134135
});
135136
});
136137

138+
describe("resolveClaudeIdleCompaction", () => {
139+
it("reads each Claude instance's own mode and defaults to compacting on return", () => {
140+
const settings = decodeServerSettings({
141+
providerInstances: {
142+
claude_work: { driver: "claudeAgent", config: { idleCompaction: "off" } },
143+
claude_personal: { driver: "claudeAgent" },
144+
},
145+
});
146+
expect(resolveClaudeIdleCompaction(settings, ProviderInstanceId.make("claude_work"))).toBe(
147+
"off",
148+
);
149+
expect(resolveClaudeIdleCompaction(settings, ProviderInstanceId.make("claude_personal"))).toBe(
150+
"onReturn",
151+
);
152+
expect(resolveClaudeIdleCompaction(settings, ProviderInstanceId.make("claudeAgent"))).toBe(
153+
"onReturn",
154+
);
155+
});
156+
});
157+
137158
describe("ClientSettings notifications", () => {
138159
it("requires opt-in when existing settings omit notification preferences", () => {
139160
expect(decodeClientSettings({}).notificationMode).toBe("off");

‎packages/contracts/src/settings.ts‎

Lines changed: 39 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ import {
66
type AuthEnvironmentScope,
77
} from "./auth.ts";
88
import * as Effect from "effect/Effect";
9+
import * as Option from "effect/Option";
910
import * as Duration from "effect/Duration";
1011
import * as Schema from "effect/Schema";
1112
import * as SchemaTransformation from "effect/SchemaTransformation";
@@ -643,6 +644,16 @@ export type CodexSettings = typeof CodexSettings.Type;
643644

644645
const CLAUDE_AUTO_COMPACT_WINDOW_PATTERN = /^(?:|[1-9]\d{5}|1000000)$/;
645646

647+
const CLAUDE_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+
const ClaudeIdleCompaction = Schema.Literals(
653+
CLAUDE_IDLE_COMPACTION_MODES.map((mode) => mode.value),
654+
);
655+
export type ClaudeIdleCompaction = typeof ClaudeIdleCompaction.Type;
656+
646657
export const ClaudeSettings = makeProviderSettingsSchema(
647658
{
648659
enabled: Schema.Boolean.pipe(
@@ -694,9 +705,22 @@ export const ClaudeSettings = makeProviderSettingsSchema(
694705
},
695706
}),
696707
),
708+
idleCompaction: ClaudeIdleCompaction.pipe(
709+
Schema.withDecodingDefault(Effect.succeed("onReturn" as const)),
710+
Schema.annotateKey({
711+
title: "Compact idle threads",
712+
description:
713+
"When to compact a thread over 200,000 tokens whose prompt cache expired while you were away.",
714+
providerSettingsForm: {
715+
control: "select",
716+
options: CLAUDE_IDLE_COMPACTION_MODES,
717+
clearWhenEmpty: "omit",
718+
},
719+
}),
720+
),
697721
},
698722
{
699-
order: ["binaryPath", "homePath", "autoCompactWindow", "launchArgs"],
723+
order: ["binaryPath", "homePath", "autoCompactWindow", "idleCompaction", "launchArgs"],
700724
},
701725
);
702726
export type ClaudeSettings = typeof ClaudeSettings.Type;
@@ -1160,7 +1184,6 @@ export const ServerSettings = Schema.Struct({
11601184
sidebarAutoSettleAfterDays: Schema.NullOr(SidebarAutoSettleAfterDays).pipe(
11611185
Schema.withDecodingDefault(Effect.succeed(DEFAULT_SIDEBAR_AUTO_SETTLE_AFTER_DAYS)),
11621186
),
1163-
compactIdleThreads: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
11641187
snoozeLimitedThreads: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
11651188
autoResumeLimitedThreads: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(false))),
11661189
sidebarAutoSettleKeepPullRequests: Schema.Boolean.pipe(
@@ -1334,6 +1357,20 @@ export const resolveProjectProviderInstanceEnabled = (
13341357
: isUnconfiguredDefaultInstanceEnabled(instanceId);
13351358
};
13361359

1360+
const decodeClaudeSettings = Schema.decodeUnknownOption(ClaudeSettings);
1361+
1362+
export const resolveClaudeIdleCompaction = (
1363+
settings: Pick<ServerSettings, "providerInstances">,
1364+
instanceId: ProviderInstanceId,
1365+
): ClaudeIdleCompaction => {
1366+
const instance = Object.hasOwn(settings.providerInstances, instanceId)
1367+
? settings.providerInstances[instanceId]
1368+
: undefined;
1369+
return decodeClaudeSettings(instance?.config ?? {}).pipe(
1370+
Option.match({ onNone: () => "onReturn" as const, onSome: (config) => config.idleCompaction }),
1371+
);
1372+
};
1373+
13371374
export const ServerSettingsOperation = Schema.Literals([
13381375
"normalize",
13391376
"check-exists",
@@ -1475,7 +1512,6 @@ export const ServerSettingsPatch = Schema.Struct({
14751512
deviceHosts: Schema.optionalKey(SshDeviceHostConfigs),
14761513
easDeviceHosts: Schema.optionalKey(EasDeviceHostConfigs),
14771514
sidebarAutoSettleAfterDays: Schema.optionalKey(Schema.NullOr(SidebarAutoSettleAfterDays)),
1478-
compactIdleThreads: Schema.optionalKey(Schema.Boolean),
14791515
sidebarAutoSettleKeepPullRequests: Schema.optionalKey(Schema.Boolean),
14801516
sidebarAutoSettleOnMerge: Schema.optionalKey(Schema.Boolean),
14811517
autoResumeLimitedThreads: Schema.optionalKey(Schema.Boolean),

0 commit comments

Comments
 (0)