[Feature request] Shared background renderer for all Claude Code sessions

[axisrow]

Add an opt-in shared-process mode: all Claude Code sessions belonging to one OS user send status-line requests to one long-lived ccstatusline process. Preserve the existing widgets, formatting, per-session data, CLI and TUI.

The intended outcome is to stop loading Node and the rendering module graph on every repaint, share reusable work at the correct scope, and keep a slow session from delaying every other status line. This is a feature proposal; the daemon has not been implemented.

The motivation comes from a local macOS diagnosis with 36 open Claude Code sessions. Snapshots showed 18–25 simultaneous ccstatusline processes, plus Git/custom-command/Keychain subprocesses. A separate local 30-second negative-cache mitigation for unsuccessful Keychain discovery reduced CPU time in repeated test renders from approximately 1.10 s to 0.50 s, including child commands. Those measurements were taken on a heavily loaded machine: they are not a daemon benchmark, not proof of a fixed 55% improvement for all workloads, and not evidence that ccstatusline caused all system load. They show why sharing work is worth investigating. Related fork work: #6 and #7; runtime compatibility is separately tracked in #4.

Claude Code invokes the configured command again on status-line updates, supplies JSON on stdin, and uses stdout as the displayed text. It can cancel an in-flight invocation when a newer update arrives. We must keep that contract; a daemon cannot push directly into Claude's terminal. See the official status-line protocol.

The proposed flow is:

flowchart LR
    A["Claude Code sessions"] -->|"stdin JSON"| B["Short-lived shell + curl clients"]
    B -->|"HTTP over private Unix socket"| C
    subgraph D["One shared Node process"]
        C["Validate request and resolve context"] --> E["Async providers and scoped caches"]
        E --> F["Existing status-line formatter"]
    end
    F -->|"ANSI text response"| B
    B -->|"stdout"| A

Loading

One shared process means one persistent renderer per OS user and compatible installation/build, not one per session, worktree or account. Lightweight clients still start for each invocation. Git and configured shell commands can still create bounded subprocesses; reducing those remains part of the measurement.

1. Keep the client genuinely lightweight. Start with the installed shell and curl, without a Node/Bun/Python/jq bootstrap on the healthy repaint path. curl already supports Unix-domain sockets; the server can use Node's built-in HTTP API, without a web framework.

   The client forwards the original stdin bytes, adds the invocation context, and prints only the successful response body. Diagnostics go to stderr. Disable user curl configuration, proxy routing and redirects for this IPC call; use explicit connection/total deadlines and HTTP error handling. A partially received/error response must not become a malformed status line. Include all client helper processes in the performance accounting.

2. Define a small, versioned IPC contract. Use POST /v1/render with the original StatusJSON as the JSON body, and GET /v1/health for readiness/build compatibility. A successful render returns complete UTF-8 ANSI text with the same line breaks, reset codes, non-breaking spaces and OSC links as the existing command.

   Transport metadata must include protocol/build identity, request identity/deadline, the caller's actual working directory, ccstatusline config selection and caller environment. A request context is conceptually:

type InvocationContext = {
    protocolVersion: 1;
    clientBuild: string;
    requestId: string;
    deadlineMs: number;
    callerCwd: string;
    configPath?: string;
    env: Record<string, string>;
};

Keep context encoding independent of the status JSON. The first client prototype should use a bounded, encoded metadata header block; a base64-encoded NUL-delimited environment snapshot is one practical candidate that avoids writing a JSON serializer in shell. Supply sensitive header material through an inherited pipe/file descriptor, not command-line arguments, URLs or temporary credential files. Test the actual macOS/Linux tooling and header-size limits before freezing this encoding.

Preserve distinctions between absent and empty environment values, including CLAUDE_CONFIG_DIR and CLAUDE_SECURESTORAGE_CONFIG_DIR. Capture terminal dimensions and overrides for each invocation, including COLUMNS and CCSTATUSLINE_WIDTH; the daemon's own terminal ancestry is irrelevant. Paths and environment values must survive spaces, Unicode, quotes and newlines.

Arbitrary custom commands currently inherit the caller's environment. Full fidelity is the default requirement: pass that snapshot to the relevant child process, keep it transient, and never log it. An allowlist-only mode would need an explicit documented compatibility choice. If the shell/curl prototype cannot preserve these semantics cheaply and safely, benchmark a tiny native transport client before adding another runtime dependency.

3. Separate request context from process globals. Extract the orchestration in renderMultipleLines() into a function that accepts validated input and explicit invocation/settings context and returns text. Keep stdout/process-exit behavior in the command entry point.

   config.ts currently has mutable module-level settingsPath and lastLoadError; terminal.ts memoizes width for the process; usage-fetch.ts has a single in-memory usage result; ccstatusline.ts changes global Chalk/color state. custom-command.ts reads process.cwd() and inherits process.env. These assumptions are valid for short-lived isolated renders but unsafe when unrelated requests overlap.

   Resolve config, config errors, profile/account identity, cwd, terminal width and subprocess environment per request. Never switch process.chdir() or mutate process.env to impersonate another caller. Make styling request-local, or serialize only the small final synchronous formatting section with the appropriate style state; do not keep mutable style state across asynchronous waits. Preserve existing config validation, atomic migrations, warning badges and malformed-file recovery.

4. Gather data asynchronously, then render using the existing widgets. Reuse the widget registry, formatter, transcript parser and existing provider logic. Prefetch the data required by configured widgets into RenderContext so synchronous widget formatting can consume resolved results.

   Git, Keychain and custom-command work must use asynchronous subprocess execution in shared mode. Node documents that the synchronous child-process APIs block its event loop; putting the current render path behind an HTTP handler would otherwise make one slow command stall every session.

   In particular, custom-command capture currently creates an extra Node process with spawnSync(process.execPath, ['-e', ...]) and its helper writes to stdout/exits. Adapt its capture logic to an asynchronous result in the daemon, retaining output limits, timeouts, EPIPE handling and descendant/process-group cleanup. Do not call that helper unchanged inside the server, or preserve a hidden Node-per-widget hot path.

   The Git review cache also has a detached refresh path that re-enters the Node executable. In shared mode, route those refreshes through the same asynchronous scheduler instead of spawning another ccstatusline runtime. Audit the other providers for self-spawns and caller-global state as part of the one-process invariant; keep the legacy execution path available for one-shot mode.

5. Share caches at the scope of their inputs. Reuse existing TTL settings and on-disk formats where compatible. Add bounded in-memory caches and reuse an in-flight refresh for the same key, so a burst of 36 callers does not launch 36 identical lookups. Account/profile separation must happen before any memory-cache fast return.

Data	Scope and invalidation
Settings	Absolute config path plus file revision; revalidate after change and keep errors local to that config.
Usage/credentials	Auth profile, resolved account/credential generation and effective provider configuration. Respect TTL/backoff and logout/account changes. Missing credentials must never select another profile's cached usage.
Service health	Endpoint/query requirements and relevant network configuration; reuse the existing freshness rules.
Git	Actual worktree/cwd, command, relevant environment and existing repository metadata/TTL rules. Linked worktrees must not share branch/index state accidentally.
Transcript analysis	Canonical file identity, size/mtime/replacement indicators and requested analysis options. Account for referenced subagent changes when included.
Custom commands	Existing command/session/width/timeout/TTL semantics, extended with explicit cwd and effective environment identity. TTL zero continues to execute for each eligible request.
Last complete rendered line	Exact display context: session, config revision, cwd, auth profile, terminal dimensions and formatting inputs; short bounded lifetime.

Avoid unconditional complete transcript scans for unchanged files. Start with validated whole-analysis reuse using the existing parser; any dependency that cannot be checked reliably remains uncached. File truncation, replacement, compaction, partial trailing records and subagent updates need invalidation tests. Incremental tail parsing is a follow-up only if profiling still shows a meaningful bottleneck.

Bound cache memory, active jobs and idle-session retention. Do not retain full environments, tokens or transcript contents in diagnostics or an unbounded map. No periodic whole-machine scan is needed: refresh on requests and expire idle entries.

6. Handle overlapping requests and cancellation deliberately. Use bounded queues and provider concurrency, with at most one active and one newest pending render per exact display context. Resolve superseded requests explicitly; do not leave their connections waiting indefinitely. Different accounts/configs/terminal widths are distinct contexts, even when a conversation ID is reused.

   When Claude cancels the client, detach that consumer. Cancel provider work when it has no remaining consumers; cancellation of one request must not kill a shared refresh needed by others. Slow network calls, custom commands and large transcript reads must not prevent cached responses for unrelated sessions. Chunk/yield long scans and limit concurrent expensive scans before introducing a worker pool.

7. Make lifecycle and failure behavior predictable. Proposed user commands are ccstatusline daemon start|stop|status, plus an explicit installation choice for shared mode. Installation writes a client-wrapper command to Claude settings; returning to one-shot mode restores the previous command.

   Coordinate cold startup using the platform's per-user service manager where available, or an atomic per-user startup lock with a readiness handshake. Concurrent first requests must converge on one server. A health response reports protocol and build identity; old clients must not silently talk to an incompatible server after an upgrade. Handle stale sockets, crashed owners, PID reuse and interrupted upgrades without unlinking a live server's endpoint or killing an unrelated process.

   Disconnect/restart loops need bounded retry and backoff. On daemon failure, prefer a correctly scoped recent completed render or a short unavailable indicator while one restart attempt proceeds. Do not silently start a full legacy Node render for every failed client: that would recreate the original process storm. Keep explicit one-shot mode available for compatibility and debugging. Do not automatically replay an ambiguous failed render containing a potentially side-effecting custom command.

8. Keep IPC private and bounded. Store the filesystem socket under a short per-user runtime path with a private directory (0700) and socket permissions restricted to the owner (0600). Verify ownership/type and avoid following attacker-controlled symlinks during stale-file cleanup. Account for Unix socket path-length limits.

   Use no TCP listener in the initial implementation. Validate JSON/context, request/header size, cwd/config paths, queue limits and deadlines at the boundary. Same-user clients retain only the capabilities of the existing local command; another OS user must not be able to reach the renderer or induce configured shell commands. Health/status diagnostics should show aggregate counters, versions and timings, never credentials, full environment snapshots, prompts or transcript content.

The main implementation touchpoints are src/ccstatusline.ts, RenderContext, config, terminal, usage fetching, Git, Git review refresh, custom-command execution, capture and transcript analysis. Keep added IPC/client/lifecycle code separate from the reusable rendering pipeline, without building a general daemon framework.

Deliver this in reviewable steps:

1. Extract request-scoped orchestration and prove output parity while retaining the current one-shot entry point.
2. Add the private IPC server/client and coordinated startup; establish the one-process invariant before adding caching.
3. Move blocking providers off the event loop, adapt custom-command capture, and add scoped caches, refresh deduplication and cancellation.
4. Add opt-in installation/status/recovery and benchmarks. Start on macOS/Linux; keep the existing path on Windows until an equivalent private transport/client is tested. Preserve Bun/Node behavior on genuinely supported runtimes and resolve/document Node 14+ distribution requirement is already broken on main (pre-existing blocker) #4 rather than assuming an untested Node 14 claim.
5. Evaluate incremental transcript parsing or a worker pool only if the resulting profile warrants them.

Acceptance criteria:

• With 36 concurrent sessions, exactly one compatible shared renderer remains after startup; a healthy repaint launches no Node/Bun process, including through custom-command capture.
• Fixed input, fixed provider results and fixed time produce byte-equivalent output in one-shot/shared modes, including multiline layouts, colors, Powerline, custom commands and warning badges.
• Simultaneous different configs, accounts, worktrees, environments and terminal widths cannot exchange data or formatting state; account switches/logout invalidate the relevant cache.
• One slow/hung command or usage fetch does not stall cached/simple requests from another session; queues, cancellation and timeout behavior remain bounded.
• Cold-start races, crashes, stale sockets, incompatible versions and upgrades recover without duplicate persistent servers or restart/fallback storms.
• Truncation/replacement/compaction/partial JSONL records and subagent changes produce correct transcript results.
• Cache/session memory stays bounded during a sustained multi-session run and is reclaimed after sessions become idle.
• IPC rejects other users and invalid/oversized requests; secrets are absent from logs, URLs, argv and persisted transport metadata.
• Benchmarks report end-to-end cost for the daemon and all clients/children, with unchanged output and equivalent data freshness.
• Shared mode remains opt-in, with a tested return to the existing one-shot command and no TUI/CLI regression.

Extend scripts/benchmark-render.py rather than introducing a benchmark framework. Compare one-shot and shared mode using 1/10/36/50 sessions, cold and warm starts, idle timer refreshes, active updates, several repositories, different configs/accounts, growing transcripts and slow-command/recovery cases. Record CPU seconds per completed render and per minute, aggregate RSS/peak RSS, p50/p95/p99 latency, subprocess counts, provider/cache hits and output equality. Count persistent daemon CPU explicitly; child-process-only accounting misses it.

A suggested performance gate is at least 50% lower aggregate CPU in the warmed 36-session representative workload, with lower aggregate memory and no p95 latency regression for equivalent work/freshness. This is a target to validate, not a claimed result. Keep the feature opt-in until repeatable measurements support enabling it more broadly.

[axisrow]

Decomposed into native sub-issues (estimates from fork PR history: feat PRs run 200–650 LOC, large justified ones 1100–2900; review cycle adds 44–75% over code time):

#	Sub-issue	LOC	Size	code, min	review, min	total, min	Priority
#15	Request-scoped render orchestration + output parity	400–700	L	50–130	30–45	80–175	high
#16	Private IPC transport: curl client + Node HTTP server, v1 contract	600–900	XL	100–180	90–120	190–300	high
#17	Coordinated lifecycle: cold-start race, stale socket, retries	300–500	L	50–130	60–90	110–220	medium
#18	Async providers, scoped caches, dedup, cancellation	700–1000	XL	100–180	90–120	190–300	medium
#19	Opt-in install, status UX, benchmarks, acceptance gates	400–700	L	50–130	60–90	110–220	medium
#20	Conditional: incremental tail parsing / worker pool	0–300	S/M	10–50	10–25	20–75	low

Total: ~700–1290 min (~12–21 h) of agent work — sum of «итого», not «код» (review is a first-class cost, not overhead).

Recommended order

1. Daemon: extract request-scoped render orchestration with output parity #15 — foundation; nothing else starts without it.
2. Daemon: private IPC transport — shell/curl client + Node HTTP server (v1 contract) #16 — IPC transport (needs request-scoped renders).
3. Daemon: coordinated lifecycle — cold-start race, stale socket, upgrades, bounded retries #17 ∥ Daemon: async providers, scoped caches, refresh dedup, cancellation #18 — lifecycle and providers/caches are independent once Daemon: private IPC transport — shell/curl client + Node HTTP server (v1 contract) #16 lands; can run as parallel workers.
4. Daemon: opt-in installation, status/recovery UX, benchmarks and acceptance gates #19 — installation + benchmarks + acceptance run against the epic checklist.
5. Daemon follow-up (conditional): incremental transcript tail parsing / provider worker pool #20 — only if Daemon: opt-in installation, status/recovery UX, benchmarks and acceptance gates #19's profile still shows transcript/contention bottlenecks; do not start without a profile attached.

Each sub-issue is scoped to a PR of ≤1000 LOC, so no overflow follow-ups were needed. The split follows the epic's own delivery steps: the one-shot path stays intact through #15, the one-process invariant is established before caching (#16 → #18), and everything remains opt-in until #19's numbers are in.

[axisrow]

Epic complete — shared-mode daemon shipped in 5 merged slices

All delivery steps are merged to main; every child issue (#15, #16, #17, #18, #19, #20) is closed.

Step	Issue	PR	What shipped
1	#15	#25	Request-scoped render orchestration (src/render.ts) with render-parity fixtures; one-shot entry point and byte-identical output retained
2	#16	#44	Private IPC transport: Node http server on a per-user Unix socket (0700 runtime dir, 0600 socket, bearer token via daemon.env discovery), POSIX sh+curl client with no jq/Node bootstrap, POST /v1/render + GET /v1/health (v1 contract), base64 NUL-delimited env snapshot with absent-vs-empty preserved
2	#17	#47	Coordinated lifecycle: cold-start lock + readiness handshake, stale-socket/PID-reuse recovery without touching live servers, upgrade restart, bounded retries
3	#18	#49	Async provider twins (git, keychain, custom-command capture off the event loop), caches scoped by config/account/cwd/env identity, RefreshGroup single-flight refresh dedup + cancellation, prefetch
4	#19	#50	Opt-in daemon install/stop/status/uninstall with tested verbatim return to one-shot, status/recovery UX, benchmark extension + acceptance run
5	#20	—	Closed not-needed: the acceptance profile did not warrant incremental transcript tail parsing or a provider worker pool (numbers: #20 (comment))

Acceptance measurement — docs/daemon-19-bench.md, docs/daemon-19-results.json, docs/daemon-19-verification.md (Apple M5, node dist, fresh HOME per scenario, shared dirty git repo, loadavg gate 14):

• CPU gate (epic target ≥50% aggregate-CPU reduction, daemon and every client/child included via getrusage(RUSAGE_CHILDREN)), warmed 36-session workload: 180.0 → 34.7 ms CPU/render = 80.7% reduction. Warm shared steady state 16.9–46.8 ms CPU/render across 1/10/36/50 sessions, small and large (13 MB) transcripts; cold runs (daemon boot + cold caches inside the measured window) reduce 77–86%.
• Output equality: exactly 1 distinct hash per passing scenario; every one-shot-vs-shared comparison row output_hashes_equal=true; all 50 sessions re-rendered byte-identically after a SIGKILL restart.
• Recovery: dead-daemon wave → 50/50 clients fail rc≠0 with empty stdout (never a partial status line), daemon restart-to-ready 135.5 ms, 0 output mismatches.
• Memory: aggregate RSS at 50 warm sessions ~2.8–3.5 GB one-shot vs 0.35–0.56 GB shared; the daemon process stays ~0.4–0.6 GB while one-shot multiplies per session (up to 5.7 GB in the slow scenario).
• Opt-in + tested return: enable/disable round-trip, verbatim restore of the previous statusLine, idempotent enable, refusals on corrupt config and Windows.

Honest limitations — measured and kept visible, not tuned away:

• s50-shared-warm-small-slow fails as recorded (twice, reproducibly): 50 synchronous sessions × a 400 ms-sleep custom command with cache TTL 0 overrun the designed backpressure boundary (MAX_IN_FLIGHT_RENDERS = 4 + the client's ~8 s bounded retry ladder → some 503 busy). The equivalent one-shot wave keeps all sessions rendering but costs 250 ms CPU/render and up to 5.7 GB RSS.
• Latency percentiles were taken under ambient load (loadavg 4–15, sibling sessions); they are upper bounds, and shared p99 at 50 sessions grows with the busy-retry ladder by design.
• bun ≥1.3.13 does not deliver client-disconnect to its http server (probe-verified during PR feat(daemon): async providers, scoped caches, refresh dedup, cancellation (#18) #49) — cancellation wiring is Node-first, documented on the PR.
• Shared mode remains opt-in; Windows keeps the one-shot path until an equivalent private transport/client is tested (per this epic). General runtime-compat tracking stays in Node 14+ distribution requirement is already broken on main (pre-existing blocker) #4.

State at the acceptance run: bun test 2732 passed / 0 failed (single full run), bun run lint clean.

[axisrow]

Epic delivered: #15->PR #25, #16->PR #44, #17->PR #47, #18->PR #49, #19->PR #50, #20 closed not-needed per the benchmark data. Gate measured at 80.7% aggregate-CPU reduction (target >=50%); full summary and limitations above.