Skip to content

Commit cb99f1c

Browse files
baxenclaude
andcommitted
perf(claude-code): one shared spare process instead of one per agent
Each Claude Code agent kept its own warm `claude` process and up to six processes in all. With agents in many communities kept running, that is one idle ~300 MB process per agent. Starting the process is what a spare saves (time to turn start ~530ms cold vs ~45ms warm, measured against claude 2.1.296); sending `initialize` costs almost nothing. So the spare is now spawned without `initialize`, fixing only its folder and model, and the agent that takes it sends its own prompt and installs its own tool handler. One spare serves every agent; it follows the latest new conversation, and is replaced when no agent runs where it was started. The per-agent process cap is removed. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Bradley Axen <[email protected]>
1 parent 9011eb8 commit cb99f1c

6 files changed

Lines changed: 364 additions & 162 deletions

File tree

‎src/bundled/claude-code/claude.ts‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ export class ClaudeProcess {
8989
private constructor(
9090
private readonly process: HostProcess,
9191
resume: string | undefined,
92-
private readonly tools: ToolServer | undefined,
92+
private tools: ToolServer | undefined,
9393
) {
9494
this.sessionId = resume;
9595
this.exited = process.exited.then((code) => {
@@ -104,6 +104,14 @@ export class ClaudeProcess {
104104
}
105105

106106
static async start(spawn: Spawn, launch: ClaudeLaunch) {
107+
const claude = await ClaudeProcess.spawn(spawn, launch);
108+
await claude.initialize(launch);
109+
return claude;
110+
}
111+
112+
/** Starts `claude` without its prompt. This is most of what a start costs,
113+
* and fixes nothing about the agent it serves but its folder and model. */
114+
static async spawn(spawn: Spawn, launch: Omit<ClaudeLaunch, "systemPrompt">) {
107115
let claude: ClaudeProcess | undefined;
108116
const early: string[] = [];
109117
const earlyErrors: string[] = [];
@@ -150,8 +158,14 @@ export class ClaudeProcess {
150158
);
151159
for (const data of earlyErrors) claude.readError(data);
152160
for (const data of early) claude.read(data);
153-
// Loads settings, tools and MCP servers now rather than on the first message.
154-
await claude.request({
161+
return claude;
162+
}
163+
164+
/** Gives a started process its prompt, and its tools to whoever it now
165+
* works for. Loads settings and tools now rather than on the first message. */
166+
async initialize(launch: Pick<ClaudeLaunch, "systemPrompt" | "tools">) {
167+
if (launch.tools) this.tools = launch.tools;
168+
await this.request({
155169
subtype: "initialize",
156170
appendSystemPrompt: launch.systemPrompt,
157171
...(launch.tools
@@ -165,7 +179,6 @@ export class ClaudeProcess {
165179
}
166180
: {}),
167181
});
168-
return claude;
169182
}
170183

171184
get running() {

‎src/bundled/claude-code/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ export const apply: PluginModule["apply"] = (ctx) => {
2828
if (snapshot.status === "loading") return;
2929
runtime.sync(snapshot.running.filter((agent) => agent.type === typeKey));
3030
};
31-
// A spare session is warmed for each running agent.
31+
// One spare session waits for whichever running agent needs it next.
3232
if (spawn) {
3333
const unsubscribe = agents2.subscribe(sync);
3434
sync();

‎src/bundled/claude-code/runtime.test.ts‎

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -294,7 +294,8 @@ it("shows the whole thread to a session started over from a lost one", async ()
294294
);
295295
await deliver({ type: "mention", event: mention });
296296
await flush(20);
297-
const [lost, fresh] = claudes();
297+
const [lost] = claudes();
298+
const fresh = claudes().find((process) => process.prompts.length);
298299
expect(lost?.options.args).toContain("lost");
299300
expect(lost?.prompts).toEqual([]);
300301
expect(fresh?.prompts[0]).toContain('<thread-context included="1" total="2"');
@@ -339,13 +340,31 @@ it("runs a timer in its own session", async () => {
339340
expect(claude?.prompts[0]).toContain("Timer: watch/daily");
340341
});
341342

342-
it("warms a spare for each agent of its type and stops those that go away", async () => {
343+
it("keeps one spare for all its agents, and none once they are gone", async () => {
343344
const { runtime, claudes } = setup();
344-
const agent = { pubkey: self, config: DEFAULT_CONFIG } as Agent;
345-
runtime.sync([agent]);
345+
const agent = (pubkey: string) =>
346+
({ pubkey, config: DEFAULT_CONFIG }) as Agent;
347+
runtime.sync([agent(self), agent(alice)]);
346348
await flush(10);
347349
expect(claudes()).toHaveLength(1);
350+
expect(claudes()[0]?.options.cwd).toBe(DEFAULT_CONFIG.workspace);
348351
runtime.sync([]);
349352
await flush(10);
350353
expect(claudes().every((process) => process.killed)).toBe(true);
351354
});
355+
356+
it("replaces the spare when no agent runs where it was started", async () => {
357+
const { runtime, claudes } = setup();
358+
runtime.sync([{ pubkey: self, config: DEFAULT_CONFIG } as Agent]);
359+
await flush(10);
360+
runtime.sync([
361+
{ pubkey: self, config: { ...DEFAULT_CONFIG, model: "sonnet" } } as Agent,
362+
]);
363+
await flush(10);
364+
const [old, next] = claudes();
365+
expect(old?.killed).toBe(true);
366+
expect(next?.options.args).toEqual(
367+
expect.arrayContaining(["--model", "sonnet"]),
368+
);
369+
expect(claudes()).toHaveLength(2);
370+
});

‎src/bundled/claude-code/runtime.ts‎

Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ import {
2525
timerPrompt,
2626
turnPrompt,
2727
} from "./prompt";
28-
import { AgentSessions, localSessions } from "./sessions";
28+
import { AgentSessions, localSessions, Spare } from "./sessions";
2929

3030
export type Config = Readonly<{
3131
/** A Claude model or alias; empty uses Claude Code's own default. */
@@ -67,6 +67,12 @@ type Entry = {
6767
contexts: Map<string, Context>;
6868
};
6969

70+
/** Where an agent's processes run, and with which model. */
71+
const where = ({ workspace, model }: Config) => ({
72+
cwd: workspace,
73+
...(model.trim() ? { model: model.trim() } : {}),
74+
});
75+
7076
export class ClaudeRuntime {
7177
private readonly agents = new Map<string, Entry>();
7278
private readonly reading = new Map<string, Promise<readonly Memory[]>>();
@@ -77,6 +83,11 @@ export class ClaudeRuntime {
7783
string,
7884
ReturnType<AgentSessions["snapshot"]>
7985
>();
86+
/** One process started ahead of need, for any agent's next new conversation. */
87+
private readonly spare = new Spare(
88+
(id, options) => this.spawn(id, options),
89+
(_conversation, message) => respond(undefined, {}, message),
90+
);
8091

8192
constructor(
8293
private readonly host: Host,
@@ -92,8 +103,9 @@ export class ClaudeRuntime {
92103
return spawn;
93104
}
94105

95-
/** Brings the runtime in line with this type's agents: new ones get a warm
96-
* session, changed settings restart idle sessions, removed agents stop. */
106+
/** Brings the runtime in line with this type's agents: changed settings
107+
* restart idle sessions, removed agents stop, and a spare waits while any
108+
* agent is here. */
97109
sync(agents: readonly Agent[]) {
98110
const current = new Set(agents.map((agent) => agent.pubkey));
99111
// Deleted, signed out or its community disconnected: either way its
@@ -106,12 +118,15 @@ export class ClaudeRuntime {
106118
for (const agent of agents) {
107119
const next = config(agent.config);
108120
const entry = this.agents.get(agent.pubkey);
109-
if (!entry) this.entry(agent.pubkey, next).sessions.warm();
121+
if (!entry) this.entry(agent.pubkey, next);
110122
else if (JSON.stringify(entry.config) !== JSON.stringify(next)) {
111123
entry.config = next;
112124
entry.sessions.reconfigure();
113125
}
114126
}
127+
if (agents.length)
128+
this.spare.warm(...agents.map((agent) => where(config(agent.config))));
129+
else this.spare.stop();
115130
this.notify();
116131
}
117132

@@ -136,6 +151,7 @@ export class ClaudeRuntime {
136151
}
137152

138153
dispose() {
154+
this.spare.dispose();
139155
for (const entry of this.agents.values()) entry.sessions.dispose();
140156
this.agents.clear();
141157
}
@@ -150,6 +166,9 @@ export class ClaudeRuntime {
150166
return;
151167
const entry = this.entry(agent.pubkey, settings);
152168
entry.handle = agent;
169+
// Read while the turn's prompt is built, not after: a new session's prompt
170+
// needs it, and a spare is only faster if nothing else is awaited.
171+
void this.memory(agent.pubkey, entry);
153172
if (trigger.type === "timer") {
154173
const done = entry.sessions.deliver(
155174
`timer/${trigger.slug}`,
@@ -328,8 +347,6 @@ export class ClaudeRuntime {
328347
const tools =
329348
(cwd: string): ToolServer =>
330349
async (conversation, message) => {
331-
// A spare starts before any delivery: it can list the tools, and has a
332-
// handle to call them with by the time it is given a turn.
333350
const handle = entry.handle;
334351
const client = handle && {
335352
...appClient(handle, {
@@ -348,6 +365,7 @@ export class ClaudeRuntime {
348365
};
349366
entry.sessions = new AgentSessions({
350367
spawn: (id, options) => this.spawn(id, options),
368+
spare: this.spare,
351369
store: localSessions(this.storage, pubkey),
352370
onChange: () => this.notify(),
353371
fingerprint: () =>
@@ -358,12 +376,11 @@ export class ClaudeRuntime {
358376
entry.config.scope,
359377
]),
360378
launch: async () => {
361-
const { model, workspace, instructions, scope } = entry.config;
379+
const { workspace, instructions, scope } = entry.config;
362380
const memory = await this.memory(pubkey, entry);
363381
return {
364-
cwd: workspace,
382+
...where(entry.config),
365383
tools: tools(workspace),
366-
...(model.trim() ? { model: model.trim() } : {}),
367384
systemPrompt: systemPrompt({
368385
scope,
369386
cwd: workspace,

0 commit comments

Comments
 (0)