chad-code 2.0.1__tar.gz → 2.0.3__tar.gz

{chad_code-2.0.1 → chad_code-2.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chad-code
-Version: 2.0.1
+Version: 2.0.3
 Summary: Claude-Code-style coding agent that runs entirely on a 24 GB Apple Silicon Mac (MLX, Qwen3.8-27B)
 License-Expression: MIT
 Project-URL: Repository, https://github.com/nathansutton/chad
@@ -33,11 +33,11 @@ Provides-Extra: speech
 Requires-Dist: sounddevice>=0.5; extra == "speech"
 Dynamic: license-file
 
-# chad: a Claude-Code-style coding agent that fits on a 24 GB MacBook
+# chad: a local Claude-Code-style coding agent for your laptop
 
 [![tests](https://github.com/nathansutton/chad/actions/workflows/tests.yml/badge.svg)](https://github.com/nathansutton/chad/actions/workflows/tests.yml)
 
-<img src="docs/claude-vs-chad.jpg" width="33%" alt="Two staircase newel posts side by side: Claude is a hand-carved wooden horse head, chad is a scuffed plastic toy horse tied on with twine">
+<img src="docs/claude-vs-chad.jpg" width="66%" alt="Two staircase newel posts side by side: Claude is a hand-carved wooden horse head, chad is a scuffed plastic toy horse tied on with twine">
 
 > Claude can do anything, for anyone, anywhere. chad does one thing. 🗿
 > *Coding under supervision.*
@@ -118,7 +118,7 @@ one checkpoint it ships:
   cache, so a follow-up step prefills the ~16 tokens it appended instead of the 5,000 it
   already read: **~0.75 s per step instead of ~50 s**. Any server with prompt caching gets
   the easy case; the work is holding it true across compaction, truncated turns and restarts.
-  The system prefix is checkpointed to disk, so the second session in a project starts warm
+  The system prefix is checkpointed to disk, so the second session anywhere starts warm
   (75.6 s → 5.5 s to the first tool call).
 - **Fused Metal kernels.** Quantized-KV attention, a small-M matmul for speculative verify,
   and a compiled single-token layer step, chosen per machine at load time, no knobs.

{chad_code-2.0.1 → chad_code-2.0.3}/README.md

@@ -1,8 +1,8 @@
-# chad: a Claude-Code-style coding agent that fits on a 24 GB MacBook
+# chad: a local Claude-Code-style coding agent for your laptop
 
 [![tests](https://github.com/nathansutton/chad/actions/workflows/tests.yml/badge.svg)](https://github.com/nathansutton/chad/actions/workflows/tests.yml)
 
-<img src="docs/claude-vs-chad.jpg" width="33%" alt="Two staircase newel posts side by side: Claude is a hand-carved wooden horse head, chad is a scuffed plastic toy horse tied on with twine">
+<img src="docs/claude-vs-chad.jpg" width="66%" alt="Two staircase newel posts side by side: Claude is a hand-carved wooden horse head, chad is a scuffed plastic toy horse tied on with twine">
 
 > Claude can do anything, for anyone, anywhere. chad does one thing. 🗿
 > *Coding under supervision.*
@@ -83,7 +83,7 @@ one checkpoint it ships:
   cache, so a follow-up step prefills the ~16 tokens it appended instead of the 5,000 it
   already read: **~0.75 s per step instead of ~50 s**. Any server with prompt caching gets
   the easy case; the work is holding it true across compaction, truncated turns and restarts.
-  The system prefix is checkpointed to disk, so the second session in a project starts warm
+  The system prefix is checkpointed to disk, so the second session anywhere starts warm
   (75.6 s → 5.5 s to the first tool call).
 - **Fused Metal kernels.** Quantized-KV attention, a small-M matmul for speculative verify,
   and a compiled single-token layer step, chosen per machine at load time, no knobs.

{chad_code-2.0.1 → chad_code-2.0.3}/pyproject.toml

@@ -4,7 +4,7 @@
 # import name, and command name are independent. `uvx chad-code` runs the alias
 # script added under [project.scripts].
 name = "chad-code"
-version = "2.0.1"
+version = "2.0.3"
 description = "Claude-Code-style coding agent that runs entirely on a 24 GB Apple Silicon Mac (MLX, Qwen3.8-27B)"
 readme = "README.md"
 license = "MIT"
@@ -138,6 +138,8 @@ testpaths = ["tests"]
 
 [tool.ruff]
 line-length = 100
+# Vendored Exercism exercises (benchmarks/matrix/tasks/) are upstream files, kept byte-identical.
+extend-exclude = ["benchmarks/matrix/tasks"]
 src = ["src", "tests"]
 
 [tool.ruff.lint]

{chad_code-2.0.1 → chad_code-2.0.3}/src/chad/__init__.py

@@ -4,7 +4,7 @@ A flat collection of cooperating modules behind one console script (``chad``):
 the inference engine, the tool layer, the agent loop, and the terminal UI.
 """
 
-__version__ = "2.0.1"
+__version__ = "2.0.3"
 
 # chad sets no MLX_* runtime vars. MLX_METAL_FAST_SYNCH, MLX_MAX_OPS_PER_BUFFER
 # and MLX_MAX_MB_PER_BUFFER were each measured end-to-end on the 35B and every

{chad_code-2.0.1 → chad_code-2.0.3}/src/chad/agent.py

@@ -29,7 +29,7 @@ from . import (
 )
 from .base_engine import BaseEngine
 from .diag import args_preview, log, redact, result_preview
-from .prompt import build_system_prompt, classify_intent
+from .prompt import build_system_prompt, classify_intent, static_system_prompt
 from .render import (
     C_DIM,
     C_RED,
@@ -206,8 +206,15 @@ def close_unclosed_think(text: str, thinking: bool) -> str:
     re-prefill of the whole transcript next step (measured: tens of thousands of tokens
     at large context). Appending the missing `</think>` keeps the cached tokens a strict
     prefix of the re-render, so only a couple of tokens prefill instead. No-op when
-    thinking is off or the block is already closed."""
-    if thinking and "<think>" not in text and "</think>" not in text and text:
+    thinking is off or the block is already closed.
+
+    Only the CLOSE decides this. An earlier guard also required no `<think>` in the
+    text, which read a stray opening tag — one the model wrote inside its own reasoning,
+    not the template's — as "already a block" and skipped the append. That turn then
+    reached `split_inline_reasoning` with no `</think>` to split on, so it was stored raw
+    and re-rendered with an injected empty think block: the exact full re-prefill this
+    function exists to prevent, on the longest turns, where it costs the most."""
+    if thinking and "</think>" not in text and text:
         return text + "\n</think>"
     return text
 
@@ -237,8 +244,17 @@ def split_inline_reasoning(m: dict) -> dict:
     if m.get("role") != "assistant" or "</think>" not in content:
         return m
     head, _, tail = content.partition("</think>")
+    head = head.rstrip("\n")
+    # Strip a LEADING `<think>` only. The generation prompt already opened the block, so
+    # any later tag is reasoning the model wrote, not a delimiter. Taking the LAST one
+    # (`split("<think>")[-1]`) silently dropped every reasoning token before a stray tag:
+    # transcript content lost, and the shortened re-render diverges from the cache right
+    # where the turn began.
+    unwrapped = head.lstrip()
+    if unwrapped.startswith("<think>"):
+        head = unwrapped[len("<think>"):]
     return {**m,
-            "reasoning_content": head.rstrip("\n").split("<think>")[-1].lstrip("\n"),
+            "reasoning_content": head.lstrip("\n"),
             "content": tail.lstrip("\n")}
 
 
@@ -788,6 +804,36 @@ class Agent:
             n += 1
         return list(a[:n])
 
+    def _static_head_ids(self) -> list:
+        """The project-independent head of `_stable_prefix_ids`: everything the
+        template renders before the per-session tail of the system prompt (cwd,
+        workspace listing, project docs). Found the same way — two renders differenced,
+        one with the full system prompt and one with only its static text — so it is
+        exact under any template, wherever that template puts the tool schemas. The
+        engine checkpoints this ONCE for every project and the full prefix once per
+        project (`Engine.warm_prefix`). Empty when the system prompt is not chad's own
+        or has no per-session tail, in which case only the full prefix is used."""
+        sysm = self.messages[0]
+        static = static_system_prompt()
+        content = sysm.get("content") or ""
+        if not content.startswith(static) or content == static:
+            return []
+        schemas = self._active_schemas()
+        def render1(m):
+            return self._template_ids(self.engine.tok.apply_chat_template(
+                [m, {"role": "user", "content": "a"}], tools=schemas,
+                add_generation_prompt=True, enable_thinking=self.thinking))
+        a, b = render1({"role": "system", "content": static}), render1(sysm)
+        n = 0
+        for x, y in zip(a, b):
+            if x != y:
+                break
+            n += 1
+        head, full = list(b[:n]), self._stable_prefix_ids()
+        if len(head) >= len(full) or full[: len(head)] != head:
+            return []
+        return head
+
     def _confirm(self, name, args) -> bool:
         # Destructive-bash seatbelt: a catastrophic shell command (rm -rf ~, mkfs,
         # curl|sh, …) is screened even in --yolo mode, because the model acts on
@@ -861,14 +907,39 @@ class Agent:
                 pass
         # Warm start: on a cold cache, load the system+tools KV from disk
         # (or prefill+persist it once) so the first turn doesn't re-prefill the
-        # ~3.2k-token stable prefix every session. Cheap no-op on a warm cache.
+        # ~2.5k-token stable prefix every session. Two tiers: the full prefix (same
+        # project) and its static head (any project — only the per-project tail is
+        # prefilled). Cheap no-op on a warm cache.
         if self.engine.cache_dir and not self.engine._cached_ids:
             try:
-                status, n = self.engine.warm_prefix(self._stable_prefix_ids(),
-                                                     should_stop=self._should_stop)
-                log.info("CACHE warm-start %s: %d prefix tokens (disk KV cache)", status, n)
+                t_warm = time.time()
+                full = self._stable_prefix_ids()
+                status, n = self.engine.warm_prefix(full, should_stop=self._should_stop,
+                                                     head_ids=self._static_head_ids())
+                warm_s = time.time() - t_warm
+                log.info("CACHE warm-start %s: %d prefix tokens (disk KV cache, %.1fs)",
+                         status, n, warm_s)
                 if status == "hit":
                     self._emit("info", f"  [warm start: {n:,} prefix tokens from disk cache]")
+                elif status == "partial":
+                    self._emit("info", f"  [warm start: {n:,} prefix tokens from disk cache; "
+                                       f"{len(full) - n:,} project tokens prefilled "
+                                       f"in {warm_s:.1f}s]")
+                # The prefix prefill happens BEFORE step 1, so a per-step trace would
+                # never see it: a miss is the whole cold prefill of the system prompt,
+                # paid while the user is already waiting. Recorded as its own row (seq 0)
+                # so an offline reader can add it to the first step's wait; step rows
+                # are untouched (their cached_tokens already count the prefix).
+                if _PREFILL_TRACE and status != "skip":
+                    # prefix_tokens is what `status` refers to (hit/partial: restored,
+                    # miss: prefilled); prefilled_tokens is the cold part either way.
+                    _trace_prefill({"seq": 0, "step": -1, "kind": "warm_prefix",
+                                    "status": status, "prefix_tokens": n,
+                                    "total_prefix": len(full),
+                                    "prefilled_tokens": (0 if status == "hit"
+                                                         else len(full) - n
+                                                         if status == "partial" else n),
+                                    "prefill_s": round(warm_s, 4)})
             except Exception as e:  # never let cache warming break a turn
                 log.warning("warm_prefix failed: %s", e)
         # @file mentions: inline any referenced files so the model has them without a

{chad_code-2.0.1 → chad_code-2.0.3}/src/chad/base_engine.py

@@ -207,10 +207,13 @@ class BaseEngine(Protocol):
         `_reset_cache`). Called on `/reset` and by the governor's fresh-turn relaunch."""
         ...
 
-    def warm_prefix(self, prefix_ids: list, should_stop: Optional[Callable[[], bool]] = None
-                    ) -> tuple[str, int]:
+    def warm_prefix(self, prefix_ids: list, should_stop: Optional[Callable[[], bool]] = None,
+                    head_ids: Optional[list] = None) -> tuple[str, int]:
         """Warm-start the stable system+tools prefix from disk (MLX) or no-op ('skip', 0)
-        on a stateless backend. Returns (status, n_tokens)."""
+        on a stateless backend. `head_ids`, if given, is the project-independent head
+        of `prefix_ids` (a proper prefix of it), checkpointed once for every project so
+        a fresh directory restores it and prefills only the tail. Returns
+        (status, n_tokens) with status 'hit' | 'partial' | 'miss' | 'skip'."""
         ...
 
     def push_cache(self) -> None:

{chad_code-2.0.1 → chad_code-2.0.3}/src/chad/completion_engine.py

@@ -236,7 +236,8 @@ class CompletionEngine:
     _reset_cache = reset   # cli/bench call the private spelling; keep it working
 
     def warm_prefix(self, prefix_ids: list,
-                    should_stop: Optional[Callable[[], bool]] = None) -> tuple[str, int]:
+                    should_stop: Optional[Callable[[], bool]] = None,
+                    head_ids: Optional[list] = None) -> tuple[str, int]:
         """Warm-start the stable prefix. Against stock llama.cpp there is nothing to do
         — the KV checkpoint would live on the SERVER's disk, which we can't reach — so
         this stays 'skip'. A `chad serve` server advertising `warm_prefix` does the
@@ -246,12 +247,15 @@ class CompletionEngine:
         self._ensure_caps()
         if CAP_WARM_PREFIX not in self._caps:
             return ("skip", 0)
-        resp = self._post_json("/warm", {"prefix": list(prefix_ids)})
+        body = {"prefix": list(prefix_ids)}
+        if head_ids:
+            body["head"] = list(head_ids)
+        resp = self._post_json("/warm", body)
         if not resp:
             return ("skip", 0)
         status = str(resp.get("status") or "skip")
         fed = int(resp.get("fed") or 0)
-        if status in ("hit", "miss") and fed:
+        if status in ("hit", "miss", "partial") and fed:
             # Mirror what the server now holds, so the first turn's prefill estimate
             # accounts for the prefix we just warmed instead of assuming a cold cache.
             self._cached_ids = list(prefix_ids[:fed])

{chad_code-2.0.1 → chad_code-2.0.3}/src/chad/engine.py

@@ -550,6 +550,9 @@ class Engine:
     _pld_hybrid: bool = field(init=False, default=False)
     _model_path: str = field(init=False, default="")  # resolved weights dir
     _warm_prefix_ids: Any = field(init=False, default=None)
+    # The project-independent head of that prefix (tool schemas + behavioral prompt),
+    # checkpointed once for every working directory; see warm_prefix.
+    _warm_head_ids: Any = field(init=False, default=None)
     kv_bytes_per_token: float = field(init=False, default=0.0)  # measured at load (036)
     # Model-shape facts read from config at load, for the adaptive prefill chunk.
     # MoE prefill amortizes routing with bigger chunks (+14% measured 512→2048 on
@@ -934,43 +937,92 @@ class Engine:
         kind = _CKPT_PUSH if tag == _CKPT_PUSH else _CKPT_WARM
         return os.path.join(self.cache_dir, f"{kind}-{h.hexdigest()}.safetensors")  # type: ignore[arg-type]
 
-    def warm_prefix(self, prefix_ids: list, should_stop=None):
-        """Make a cold session start warm. If a disk checkpoint for exactly these
-        prefix tokens exists, load it into the live cache (ZERO prefill); otherwise
-        prefill the prefix once and persist it for next time. Only valid on a cold
-        cache. Returns (status, n_tokens) where status is 'hit' | 'miss' | 'skip'."""
+    def warm_prefix(self, prefix_ids: list, should_stop=None, head_ids=None):
+        """Make a cold session start warm. Two checkpoints can serve it, longest first:
+
+        - the FULL prefix (tool schemas + system prompt, per-project tail included):
+          a hit is a restart in the same project — ZERO prefill;
+        - the static HEAD (`head_ids`: the part of the prefix that is byte-identical in
+          every project — tool schemas + behavioral prompt): a hit restores the head
+          and prefills only the per-project tail (cwd, workspace listing, project
+          docs — a few hundred tokens), so a fresh directory no longer pays the whole
+          ~2.5k-token cold prefill. Before this tier existed, the checkpoint was
+          keyed on the whole prompt and a new directory could never hit it.
+
+        A miss prefills the prefix once and persists BOTH checkpoints for next time.
+        Only valid on a cold cache. Returns (status, n_tokens): 'hit' (n = tokens
+        restored), 'partial' (head restored, n = its tokens; the rest was prefilled),
+        'miss' (n = tokens prefilled), 'skip'."""
         if not self.cache_dir or not prefix_ids:
             return ("skip", 0)
         if self._cached_ids:               # cache already populated this session
             return ("skip", 0)
+        prefix_ids = list(prefix_ids)
         path = self._ckpt_path(prefix_ids)
-        if os.path.isfile(path):
-            try:
-                loaded = cache_utils.load_prompt_cache(path)
-                # sanity: a loaded cache must have one entry per model layer
-                if len(loaded) == self._n_model_layers():
-                    self._cache = loaded
-                    self._cached_ids = list(prefix_ids)
-                    self._warm_prefix_ids = list(prefix_ids)
-                    self._set_cache_flags()
-                    return ("hit", len(prefix_ids))
-            except Exception:
-                pass                       # corrupt/incompatible -> recompute below
-        # miss: prefill the prefix into a fresh cache, then persist it.
+        if os.path.isfile(path) and self._load_ckpt(path, prefix_ids):
+            self._warm_prefix_ids = list(prefix_ids)
+            return ("hit", len(prefix_ids))
+        head = list(head_ids or [])
+        if not (head and len(head) < len(prefix_ids) and prefix_ids[: len(head)] == head):
+            head = []                      # not a proper prefix of this prefix: unusable
+        tail = prefix_ids[len(head):]
+        if head:
+            self._warm_head_ids = list(head)
+            hp = self._ckpt_path(head)
+            if os.path.isfile(hp) and self._load_ckpt(hp, head):
+                fed = self._prefill(tail, should_stop)
+                if fed < len(tail):        # interrupted -> don't persist a partial
+                    self._cached_ids = prefix_ids[: len(head) + fed]
+                    return ("partial", len(head))
+                self._cached_ids = list(prefix_ids)
+                self._warm_prefix_ids = list(prefix_ids)
+                self._save_ckpt(path)
+                return ("partial", len(head))
+        # miss: prefill into a fresh cache and persist — the head first (so the NEXT
+        # fresh directory gets a partial hit), then the whole prefix.
         self._reset_cache()
-        fed = self._prefill(list(prefix_ids), should_stop)
-        if fed < len(prefix_ids):          # interrupted -> don't persist a partial
-            self._cached_ids = list(prefix_ids[:fed])
-            return ("miss", fed)
+        if head:
+            fed = self._prefill(head, should_stop)
+            if fed < len(head):
+                self._cached_ids = head[:fed]
+                return ("miss", fed)
+            self._cached_ids = list(head)
+            self._save_ckpt(hp)
+        fed = self._prefill(tail, should_stop)
+        if fed < len(tail):
+            self._cached_ids = prefix_ids[: len(head) + fed]
+            return ("miss", len(head) + fed)
         self._cached_ids = list(prefix_ids)
         self._warm_prefix_ids = list(prefix_ids)
+        self._save_ckpt(path)
+        return ("miss", len(prefix_ids))
+
+    def _load_ckpt(self, path: str, ids: list) -> bool:
+        """Install a KV checkpoint as the live cache for exactly `ids`. False on
+        anything short of a clean load (unreadable, wrong layer count), leaving the
+        caller to recompute."""
+        try:
+            loaded = cache_utils.load_prompt_cache(path)
+        except Exception:
+            return False                   # corrupt/incompatible -> recompute
+        if len(loaded) != self._n_model_layers():
+            return False
+        self._cache = loaded
+        self._cached_ids = list(ids)
+        self._set_cache_flags()
+        return True
+
+    def _save_ckpt(self, path: str) -> None:
+        """Persist the live cache. Best-effort: a full or read-only disk skips the
+        checkpoint, never the turn."""
+        if not self.cache_dir:
+            return
         try:
             os.makedirs(self.cache_dir, exist_ok=True)
             cache_utils.save_prompt_cache(path, self._cache)
             self._enforce_kv_budget(path)
         except Exception:
-            pass                           # disk full / read-only -> just skip persist
-        return ("miss", len(prefix_ids))
+            pass
 
     def _n_model_layers(self) -> int:
         return len(self.model.layers)
@@ -1094,25 +1146,32 @@ class Engine:
     def _reload_warm_prefix(self, target_ids: list) -> int:
         """If a disk checkpoint of the warm system prefix exists and target_ids still
         begins with it, load it into the freshly-reset cache and return its length
-        (tokens we skip re-prefilling). Returns 0 if unavailable/inapplicable."""
+        (tokens we skip re-prefilling). Falls back to the static head checkpoint when
+        the full one is gone (evicted) or unreadable. Returns 0 if neither applies."""
         wp = self._warm_prefix_ids
-        if not (wp and self.cache_dir and len(target_ids) >= len(wp)
+        if (wp and self.cache_dir and len(target_ids) >= len(wp)
                 and target_ids[: len(wp)] == wp):
+            path = self._ckpt_path(wp)
+            if os.path.isfile(path):
+                if self._load_ckpt(path, wp):
+                    return len(wp)
+                self._reset_cache()        # corrupt/incompatible -> clean rebuild
+        return self._reload_warm_head(target_ids)
+
+    def _reload_warm_head(self, target_ids: list) -> int:
+        """Second tier of `_reload_warm_prefix`: the project-independent head (tool
+        schemas + behavioral prompt), when target_ids still begins with it."""
+        hd = getattr(self, "_warm_head_ids", None)
+        if not (hd and self.cache_dir and len(target_ids) >= len(hd)
+                and target_ids[: len(hd)] == hd):
             return 0
-        path = self._ckpt_path(wp)
+        path = self._ckpt_path(hd)
         if not os.path.isfile(path):
             return 0
-        try:
-            loaded = cache_utils.load_prompt_cache(path)
-            if len(loaded) != self._n_model_layers():
-                return 0
-            self._cache = loaded
-            self._cached_ids = list(wp)
-            self._set_cache_flags()
-            return len(wp)
-        except Exception:
-            self._reset_cache()            # corrupt/incompatible -> clean rebuild
-            return 0
+        if self._load_ckpt(path, hd):
+            return len(hd)
+        self._reset_cache()
+        return 0
 
     # -- one-deep cache quarantine -----------------------------
     # A subagent explores in a SEPARATE small context so the main transcript's warm
@@ -1228,6 +1287,9 @@ class Engine:
         protect = {just_written}
         if self._warm_prefix_ids:
             protect.add(self._ckpt_path(self._warm_prefix_ids))
+        hd = getattr(self, "_warm_head_ids", None)
+        if hd:
+            protect.add(self._ckpt_path(hd))
         enforce_cache_budget(self.cache_dir, self.kv_cache_max_bytes, protect)
 
     # -- generation -------------------------------------------------------

{chad_code-2.0.1 → chad_code-2.0.3}/src/chad/prompt.py

@@ -217,12 +217,24 @@ def _dynamic_context() -> list:
     return dynamic
 
 
+def static_system_prompt() -> str:
+    """The part of the system prompt that is byte-identical in every project and every
+    session: the behavioral prompt and the verify-first block. What the chat template
+    renders before it (the tool schemas) is static too, so the rendered prefix up to the
+    end of this text is the same token sequence in every working directory — which is
+    what lets the engine checkpoint it ONCE, globally, instead of once per directory
+    (`Agent._static_head_ids`, `Engine.warm_prefix`)."""
+    return _BASE_PROMPT + _verify_baseline_block()
+
+
 def build_system_prompt() -> str:
     # Cache-boundary trick (from the Claude Code teardown): everything above the
     # boundary is static behavioral text that stays identical across sessions, so the
-    # prefix KV cache reuses it. Volatile per-session context (cwd, project docs) goes
-    # below, where re-prefilling a few hundred tokens is cheap.
-    return (_BASE_PROMPT + _verify_baseline_block() + "\n".join(_dynamic_context()))
+    # prefix KV cache reuses it. Volatile per-session context (cwd, workspace listing,
+    # project docs) goes below, where re-prefilling a few hundred tokens is cheap. The
+    # boundary is load-bearing for the on-disk warm start: the static head above it is
+    # checkpointed once for every project, the full prompt once per project.
+    return static_system_prompt() + "\n".join(_dynamic_context())
 
 
 def _verify_baseline_block() -> str:

{chad_code-2.0.1 → chad_code-2.0.3}/src/chad/serve.py

@@ -37,7 +37,9 @@ forfeits come back:
   return trip re-prefills it. Here the sub-agent's excursion is bracketed by a real
   ``Engine.push_cache``/``pop_cache``, so the main transcript's KV survives it.
 - ``POST /warm`` — the on-disk KV warm-start of the stable system+tools prefix, which
-  a remote client cannot do because the checkpoint lives on the *server's* disk.
+  a remote client cannot do because the checkpoint lives on the *server's* disk. An
+  optional ``head`` (the project-independent part of ``prefix``) lets a client in a
+  fresh directory restore that head and prefill only its per-project tail.
 
 Both are latency, never correctness: a client that doesn't speak them, or a call that
 fails, degrades to the plain remote behavior.
@@ -704,6 +706,12 @@ def _make_handler(state: ServerState) -> type:
             if not isinstance(prefix, list) or not all(
                     isinstance(t, int) and not isinstance(t, bool) for t in prefix):
                 return self._error(400, "prefix must be an array of token ids")
+            # Optional second tier: the project-independent head of `prefix`, so a
+            # client in a fresh directory restores the head and prefills only its tail.
+            head = body.get("head")
+            if head is not None and (not isinstance(head, list) or not all(
+                    isinstance(t, int) and not isinstance(t, bool) for t in head)):
+                return self._error(400, "head must be an array of token ids")
             # Same wall as /completion: warming a prefix that cannot fit is a prefill
             # that cannot fit, and it reaches the allocator the same way.
             _, too_big = admit(len(prefix), 0, state.n_ctx(), state.safe_ctx())
@@ -711,7 +719,8 @@ def _make_handler(state: ServerState) -> type:
                 return self._error(400, too_big)
             state.busy = True
             try:
-                status, fed = state.call(state.eng.warm_prefix, list(prefix))
+                status, fed = state.call(state.eng.warm_prefix, list(prefix),
+                                         head_ids=list(head) if head else None)
             except Exception as e:  # noqa: BLE001 — same: degrade, don't fail a run
                 return self._send_json(200, {"status": "error", "fed": 0,
                                              "error": str(e)})

{chad_code-2.0.1 → chad_code-2.0.3}/src/chad_code.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chad-code
-Version: 2.0.1
+Version: 2.0.3
 Summary: Claude-Code-style coding agent that runs entirely on a 24 GB Apple Silicon Mac (MLX, Qwen3.8-27B)
 License-Expression: MIT
 Project-URL: Repository, https://github.com/nathansutton/chad
@@ -33,11 +33,11 @@ Provides-Extra: speech
 Requires-Dist: sounddevice>=0.5; extra == "speech"
 Dynamic: license-file
 
-# chad: a Claude-Code-style coding agent that fits on a 24 GB MacBook
+# chad: a local Claude-Code-style coding agent for your laptop
 
 [![tests](https://github.com/nathansutton/chad/actions/workflows/tests.yml/badge.svg)](https://github.com/nathansutton/chad/actions/workflows/tests.yml)
 
-<img src="docs/claude-vs-chad.jpg" width="33%" alt="Two staircase newel posts side by side: Claude is a hand-carved wooden horse head, chad is a scuffed plastic toy horse tied on with twine">
+<img src="docs/claude-vs-chad.jpg" width="66%" alt="Two staircase newel posts side by side: Claude is a hand-carved wooden horse head, chad is a scuffed plastic toy horse tied on with twine">
 
 > Claude can do anything, for anyone, anywhere. chad does one thing. 🗿
 > *Coding under supervision.*
@@ -118,7 +118,7 @@ one checkpoint it ships:
   cache, so a follow-up step prefills the ~16 tokens it appended instead of the 5,000 it
   already read: **~0.75 s per step instead of ~50 s**. Any server with prompt caching gets
   the easy case; the work is holding it true across compaction, truncated turns and restarts.
-  The system prefix is checkpointed to disk, so the second session in a project starts warm
+  The system prefix is checkpointed to disk, so the second session anywhere starts warm
   (75.6 s → 5.5 s to the first tool call).
 - **Fused Metal kernels.** Quantized-KV attention, a small-M matmul for speculative verify,
   and a compiled single-token layer step, chosen per machine at load time, no knobs.

{chad_code-2.0.1 → chad_code-2.0.3}/src/chad_code.egg-info/SOURCES.txt

@@ -80,6 +80,7 @@ tests/test_ignore.py
 tests/test_intent.py
 tests/test_levers.py
 tests/test_log_redaction.py
+tests/test_matrix_bench.py
 tests/test_mcp.py
 tests/test_mcp_oauth.py
 tests/test_mlx_fastpath.py
@@ -101,4 +102,5 @@ tests/test_toolcall_dialect.py
 tests/test_toolcall_parse.py
 tests/test_tools.py
 tests/test_tui.py
-tests/test_validate.py
+tests/test_validate.py
+tests/test_warm_prefix_tiers.py