claude-code-infinite 1.0.20 → 1.0.22

package/README.md

@@ -17,10 +17,27 @@ follows it down to the original messages.
 * **Search across every session.** Claude can find what was decided, tried or ruled out in any of
   your past sessions, by exact words or by meaning, filtered by project and date
 * **Browse each session's MemTree** in your browser, from the link `ccc` prints in the terminal
-* **Replaces `/compact` without losing the thread.** In a blind-graded benchmark, MemTree matched
-  full-context Claude Code and beat Claude Code's built-in `/compact` by 20 points
-  ([details](#long-session-benchmark))
+* **Never loses anything vs Claude Code.** Sessions are sent word for word until near the context
+  limit; past it, MemTree matched full context (69 vs 69) and beat `/compact` by 20 ([benchmark](#long-session-benchmark))
 * **Unlimited-length sessions**, with relevant past information recalled automatically
+* **A local proxy, so no slowdown.** Requests go straight from your machine to Anthropic and
+  MemTree indexes in the background; only the occasional compression step, when a session
+  outgrows the context budget, waits on MemTree
+
+The magic starts past the context limit. Keep one session going for days and it learns how you
+work: your priorities, the nuances of your projects, your company and your environment. Where
+`/compact` would wipe that detail, MemTree keeps it, so the thread becomes an expert in you. Let it
+orchestrate dozens of subagents on your behalf.
+
+> [!IMPORTANT]
+> Requires a Claude Pro or Max subscription.
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/crizCraig/claude-code-infinite/main/docs/images/benchmark-dark.svg">
+    <img width="600" alt="Long-session benchmark, judged score out of 100: Claude Code Infinite 69, full context 69, /compact 49" src="https://raw.githubusercontent.com/crizCraig/claude-code-infinite/main/docs/images/benchmark-light.svg">
+  </picture>
+</p>
 
 ## Search across sessions
 
@@ -67,14 +84,11 @@ tokens; `/compact`'s exclude the one-time `/compact` step. This is one task fami
 
 * [node.js 20.3 or newer](https://nodejs.org/en/download/)
 * [Claude Code (the terminal version)](https://code.claude.com/docs/en/quickstart)
-* **Claude Subscription** - optional but highly recommended as this offers up to 1000x cost savings vs Anthropic's API pricing
+* **A Claude Pro or Max subscription**
 
-## Setup
+<sub>Also works with an Anthropic API key, but that's far costlier than Pro or Max.</sub>
 
-> [!TIP]
-> No Claude subscription? Use an Anthropic API key exactly as with vanilla Claude Code
-> (`ANTHROPIC_API_KEY` or a Console login). `ccc` forwards it unchanged to api.anthropic.com, and
-> you pay Anthropic per token.
+## Setup
 
 1. Install (Node ≥ 20.3; no git needed)
   ```bash
@@ -96,6 +110,32 @@ The tool supports multiple environments (this selects the MemTree compression AP
 
 Each environment maintains its own separate API key.
 
+## Commands
+
+Type these inside a `ccc` session (the `ccc:` prefix is optional). `ccc` answers them
+locally, so they cost no model turn.
+
+| Command | What it does |
+| --- | --- |
+| `/ccc:memtree` | Lists the MemTree commands and links your usage dashboard. |
+| `/ccc:memtree-view` | Shows the link to this session's MemTree page. |
+| `/ccc:memtree-compact [tokens]` | Compacts the session on your next message (to half the budget, or a target such as `400k`) and keeps the compressed history. |
+| `/ccc:memtree-compact off` | Goes back to sending the conversation whole. |
+
+Environment variables, set when launching `ccc`:
+
+| Variable | What it does |
+| --- | --- |
+| `CCC_COMPACT_TARGET=500k` | Compaction target for every session (useful for headless `-p` runs); `off` starts every session with compaction off. |
+| `CCC_MEMTREE_LINK` | Where the MemTree link appears: `turn` (default, end of a turn with a new page), `message` (under every reply), `stop` (end of every turn), `success` (only after an optimized turn), or `off`. |
+| `CCC_AUTO_COMPACT=1` | Restores Claude Code's own auto-compaction setting ([details](#claude-code-auto-compaction)). |
+| `CCC_NO_UPDATE_CHECK=1` | Turns off the update check, and with it automatic updates ([details](#upgrading)). |
+| `CCC_DISABLE_AUTOUPDATE=1` | Keeps the update notice but never installs ([details](#automatic-updates)). |
+| `CCC_NO_DIAGNOSTICS=1` | Turns off diagnostics ([details](#diagnostics)). So do `DO_NOT_TRACK=1`, Claude Code's `DISABLE_TELEMETRY=1` or `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`, and `"diagnostics": false` in `~/.claude-code-infinite/config.json`. |
+
+Links are clickable in terminals that support OSC 8 hyperlinks (iTerm2, Ghostty, WezTerm,
+kitty, VS Code, JetBrains, Windows Terminal); elsewhere you get the plain URL.
+
 ## Claude Code auto-compaction
 
 `ccc` disables Claude Code's automatic conversation compaction for the Claude process it launches. MemTree manages the context sent to the model, so letting Claude Code independently summarize the full local transcript can compact a conversation MemTree already reduced. Manual `/compact` remains available.
@@ -105,6 +145,13 @@ above a fixed 100k-token threshold, even when the active model has a 1M window
 and auto-compaction is disabled. `ccc` suppresses that resume-time
 recommendation as well; it does not disable the manual `/compact` command.
 
+With auto-compaction off, Claude Code still refuses a request itself, without
+sending it, once its own estimate reaches the window minus 23k (977k on a 1M
+window). MemTree compresses at 900k, so a single large tool round could reach that
+refusal before `ccc` ever saw the request. `ccc` sets
+`CLAUDE_CODE_BLOCKING_LIMIT_OVERRIDE` (unless you exported your own) so such a
+request reaches the proxy, which compresses it mid-turn.
+
 A session whose last response reached the verified local refusal threshold
 (for example one sent whole while MemTree was unavailable) would otherwise be
 refused locally with "Context limit reached" on every prompt after a resume.
@@ -141,24 +188,27 @@ Claude Code ──▶ localhost proxy (ccc)
 - Anthropic requests go directly from the local proxy to api.anthropic.com using the authentication Claude Code supplied. PolyChat never sees that credential or Anthropic traffic.
 - If MemTree is unreachable, slow, or your MemTree plan needs payment, `ccc` degrades to a transparent passthrough so your session is never interrupted.
 
-### Inline notices
-
-In interactive sessions, `ccc` reports these MemTree states as display-only lines in Claude Code:
+### Diagnostics
 
-- `✓ MemTree · conversation optimized · ~813k → 408k tokens`, with the session's newest completed MemTree page on its own line below it and a blank line before the answer, when a compressed turn reflects new indexing (MemTree's index covers more of the conversation than before) or a newly finished MemTree page. The before-count is `ccc`'s size estimate for the request that would otherwise have been sent (MemTree's `usage.raw_prompt_tokens` when `ccc` has none); the after-count is Anthropic's reported compressed input, estimated from bytes until usage arrives. Counts under a million are whole thousands, larger ones one decimal (`1.3m`). Without both counts, or when the result is not smaller, the line reads just `✓ MemTree · conversation optimized`. The line is green when terminal color is available, and plain when `NO_COLOR` or a monochrome terminal is configured. `ccc` uses the standard ANSI green foreground sequence and Node's capability detection, so the same path works in ANSI terminals on macOS/Linux and supported Windows consoles.
-- `⚠ MemTree degraded — this turn ran uncompressed` when a blocking compression call fails or times out.
-- `⚠ MemTree is off — payment required…` once when compression and indexing are disabled for payment.
-- `• MemTree` with the page on its own line below it, once at the end of a user turn, when the turn used a MemTree index whose link has not been shown yet (the first one of the session, then each newly finished index), unless the turn's success line already showed it. The line comes from the `Stop` hook, so it lands after the turn's last message. When MemTree passed the conversation through whole because it already fits the model's budget, the label line reads `• MemTree · /memtree-compact to compact session`. The URL always gets a line to itself, so a long link does not wrap the label or note. The displayed link follows the server's newest completed tree for this session, preserving its pinned namespace and own/served selection. If that lookup is unavailable, it falls back to the compression page; that page can show a completed prefix while its own tree builds. Open it in a browser, read it as JSON with `ccc fetch <url>`, or, from an agent inside the session, `GET $ANTHROPIC_BASE_URL/memtree/<short id>.json` on the loopback proxy without handling the key. Every MemTree call carries Claude Code's session id, so `GET $ANTHROPIC_BASE_URL/memtree/sessions/<session id>.json` lists every page from one session, newest first (the session id is the `--resume` id and the name of the transcript under `~/.claude/projects/`). `/memtree` lists the MemTree commands. Type `/memtree-view` at any time to print the session's latest link. Both also end with a `• Usage` link to your usage dashboard on polychat (`/usage` on the same host as MemTree: `https://app.polychat.co/usage` in production, the staging or local host otherwise); it opens only with your browser signed in to polychat as the same account. `/memtree-compact` is MemTree's replacement for Claude Code's `/compact`: your next message is sent compressed to half the budget (or `/memtree-compact 400k` for another target), and from then on the session follows the compaction rules under [How it works](#how-it-works) with that target. `/memtree-compact off` goes back to sending the conversation whole. `CCC_COMPACT_TARGET=500k` sets the target of every compaction for every session from launch, for benchmarks and headless (`-p`) runs, where the slash command is unavailable; it does not compact by itself, the budget still decides when, and `/memtree-compact off` still turns compaction off for one session. `CCC_COMPACT_TARGET=off` starts every session in the `/memtree-compact off` state instead (`/memtree-compact [N]` still turns it back on). `ccc` answers these commands locally, so they cost no model turn and nothing is added to the conversation; the compaction setting lasts for the life of the `ccc` process. When a session starts and already has a page, which in practice means a resumed one (`ccc --resume`, or `/resume` inside a running session), its latest link is shown right away: `ccc` remembers the newest page per session in `~/.claude-code-infinite/memtree-links.json` (most recent 200 sessions) and a `SessionStart` hook prints it. `CCC_MEMTREE_LINK` changes where the link appears: `turn` (default), `message` (under every finished assistant message, green when the index is new, dim otherwise), `stop` (every turn, on `Stop`), `success` (only on the line below `✓ MemTree · conversation optimized`), or `off`.
+`ccc` sends a few diagnostics to MemTree so we can see why a session fails to start or stalls:
 
-The newest-tree lookup runs in the background with a 60-second cache, at most eight outstanding fetches, and one 10-second deadline across at most 32 finder pages. `/memtree-view` and resume hooks wait at most 2.5 seconds. Servers with the finder session-ID search (polychat `0202eaa` and later, including reviewed `c67cadb`) use `/v1/memtree/sessions?q=<id>`, following cursors and accepting only the exact session ID. A missing endpoint falls back to the compression page and is not retried for 30 minutes. The older exact route `/usage/memtree/sessions/<id>.json` accepts the bearer key, but excludes index-only calls and does not report completed trees, so it cannot supply this link. No verified server version provides a suitable exact newest-completed-tree lookup yet.
+- versions (ccc, Claude Code, Node), how ccc was installed (npm, npx, linked), OS and CPU
+  architecture, terminal type and locale;
+- lifecycle events (first run, sign-in prompt shown, key accepted or rejected, session start,
+  the MemTree-paused notice shown, update hint or background update result);
+- errors as codes, status numbers, sizes and timings (an Anthropic 401, a MemTree 402, a
+  compression timeout).
 
-`/memtree-view` (and the usage link of `/memtree`) emits OSC 8 hyperlinks only when the ccc proxy has a TTY and detects iTerm2 3.1+ (`TERM_PROGRAM=iTerm.app` plus its version), JetBrains (`TERMINAL_EMULATOR=JetBrains-JediTerm`), Ghostty, WezTerm, VS Code, kitty, or Windows Terminal (`WT_SESSION`). Detection happens in the proxy, before hook output is relayed through pipes. `NO_COLOR`, dumb/unknown terminals, tmux/screen, and non-TTY output get a plain URL. Apple Terminal also gets the full visible URL for its normal URL handling. The success and Stop notices retain their visible URLs, and a late lookup cannot repeat the same page already linked by that turn's success notice.
+Never sent: your prompts or any conversation content, file paths, project or repository names,
+hostnames, usernames, environment values, keys or tokens, or error message text. Each event is
+checked against a fixed allowlist on your machine before it is queued, and again by the server.
+They are tied to your MemTree key when you have one, otherwise to a random install id in
+`~/.claude-code-infinite/install_id`. Sending is batched in the background and never slows a
+request; a failed send is dropped.
 
-**The end of a session.** MemTree indexes once about 10k new tokens build up, and each index call carries a request's messages, so a session's last turns, including the reply it ended with (often where a PR was opened), would never be indexed. `ccc` therefore sends one final index call per session: the main conversation plus that last reply, read from Claude Code's transcript, flagged so MemTree indexes the tail even below its minimum (at most once per conversation per 30 minutes; two conversations with an identical first message share that allowance). It goes out 10 minutes after a turn ends with no new request, or at exit for the 3 most recent sessions, inside the 2-second background drain; `-p` and non-TTY runs, which have no `Stop` hook, get it at exit. A failure is logged and never changes `ccc`'s exit code. Until then, `read_lines` with `"tail": true` reads the messages after the tree verbatim. When `ccc` runs inside another Claude Code session, the inner Claude Code writes no transcript unless `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` is set; without it the final index still covers everything through the last request, just not the final reply.
-
-`ccc` installs a minimal session-only Claude Code plugin using the repeatable `--plugin-dir` option. Its `MessageDisplay` hook changes only what the terminal renders and never alters stored assistant content; a `Stop` hook supplies a fallback for tool-only responses. That fallback may be saved by Claude Code as non-model hook UI metadata, but it is excluded from resumed model and recap requests. Notices are never added to model context, and Anthropic responses are left untouched with one exception: the hidden recap request Claude Code sends when you come back to an idle session gets a final `• MemTree` / `<url>` text block, so the recap ends with the link (not added when `CCC_MEMTREE_LINK=off`). Claude Code keeps that recap as a UI-only system entry, never as conversation content, and the block is skipped when it would push the recap past Claude Code's 400-character cap, and `-p`/non-TTY output is left unchanged. Legacy marker cleanup remains for transcripts created by older `ccc` releases. The payment state can also produce a separate terminal warning at startup.
-
-Claude Code currently displays the original assistant text instead of `MessageDisplay` replacements while verbose mode is enabled. Turn verbose mode off to see the inline MemTree line.
+Turn diagnostics off with any of: `CCC_NO_DIAGNOSTICS=1`, `"diagnostics": false` in
+`~/.claude-code-infinite/config.json`, `DO_NOT_TRACK=1`, or Claude Code's own
+`DISABLE_TELEMETRY=1` / `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1`.
 
 ### Memory tools
 
@@ -173,7 +223,7 @@ Interactive `ccc` sessions also get a small MCP server, `memtree`, with four rea
 
 When you send a message, we retrieve relevant details and summaries from the prior messages in your thread. These details and summaries populate a **memory message**. Following the memory message, we append a compressed version of your recent message history. The resulting context-window is dramatically smaller, allowing Claude to process your request with much greater efficacy, lower latency, and reduced cost.
 
-**Compaction keeps a stable prefix.** While a conversation fits the model's budget (800k tokens for Opus 5.5), it is sent whole. When a request reaches the budget, `ccc` compresses it once, to half the budget (or your `/memtree-compact N`), and keeps those compressed bytes as the session's prefix. Every later request, human turns included, is that same prefix followed by the messages that came after it, verbatim, with no compression call (MemTree still indexes in the background). Because the prefix does not change, Anthropic reads it from the prompt cache on every turn after the one that compacted, instead of writing the whole compressed context again. `ccc` compresses again only when prefix plus newer turns reach the budget (measured from the size Anthropic reported for the previous request, plus an estimate for what was added), or when the messages the prefix stands for change (rewind, edit, fork, `/clear`). If that recompression fails, the turn is sent on the old prefix rather than the whole history. The prefix is also kept on disk, one file per session under `~/.claude-code-infinite/stable-prefixes/` (mode 600 in a private directory, at most 64 sessions and 256 MB, oldest dropped first), so the first turn after `ccc --resume` rides it instead of waiting on a fresh compression. A stored prefix belongs to the MemTree backend and key that wrote it (identified by a hash, never the key itself) and is never used with another. It is used only if the resumed history still matches what it replaced; a main-thread history that no longer matches discards it, while side requests (such as Claude Code's web-search helper) leave it alone. Only the main thread's prefix is stored, never a subagent's. The budget is the one MemTree reports for the model; until the server reports one, `ccc` uses 80% of the model's context window. `CCC_BUDGET_TOKENS=60k` overrides it for testing. Every `requests.jsonl` line carries the `pid` of the `ccc` process that wrote it, which tells apart concurrent sessions sharing the log. The same rule holds inside a tool loop, so a long single turn (a headless `-p` run, or a long agentic loop) is compacted as it grows rather than only when you next type: each tool request under the budget goes out with no compression call, the one that reaches it is compressed once and becomes the stable prefix, and later tool requests and your next message ride that prefix until it reaches the budget again. `requests.jsonl` shows the `compaction` of each main-thread human turn and of every tool turn (budget, its source, the size estimate, and the reason for a compaction: `budget`, `prefix-mismatch`, `manual` or `target-change`); a human turn sent on the stable prefix is `turnType: "followup-prefix"`, a tool turn `tool-memory` (on its route) or `tool-prefix` (on the prefix directly), and a tool turn that compacted `tool-recompressed`.
+**Compaction keeps a stable prefix.** While a conversation fits the model's budget (900k tokens for Opus 5.5, where plain Claude Code would auto-compact at 967k), it is sent whole. When a request reaches the budget, `ccc` compresses it once, to half the budget (or your `/memtree-compact N`), and keeps those compressed bytes as the session's prefix. Every later request, human turns included, is that same prefix followed by the messages that came after it, verbatim, with no compression call (MemTree still indexes in the background). Because the prefix does not change, Anthropic reads it from the prompt cache on every turn after the one that compacted, instead of writing the whole compressed context again. `ccc` compresses again only when prefix plus newer turns reach the budget (measured from the size Anthropic reported for the previous request, plus an estimate for what was added), or when the messages the prefix stands for change (rewind, edit, fork, `/clear`). If that recompression fails, the turn is sent on the old prefix rather than the whole history. The prefix is also kept on disk, one file per session under `~/.claude-code-infinite/stable-prefixes/` (mode 600 in a private directory, at most 64 sessions and 256 MB, oldest dropped first), so the first turn after `ccc --resume` rides it instead of waiting on a fresh compression. A stored prefix belongs to the MemTree backend and key that wrote it (identified by a hash, never the key itself) and is never used with another. It is used only if the resumed history still matches what it replaced; a main-thread history that no longer matches discards it, while side requests (such as Claude Code's web-search helper) leave it alone. Only the main thread's prefix is stored, never a subagent's. The budget is the one MemTree reports for the model; until the server reports one, `ccc` uses 90% of the context window on Opus 5.5, Opus 5, Opus 4.8 and Fable 5 and 5.1 with a 1M window, and 80% otherwise. `CCC_BUDGET_TOKENS=60k` overrides it for testing. Every `requests.jsonl` line carries the `pid` of the `ccc` process that wrote it, which tells apart concurrent sessions sharing the log. The same rule holds inside a tool loop, so a long single turn (a headless `-p` run, or a long agentic loop) is compacted as it grows rather than only when you next type: each tool request under the budget goes out with no compression call, the one that reaches it is compressed once and becomes the stable prefix, and later tool requests and your next message ride that prefix until it reaches the budget again. `requests.jsonl` shows the `compaction` of each main-thread human turn and of every tool turn (budget, its source, the size estimate, and the reason for a compaction: `budget`, `prefix-mismatch`, `manual` or `target-change`); a human turn sent on the stable prefix is `turnType: "followup-prefix"`, a tool turn `tool-memory` (on its route) or `tool-prefix` (on the prefix directly), and a tool turn that compacted `tool-recompressed`.
 
 That compressed context stays in force for the rest of the turn: the tool loop it kicks off, and the matching Count Tokens calls, are routed through the same compressed prefix. The Count Tokens part matters — Claude Code sizes its context from those replies, so counting the uncompressed history would make it auto-compact a conversation memory had already shrunk. A mismatched or resumed conversation shape drops the route rather than grafting one session's prefix onto another.
 
@@ -256,6 +306,30 @@ features, and their output, often the biggest source of tokens, is exactly what
 For `ccc --resume <id>`, an automatic, best-effort repair can unblock a transcript whose last response already exceeds Claude Code’s local refusal limit. It changes only that response’s usage totals and the iteration Claude Code counts, after writing an exclusive, uniquely named backup under `~/.claude-code-infinite/transcript-backups`. Earlier iterations and conversation content stay intact. The installed Claude Code 2.1.288 computes its blocking limit as the context window minus the output allowance (capped at 20,000) minus 3,000 tokens: 977,000 for the supported 1M models. Other versions use the conservative full-window threshold. The window comes from ccc’s model table, explicit `[1m]` transcript model signals, and any `--model` or `ANTHROPIC_MODEL` override, conservatively keeping the largest supported window. A successful response with input already beyond that inferred window disproves the inference and is never repaired. Unknown model overrides (including unresolved aliases), models or usage shapes, threshold overrides, possible running writers, changed snapshots, backup collisions, and filesystem errors all skip repair and continue the original resume. Process and file checks are bounded; other running JavaScript runtimes may conservatively prevent repair.
 
 
+## Releasing
+
+Releases are staged by GitHub Actions through npm Trusted Publishing (OIDC), so no npm
+token, passkey or browser is needed to build and upload them, and each one is approved by a
+maintainer before it goes live:
+
+1. On a clean `main`, run `./publish.sh` (or `./publish.sh minor` / `major`). It builds,
+   checks that `dist/` is committed, runs `npm version`, and pushes the commit and the
+   `vX.Y.Z` tag.
+2. The tag push runs [`.github/workflows/publish.yml`](.github/workflows/publish.yml): `npm ci`,
+   the test suite with `NO_COLOR=1` and with `FORCE_COLOR=1`, a check that the rebuilt
+   `dist/` matches the commit and that the tag equals `package.json`'s version, then
+   `npm stage publish --provenance`.
+3. Approve the staged version (2FA) on
+   [npmjs.com](https://www.npmjs.com/package/claude-code-infinite) under the **Staged
+   Packages** tab, or with `npm stage list claude-code-infinite` and
+   `npm stage approve <stage-id>`. Until then it is not installable.
+
+The trusted publisher on npmjs.com is bound to the workflow file name `publish.yml` with no
+GitHub environment, and allows only staged publishing; renaming the workflow breaks it.
+`./publish.sh --local` is the fallback: it publishes directly from your machine with npm web
+auth, then pushes the commit and tag; the workflow still tests that tag but skips staging,
+since the version is already published.
+
 ## Troubleshooting
 
 ### Anthropic auth errors (401s, login prompts)
@@ -269,11 +343,12 @@ If you see an inline "⚠ MemTree degraded — this turn ran uncompressed" notic
 ## Upgrading
 
 `ccc` checks npm at startup (bounded to 1.5 seconds, silent if offline, and cached for a
-day in `~/.claude-code-infinite/update-check.json`) and, when a newer release exists,
-shows one line under the MemTree banner inside Claude Code, e.g.
-`• ccc 1.0.20 is available (you have 1.0.14) · npm i -g claude-code-infinite@latest`.
-Prereleases are never offered, and print (`-p`) or non-TTY runs skip the check. Upgrading
-is never automatic:
+day in `~/.claude-code-infinite/update-check.json`). Prereleases are never offered, and
+print (`-p`) or non-TTY runs skip the check. When a newer release exists and `ccc` can
+update itself, it does (see [Automatic updates](#automatic-updates)); otherwise it shows
+one line under the MemTree banner inside Claude Code, e.g.
+`• ccc 1.0.21 is available (you have 1.0.20) · npm i -g claude-code-infinite@latest`.
+To upgrade by hand:
 
 ```bash
 npm i -g claude-code-infinite@latest
@@ -281,4 +356,64 @@ npm i -g claude-code-infinite@latest
 
 Set `CCC_NO_UPDATE_CHECK=1` (or the older `CCC_SKIP_UPDATE_CHECK=1`), or add
 `"updateCheck": false` to `~/.claude-code-infinite/config.json`, to disable the check
-(air-gapped or CI runs).
+(air-gapped or CI runs). That also turns off automatic updates.
+
+## Automatic updates
+
+Like Claude Code, `ccc` installs a newer release for you in the background. A few
+seconds after an interactive session starts, if the update check found a newer
+release, `ccc` runs
+
+```bash
+npm install --global --prefix=<your npm prefix> claude-code-infinite@<that version> --no-fund --no-audit
+```
+
+in a detached process, so the session never waits for it and quitting `ccc` does not
+stop it. When it has finished, the next session start inside Claude Code (a new
+conversation, `/clear`, or a resume) shows, once:
+
+```
+✔ ccc 1.0.21 installed · restart ccc to use it
+```
+
+The session keeps running the version it started with until you restart `ccc`. If the
+install fails, you get the usual `• ccc 1.0.21 is available … · npm i -g
+claude-code-infinite@latest` line instead, and `ccc` waits a day before trying again; it
+tries each version at most twice. The npm output of the last attempt is in
+`~/.claude-code-infinite/auto-update.log`, and its result in `update-state.json` next to
+it. Only one session installs at a time (`update.lock.d` there). If an installer was
+killed in a way `ccc` cannot verify, that lock stays held rather than risk two installs
+at once; after an hour `ccc` shows the update line instead, and deleting
+`~/.claude-code-infinite/update.lock.d` clears it.
+
+**When it doesn't.** `ccc` updates itself only when it is a plain global npm install
+(`npm i -g`) whose files are in `npm root -g` and writable by you. It never uses `sudo`.
+In every other case it only shows the update line:
+
+- `npm link`ed or git checkouts (a development copy is never touched),
+- `npx` and project-local installs,
+- pnpm, yarn, bun and Volta global installs (update with your tool's own command),
+- a global prefix that needs `sudo` to write, or `ccc` running as root,
+- Windows,
+- print (`-p`) and non-TTY runs, which never install anything.
+
+`ccc --debug` prints which install method was detected and what it decided.
+
+**Sessions running during an update.** npm replaces `ccc`'s files while other `ccc`
+sessions may be running. They are unaffected: each `ccc` loads all of its code when it
+starts, and the Claude Code hooks it registers either call into that running `ccc` over
+localhost or run files in its own temporary plugin directory, never the installed
+package. The one exception is the `memtree` MCP server, which Claude Code starts from the
+installed files: a server started after the update (for example, Claude Code restarting
+it with `/mcp`) runs the new version against the old session. It keeps working, and if a
+tool call fails it says that the versions differ and to restart `ccc`. If Claude Code
+starts it in the few seconds while npm is writing the files, it can fail to start; `/mcp`
+reconnects it.
+
+**Turning it off.** Any of these keeps the update line but never installs:
+
+- `CCC_DISABLE_AUTOUPDATE=1`,
+- `"autoUpdate": false` in `~/.claude-code-infinite/config.json`,
+- Claude Code's own `DISABLE_AUTOUPDATER=1`.
+
+The update-check opt-outs above turn off both the check and automatic updates.

package/dist/auto-update-runner.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The detached background installer for auto-update.ts, as source text that
+ * ccc runs with `node -e RUNNER_SOURCE <config json>`.
+ *
+ * Self-contained on purpose: it requires only Node built-ins and reads no file
+ * from the ccc package, because the npm install it runs replaces that package.
+ * It outlives the ccc that started it (detached, own process group), records
+ * the result in update-state.json and releases the lock by its token.
+ *
+ * Ownership: the launcher created this runner's lock entry and records the
+ * runner's pid in it right after spawning; the runner waits for that handoff,
+ * exits without touching anything if the entry is gone, and re-checks the
+ * entry before every npm command. Once stopping (abort or lost lock) it never
+ * starts another command.
+ *
+ * Steps: re-validate the version; confirm `npm root -g` is the directory this
+ * ccc lives in and that the entry there is not a symlink (an `npm link`); run
+ * `npm install --global --prefix=<that prefix> claude-code-infinite@<version>
+ * --no-fund --no-audit` (argv, never a shell); confirm the package.json now
+ * says that version. Any failure is recorded with a short reason.
+ *
+ * Bounded: each npm command runs in its own process group, recorded in the
+ * lock entry. When it ends (or times out) the whole group is reaped: SIGTERM,
+ * then SIGKILL, until no member is left, so a descendant that outlives npm
+ * cannot go on writing the package. The lock is released only once the group
+ * is confirmed gone; otherwise the entry stays live for as long as the group
+ * is (update-lock.ts). A hard deadline and SIGTERM/SIGINT/SIGHUP to the runner
+ * kill the group, record a failure and exit, so the lock's stale age is never
+ * reached by a live runner.
+ */
+/** What ccc passes the runner, as JSON in argv[1]. */
+export interface RunnerConfig {
+    npm: string;
+    packageName: string;
+    version: string;
+    packageDir: string;
+    npmRoot: string;
+    prefix: string;
+    stateFile: string;
+    /** update-lock.ts directory; this runner owns `<lockDir>/<token>.json`. */
+    lockDir: string;
+    logFile: string;
+    token: string;
+    timeoutMs: number;
+    /** Test-only: how long to wait for the launcher's handoff (default 10 s). */
+    handoffMs?: number;
+    /** Test-only: SIGTERM→SIGKILL and SIGKILL→give-up waits (default 10 s, 5 s). */
+    killGraceMs?: number;
+    pipeGraceMs?: number;
+}
+export declare const RUNNER_SOURCE: string;
+//# sourceMappingURL=auto-update-runner.d.ts.map

package/dist/auto-update-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-update-runner.d.ts","sourceRoot":"","sources":["../src/auto-update-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,aAAa,QAmRzB,CAAC"}

package/dist/auto-update-runner.js

@@ -0,0 +1,307 @@
+/**
+ * The detached background installer for auto-update.ts, as source text that
+ * ccc runs with `node -e RUNNER_SOURCE <config json>`.
+ *
+ * Self-contained on purpose: it requires only Node built-ins and reads no file
+ * from the ccc package, because the npm install it runs replaces that package.
+ * It outlives the ccc that started it (detached, own process group), records
+ * the result in update-state.json and releases the lock by its token.
+ *
+ * Ownership: the launcher created this runner's lock entry and records the
+ * runner's pid in it right after spawning; the runner waits for that handoff,
+ * exits without touching anything if the entry is gone, and re-checks the
+ * entry before every npm command. Once stopping (abort or lost lock) it never
+ * starts another command.
+ *
+ * Steps: re-validate the version; confirm `npm root -g` is the directory this
+ * ccc lives in and that the entry there is not a symlink (an `npm link`); run
+ * `npm install --global --prefix=<that prefix> claude-code-infinite@<version>
+ * --no-fund --no-audit` (argv, never a shell); confirm the package.json now
+ * says that version. Any failure is recorded with a short reason.
+ *
+ * Bounded: each npm command runs in its own process group, recorded in the
+ * lock entry. When it ends (or times out) the whole group is reaped: SIGTERM,
+ * then SIGKILL, until no member is left, so a descendant that outlives npm
+ * cannot go on writing the package. The lock is released only once the group
+ * is confirmed gone; otherwise the entry stays live for as long as the group
+ * is (update-lock.ts). A hard deadline and SIGTERM/SIGINT/SIGHUP to the runner
+ * kill the group, record a failure and exit, so the lock's stale age is never
+ * reached by a live runner.
+ */
+export const RUNNER_SOURCE = String.raw `"use strict";
+const { spawn } = require("node:child_process");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+
+const VERSION_RE = /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/;
+const ROOT_TIMEOUT_MS = 60000;
+const cfg = JSON.parse(process.argv[1]);
+const KILL_GRACE_MS = cfg.killGraceMs || 10000;
+const PIPE_GRACE_MS = cfg.pipeGraceMs || 5000;
+const ENTRY = path.join(cfg.lockDir, cfg.token + ".json");
+const HANDOFF_MS = cfg.handoffMs || 10000;
+let logFd = null;
+let group = null;
+let done = false;
+// Set first thing on abort or a lost lock: no command starts after it.
+let stopping = null;
+
+// Hard deadline: whatever npm does, this process kills its group, records a
+// result and exits, so a live holder never outlasts the lock's stale age.
+const DEADLINE_MS = ROOT_TIMEOUT_MS + cfg.timeoutMs + 2 * (2 * KILL_GRACE_MS + 2 * PIPE_GRACE_MS) + 30000;
+setTimeout(() => abort("runner deadline passed"), DEADLINE_MS);
+for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) {
+  process.on(signal, () => abort("runner stopped by " + signal));
+}
+
+function note(line) {
+  try {
+    if (logFd !== null) fs.writeSync(logFd, "[" + new Date().toISOString() + "] " + line + "\n");
+  } catch {}
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function groupAlive(pgid) {
+  try {
+    process.kill(-pgid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+
+function signalGroup(pgid, signal) {
+  try { process.kill(-pgid, signal); } catch {}
+}
+
+async function goneWithin(pgid, ms) {
+  const until = Date.now() + ms;
+  while (groupAlive(pgid)) {
+    if (Date.now() >= until) return false;
+    await sleep(100);
+  }
+  return true;
+}
+
+// Every member of the command's group, not only npm: SIGTERM, then SIGKILL.
+async function reapGroup(pgid) {
+  if (!groupAlive(pgid)) return true;
+  signalGroup(pgid, "SIGTERM");
+  if (await goneWithin(pgid, KILL_GRACE_MS)) return true;
+  signalGroup(pgid, "SIGKILL");
+  return goneWithin(pgid, PIPE_GRACE_MS);
+}
+
+// The lock entry names the group while it may be alive (update-lock.ts).
+// "spawning" is set before every npm spawn and cleared only once its group is
+// recorded: if this runner dies in between, the entry stays live (fail
+// closed) because an unrecorded npm may be running (update-lock.ts).
+function recordGroup(pgid, spawning) {
+  const entry = readEntry();
+  if (!entry) {
+    stopping = stopping || "lost the install lock";
+    if (pgid !== null) signalGroup(pgid, "SIGKILL"); // started without the lock: stop it
+    return false;
+  }
+  try {
+    entry.pid = process.pid;
+    entry.runner = process.pid;
+    if (pgid === null) delete entry.group; else entry.group = pgid;
+    if (spawning) entry.spawning = true; else delete entry.spawning;
+    const tmp = path.join(cfg.lockDir, "." + cfg.token + "." + process.pid + ".tmp");
+    fs.writeFileSync(tmp, JSON.stringify(entry), { mode: 0o600 });
+    fs.renameSync(tmp, ENTRY);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readEntry() {
+  try {
+    const entry = JSON.parse(fs.readFileSync(ENTRY, "utf8"));
+    return entry && entry.token === cfg.token ? entry : null;
+  } catch {
+    return null;
+  }
+}
+
+// The launcher records this runner's pid in the entry right after spawning
+// it; until then the entry is not provably ours. Gone means another session
+// took the lock: leave everything to it.
+async function awaitHandoff() {
+  const until = Date.now() + HANDOFF_MS;
+  for (;;) {
+    const entry = readEntry();
+    if (!entry) return "lost";
+    if (entry.runner === process.pid) return "ok";
+    if (Date.now() >= until) return "timeout";
+    await sleep(50);
+  }
+}
+
+// Resolves when the command is over: it closed, it exited (its pipes are not
+// waited on for long), or it timed out. The caller then reaps its group.
+function run(command, args, timeoutMs, capture) {
+  return new Promise((resolve) => {
+    let out = "";
+    let settled = false;
+    let child;
+    const timers = [];
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      timers.forEach(clearTimeout);
+      resolve(Object.assign({ out, pgid: child ? child.pid : null }, result));
+    };
+    if (stopping || !recordGroup(null, true)) {
+      finish({ code: null, error: stopping || "lost the install lock" });
+      return;
+    }
+    try {
+      child = spawn(command, args, {
+        cwd: os.homedir(),
+        env: process.env,
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: true,
+      });
+    } catch (err) {
+      recordGroup(null, false);
+      finish({ code: null, error: String(err) });
+      return;
+    }
+    if (child.pid) {
+      group = child.pid;
+      recordGroup(group, false);
+    } else {
+      recordGroup(null, false); // spawn failed; its 'error' event follows
+    }
+    timers.push(setTimeout(() => finish({ code: null, timedOut: true }), timeoutMs));
+    const logChunk = (chunk) => {
+      try { if (logFd !== null) fs.writeSync(logFd, chunk); } catch {}
+    };
+    child.stdout.on("data", (chunk) => {
+      if (capture && out.length < 65536) out += chunk.toString("utf8");
+      logChunk(chunk);
+    });
+    child.stderr.on("data", logChunk);
+    child.on("error", (err) => finish({ code: null, error: String(err) }));
+    child.on("exit", (code, signal) => {
+      timers.push(setTimeout(() => finish({ code, signal }), PIPE_GRACE_MS));
+    });
+    child.on("close", (code, signal) => finish({ code, signal }));
+  });
+}
+
+// Run a command and make sure nothing it started is left running.
+async function runReaped(command, args, timeoutMs, capture) {
+  const result = await run(command, args, timeoutMs, capture);
+  if (result.pgid) {
+    if (!(await reapGroup(result.pgid))) {
+      const err = new Error("could not stop npm's processes (group " + result.pgid + ")");
+      err.groupAlive = true;
+      throw err;
+    }
+    group = null;
+    recordGroup(null, false);
+  }
+  return result;
+}
+
+function realpath(p) {
+  try { return fs.realpathSync(p); } catch { return null; }
+}
+
+function describe(result, what) {
+  if (result.error) return what + " could not run: " + result.error;
+  if (result.timedOut) return what + " timed out";
+  if (result.code !== 0) return what + " exited with " + (result.code === null ? result.signal : result.code);
+  return null;
+}
+
+async function install() {
+  if (!VERSION_RE.test(cfg.version)) throw new Error("refusing version " + JSON.stringify(cfg.version));
+  const rootRun = await runReaped(cfg.npm, ["root", "--global"], ROOT_TIMEOUT_MS, true);
+  const rootFailure = describe(rootRun, "npm root -g");
+  if (rootFailure) throw new Error(rootFailure);
+  const npmRoot = realpath(rootRun.out.trim());
+  if (npmRoot === null || npmRoot !== realpath(cfg.npmRoot)) {
+    throw new Error("npm root -g is " + rootRun.out.trim() + ", not " + cfg.npmRoot + ": wrong prefix");
+  }
+  const entry = path.join(npmRoot, cfg.packageName);
+  if (fs.lstatSync(entry).isSymbolicLink()) throw new Error(entry + " is a symlink (npm link)");
+  if (realpath(entry) !== realpath(cfg.packageDir)) throw new Error(entry + " is not this ccc");
+  const spec = cfg.packageName + "@" + cfg.version;
+  const args = ["install", "--global", "--prefix=" + cfg.prefix, spec, "--no-fund", "--no-audit"];
+  note("npm " + args.join(" "));
+  const failure = describe(await runReaped(cfg.npm, args, cfg.timeoutMs, false), "npm install");
+  if (failure) throw new Error(failure);
+  const pkg = JSON.parse(fs.readFileSync(path.join(cfg.packageDir, "package.json"), "utf8"));
+  if (pkg.version !== cfg.version) throw new Error("installed version is " + pkg.version);
+}
+
+function record(status, error) {
+  let state = {};
+  try { state = JSON.parse(fs.readFileSync(cfg.stateFile, "utf8")) || {}; } catch {}
+  state.last = { version: cfg.version, status, at: Date.now(), packageDir: cfg.packageDir };
+  if (error) state.last.error = String(error).slice(0, 300);
+  const tmp = cfg.stateFile + "." + process.pid + ".tmp";
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(state), { mode: 0o600 });
+    fs.renameSync(tmp, cfg.stateFile);
+  } catch {
+    try { fs.rmSync(tmp, { force: true }); } catch {}
+  }
+}
+
+// Record, release the lock unless npm's group may still be alive (its entry
+// then stays live exactly as long as the group: update-lock.ts), and exit.
+function finishRun(status, error) {
+  if (done) return;
+  done = true;
+  note(status === "ok" ? "installed " + cfg.version : "failed: " + error);
+  // Without the lock the state belongs to whoever holds it now.
+  if (readEntry()) record(status, error);
+  if (group === null || !groupAlive(group)) {
+    try { fs.rmSync(ENTRY, { force: true }); } catch {}
+  } else {
+    note("npm's processes are still exiting; the lock stays held until they are gone");
+  }
+  try { if (logFd !== null) fs.closeSync(logFd); } catch {}
+  process.exit(status === "ok" ? 0 : 1);
+}
+
+async function abort(reason) {
+  if (done || stopping) return;
+  stopping = reason;
+  if (group !== null) {
+    signalGroup(group, "SIGKILL");
+    await goneWithin(group, 2000);
+  }
+  finishRun("failed", reason);
+}
+
+(async () => {
+  const handoff = await awaitHandoff();
+  if (handoff === "lost") process.exit(1); // not ours: record nothing, touch nothing
+  if (handoff === "timeout") {
+    stopping = "the launcher never handed over the install lock";
+    finishRun("failed", stopping);
+    return;
+  }
+  recordGroup(null, false); // the lock's holder is this runner from now on
+  try { logFd = fs.openSync(cfg.logFile, "w", 0o600); } catch {}
+  note("installing " + cfg.packageName + "@" + cfg.version + " into " + cfg.prefix);
+  try {
+    await install();
+    finishRun("ok");
+  } catch (err) {
+    finishRun("failed", err && err.message ? err.message : String(err));
+  }
+})();
+`;
+//# sourceMappingURL=auto-update-runner.js.map

package/dist/auto-update-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-update-runner.js","sourceRoot":"","sources":["../src/auto-update-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAuBH,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmRtC,CAAC"}