Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

perf(agents): skip session-title reads of unchanged transcripts

enes6ae9ebb8377d
diff --git a/CLAUDE.md b/CLAUDE.md
index c1507d84f..793b54d8c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2354,6 +2354,11 @@ command-bearing opens; this does not add a human-confirm dialog or change mobile
over `pty.readSessionName`. `TerminalNode` polls it (~4 s) **only once this node's own sessionId
is known** and **while the title still auto-tracks** (`data.titleAuto`, default true on agent
nodes), and adopts it as the `title`. `term.onTitleChange` now feeds the `session` chip only.
+ **A poll of an unchanged transcript reads no bytes**: the local read is gated on the resolved
+ path's (size, mtime) (`titleCache`, bounded at 500, a failed tail read never cached), and the
+ remote one (`main/remote-title-reader.ts`) on the remote context tail's `offsetFor` for the SAME
+ path — that offset is the file size at the tail's last read, so a remote `/rename` lands within
+ the tail's idle backoff (≤ 10 s); an untracked session (offset unknown) always reads.
- **title → session (write):** the moment the user renames the node by hand (header rename box /
✦ AI-name / sidebar / command palette → all funnel through `applyManualTitle` or
`renameSession`), `titleAuto` flips to **false** (polling stops overwriting) and the chosen name
diff --git a/src/core/transcript-reader.test.ts b/src/core/transcript-reader.test.ts
index 3d8d2e588..dbf7c3841 100644
--- a/src/core/transcript-reader.test.ts
+++ b/src/core/transcript-reader.test.ts
@@ -1,5 +1,5 @@
import fs from 'fs'
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import {
parseTranscriptLines,
pickSessionName,
@@ -312,3 +312,46 @@ describe('readChatWindow — byte windows read from a real file', () => {
expect(await readChatWindow('/nonexistent/nt/x.jsonl', { before: null, maxBytes: 65536 })).toBeUndefined()
})
})
+
+// The title poll runs every 4–15 s per agent node, and each poll used to read + parse a 128 KB
+// tail. The name can only change when the transcript does, so an unchanged (size, mtime) must
+// answer from the cache without touching the file's bytes — while a /rename (the file grows)
+// must still be picked up on the next poll.
+describe('readSessionName — unchanged transcripts are not re-read', () => {
+ const sid = 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'
+ const custom = (t: string) => JSON.stringify({ type: 'custom-title', customTitle: t, sessionId: sid })
+ let home: string
+ let file: string
+
+ beforeEach(() => {
+ home = fs.mkdtempSync(path.join(os.tmpdir(), 'nt-title-cache-'))
+ vi.spyOn(os, 'homedir').mockReturnValue(home)
+ const dir = path.join(home, '.claude', 'projects', '-proj')
+ fs.mkdirSync(dir, { recursive: true })
+ file = path.join(dir, `${sid}.jsonl`)
+ fs.writeFileSync(file, custom('First') + '\n')
+ })
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ fs.rmSync(home, { recursive: true, force: true })
+ })
+
+ // readSmallTail reads a small file with readFile and a large one with open+read — spy on both,
+ // so "no tail read" holds whichever branch the fixture size lands on.
+ it('does not re-read an unchanged transcript', async () => {
+ const readFile = vi.spyOn(fs.promises, 'readFile')
+ const open = vi.spyOn(fs.promises, 'open')
+ expect(await readSessionName(sid)).toBe('First')
+ const reads = readFile.mock.calls.length + open.mock.calls.length
+ expect(reads).toBeGreaterThan(0)
+ expect(await readSessionName(sid)).toBe('First')
+ expect(readFile.mock.calls.length + open.mock.calls.length).toBe(reads)
+ })
+
+ it('re-reads after the transcript changes (e.g. /rename)', async () => {
+ expect(await readSessionName(sid)).toBe('First')
+ fs.appendFileSync(file, custom('Second') + '\n')
+ expect(await readSessionName(sid)).toBe('Second')
+ })
+})
diff --git a/src/core/transcript-reader.ts b/src/core/transcript-reader.ts
index b18d64ce8..338f75c97 100644
--- a/src/core/transcript-reader.ts
+++ b/src/core/transcript-reader.ts
@@ -472,6 +472,13 @@ export function setRemoteTranscriptReader(
remoteReader = fn
}
+// Title polls hit this every 4–15 s per agent node. The name can only change when the transcript
+// does, so (size, mtime) gates the 128 KB tail read. Keyed by the RESOLVED path (the account is
+// already folded into it). Bounded: oldest entries go first. A failed tail read is not cached — a
+// transient error must not pin a null title until the file next changes.
+const TITLE_CACHE_MAX = 500
+const titleCache = new Map<string, { size: number; mtimeMs: number; name: string | null }>()
+
export async function readSessionName(
sessionId: string,
accountId?: string
@@ -486,9 +493,17 @@ export async function readSessionName(
// Stale cache entries are healed inside resolveTranscriptPath (access-checked per hit).
const p = await resolveTranscriptPath(sessionId, accountId)
if (!p) return null
+ const st = await fs.promises.stat(p).catch(() => null)
+ const hit = st ? titleCache.get(p) : undefined
+ if (st && hit && hit.size === st.size && hit.mtimeMs === st.mtimeMs) return hit.name
const tail = await readSmallTail(p, TITLE_TAIL_BYTES)
- if (!tail) return null
- return pickSessionName(tail)
+ const name = tail ? pickSessionName(tail) : null
+ if (st && tail !== undefined) {
+ titleCache.delete(p)
+ titleCache.set(p, { size: st.size, mtimeMs: st.mtimeMs, name })
+ if (titleCache.size > TITLE_CACHE_MAX) titleCache.delete(titleCache.keys().next().value!)
+ }
+ return name
}
// Durable resolver by working directory: Claude stores a project's transcripts under
diff --git a/src/main/index.ts b/src/main/index.ts
index d4ebed12f..7b45cefbd 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -235,6 +235,7 @@ import {
import { createRemoteContextTail } from './remote-context-tail'
import { createRemoteSubagentTail } from './remote-subagent-tail'
import { RemoteFile, type RemoteFileRef } from './remote-ssh/remote-file'
+import { createRemoteTitleReader } from './remote-title-reader'
import {
checkMasterArgs,
childArgs,
@@ -2465,12 +2466,19 @@ app.whenReady().then(async () => {
// project's agent runs on the remote host, so its transcript is NOT under the local
// `~/.claude/projects` — without this, `/rename` never reached the node title on remote nodes
// (and the poll re-scanned the local root every 4s for nothing). Returning null for an unknown
- // sessionId keeps every local node on the local reader.
- setRemoteTranscriptReader(async (sessionId) => {
- const ref = remoteTranscriptBySession.get(sessionId)
- if (!ref) return null
- return { text: await remoteFile.readTail(ref, TITLE_TAIL_BYTES) }
- })
+ // sessionId keeps every local node on the local reader. The ssh tail read is skipped while the
+ // remote context tail's offset for the SAME path has not moved (the file has not grown); a
+ // tail tracking a different path answers "unknown", which always reads.
+ setRemoteTranscriptReader(
+ createRemoteTitleReader({
+ refFor: (sessionId) => remoteTranscriptBySession.get(sessionId),
+ offsetFor: (sessionId) =>
+ remoteContextTail.pathFor(sessionId) === remoteTranscriptBySession.get(sessionId)?.path
+ ? remoteContextTail.offsetFor(sessionId)
+ : null,
+ readTail: (ref) => remoteFile.readTail(ref, TITLE_TAIL_BYTES)
+ })
+ )
// toolUseIds whose remote subagent file resolution was cancelled (PostToolUse / node close
// arrived before the file appeared) — checked by the async resolver to avoid a late track.
// Bounded by `remoteSubagentResolving`: a cancel flag is only added (and only matters) while a
diff --git a/src/main/remote-title-reader.test.ts b/src/main/remote-title-reader.test.ts
new file mode 100644
index 000000000..6b80f5d82
--- /dev/null
+++ b/src/main/remote-title-reader.test.ts
@@ -0,0 +1,31 @@
+import { describe, it, expect, vi } from 'vitest'
+import { createRemoteTitleReader } from './remote-title-reader'
+
+const ref = { path: '/h/.claude/projects/x/s1.jsonl', controlPath: '/cp', conn: {} } as never
+
+describe('createRemoteTitleReader', () => {
+ it('returns null for a session that is not remote', async () => {
+ const r = createRemoteTitleReader({ refFor: () => undefined, offsetFor: () => null, readTail: vi.fn() })
+ expect(await r('s1')).toBeNull()
+ })
+
+ it('reuses the last tail while the tail-tracked offset has not moved', async () => {
+ let offset: number | null = 100
+ const readTail = vi.fn().mockResolvedValue('tail-A')
+ const r = createRemoteTitleReader({ refFor: () => ref, offsetFor: () => offset, readTail })
+ expect(await r('s1')).toEqual({ text: 'tail-A' })
+ expect(await r('s1')).toEqual({ text: 'tail-A' })
+ expect(readTail).toHaveBeenCalledTimes(1)
+ offset = 200
+ readTail.mockResolvedValue('tail-B')
+ expect(await r('s1')).toEqual({ text: 'tail-B' })
+ expect(readTail).toHaveBeenCalledTimes(2)
+ })
+
+ it('always reads when the offset is unknown (tail not tracking it)', async () => {
+ const readTail = vi.fn().mockResolvedValue('t')
+ const r = createRemoteTitleReader({ refFor: () => ref, offsetFor: () => null, readTail })
+ await r('s1'); await r('s1')
+ expect(readTail).toHaveBeenCalledTimes(2)
+ })
+})
diff --git a/src/main/remote-title-reader.ts b/src/main/remote-title-reader.ts
new file mode 100644
index 000000000..43ae27ceb
--- /dev/null
+++ b/src/main/remote-title-reader.ts
@@ -0,0 +1,28 @@
+import type { RemoteFileRef } from './remote-ssh/remote-file'
+
+/** Remote session-title reader: a 128 KB tail read over ssh per poll, per remote agent node,
+ * skipped while the remote context tail reports the file has not grown (its read offset IS the
+ * file size at its last read). Unknown offset ⇒ always read. Bounded by live remote sessions:
+ * an entry goes when its session stops being remote or stops being tracked by the tail. */
+export function createRemoteTitleReader(deps: {
+ refFor(sessionId: string): RemoteFileRef | undefined
+ offsetFor(sessionId: string): number | null
+ readTail(ref: RemoteFileRef): Promise<string>
+}): (sessionId: string) => Promise<{ text: string } | null> {
+ const cache = new Map<string, { offset: number; path: string; text: string }>()
+ return async (sessionId) => {
+ const ref = deps.refFor(sessionId)
+ if (!ref) {
+ // Not a remote session — null is the signal for core to use the local reader.
+ cache.delete(sessionId)
+ return null
+ }
+ const offset = deps.offsetFor(sessionId)
+ const hit = cache.get(sessionId)
+ if (offset !== null && hit && hit.offset === offset && hit.path === ref.path) return { text: hit.text }
+ const text = await deps.readTail(ref)
+ if (offset !== null) cache.set(sessionId, { offset, path: ref.path, text })
+ else cache.delete(sessionId)
+ return { text }
+ }
+}