chad-code 2.0.2__tar.gz → 2.1.0__tar.gz

{chad_code-2.0.2/src/chad_code.egg-info → chad_code-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chad-code
-Version: 2.0.2
+Version: 2.1.0
 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
@@ -13,11 +13,12 @@ Classifier: Operating System :: MacOS
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Code Generators
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mlx==0.32.0; sys_platform == "darwin"
+Requires-Dist: mlx!=0.32.1,<=0.32.2,>=0.32.0; sys_platform == "darwin"
 Requires-Dist: mlx-lm<0.32,>=0.31.3; sys_platform == "darwin"
 Requires-Dist: transformers<5.13,>=5.0
 Requires-Dist: jinja2>=3.1
@@ -43,9 +44,13 @@ Dynamic: license-file
 > *Coding under supervision.*
 
 chad is a single-user coding agent that runs entirely on an Apple Silicon Mac via
-[MLX](https://github.com/ml-explore/mlx). One 27B model and no API key. Every other 
-harness assumes a datacenter on the other end of a socket; chad assumes a laptop, 
-and the whole design falls out of that. (Not affiliated with Anthropic.)
+[MLX](https://github.com/ml-explore/mlx). One 27B model and no API key. (Not affiliated
+with Anthropic.)
+
+Plenty of harnesses run local models now, and [pi](https://pi.dev) is a fantastic default
+for the same reason llama.cpp is: it works with everything. I was steering chad in the
+opposite direction. One model and one set of silicon, taken to the max. Swap out your
+`CHAD_MODEL` and it still runs, you just leave the drafter and the kernels behind.
 
 ## Try it
 
@@ -73,32 +78,36 @@ The PyPI package is `chad-code`. Bare `chad` is an unrelated squatted package.
 
 ## Same model, same Mac, stock engine
 
-The question worth answering: what do you gain over pointing a generic local-model tool at
-the same weights? Qwen3.8-27B at the same `UD-Q3_K_XL` recipe (Unsloth's GGUF for
+What do you gain over pointing a generic local-model tool at the same weights?
+Qwen3.8-27B at the same `UD-Q3_K_XL` recipe (Unsloth's GGUF for
 llama.cpp, chad's MLX conversion of the same bit map), the same M4 Pro (24 GB), one engine
 resident at a time, each measured with its own benchmark on a 512-token prompt and a
 128-token generation.
 
 | Engine | Prefill (512-tok prompt) | Decode (128 tok) | Speculative decoding |
 |---|---|---|---|
-| llama.cpp `llama-bench` (stock, build 10470) | 102 tok/s | 10.9 tok/s | none for this model |
-| **chad**, serial (`CHAD_NO_DFLASH=1`) | 99 tok/s | 18.1 tok/s | off |
-| **chad**, default | 98 tok/s | **62 tok/s**¹ | DFlash2 block drafter |
+| llama.cpp `llama-bench` (stock, build 10470) | 102 tok/s | 10.9 tok/s | off in this benchmark |
+| llama.cpp `llama-server` (build 10917), serial | 97 tok/s | 11.3 tok/s | off |
+| llama.cpp `llama-server` (build 10917) | 95 tok/s | 11.1 tok/s² | DFlash2 drafter (Q4_K_M GGUF) |
+| **chad**, serial (`CHAD_NO_DFLASH=1`) | 100 tok/s | 17.9 tok/s | off |
+| **chad**, default | 101 tok/s | **62.9 tok/s**¹ | DFlash2 block drafter |
 
-A 200-token function body takes roughly 18 seconds at 10.9 tok/s and 3 at 62. That is the
-difference between a batch job and a pair programmer, and closing it is what the project is
-for.
+A 200-token function body takes roughly 18 seconds at 10.9 tok/s and 3 at 63. You wait for
+the first one and you talk to the second.
 
-Ollama does not get its own row: it is llama.cpp underneath with no speculative decoding for
-this model, and on the same GGUF (0.32.15, Modelfile `FROM` only) it measures 96 tok/s
+Ollama does not get its own row: it is llama.cpp underneath, measured without speculative
+decoding, and on the same GGUF (0.32.15, Modelfile `FROM` only) it measures 96 tok/s
 prefill and the same **10.9** decode.
 
-¹ 62 is a ceiling: `chad-bench`'s prompt is tiled code the drafter reads easily. Replayed
-against ten real mid-session contexts from `~/.chad/sessions` (12–19k tokens, tool results in
+¹ 63 is a ceiling: `chad-bench`'s prompt is tiled code the drafter reads easily. Replayed
+against ten real mid-session contexts from `~/.chad/sessions` (12-19k tokens, tool results in
 place, 384-token decodes) the same engine measures **31.7 tok/s median / 21.4 floor** greedy
 against 14.8 serial, and **27.6 / 17.7** thinking against 13.9. That ~2× is what a session
-lives at. llama.cpp's Metal path for this hybrid architecture was not profiled, so read its
-row as what a fitted engine buys, not as a verdict on llama.cpp.
+lives at.
+
+² llama.cpp has run DFlash2 since build 10658. Here it accepts 96.5% of drafted tokens and still
+gains nothing: verifying 8 tokens costs ~6.4 serial steps on this GGUF and Mac
+([details](docs/benchmarks.md#same-model-same-mac-stock-engine)).
 
 Method, the longer runs and the caveats are in
 [Throughput & performance](docs/benchmarks.md#same-model-same-mac-stock-engine); the rows are
@@ -110,17 +119,17 @@ committed under [`benchmarks/stock/_runs/`](benchmarks/stock/); reproduce them w
 chad owns its inference loop instead of talking to a server, and the engine is fitted to the
 one checkpoint it ships:
 
-- **DFlash2 block speculation.** A bundled 1.9B drafter ([z-lab's DFlash2](https://huggingface.co/z-lab/Qwen3.8-27B-DFlash2),
+- DFlash2 block speculation. A bundled 1.9B drafter ([z-lab's DFlash2](https://huggingface.co/z-lab/Qwen3.8-27B-DFlash2),
   ported to MLX and quantized) proposes a whole block of tokens from the main model's own
   hidden states. The main model verifies the block in one batched forward, and exact
   rejection sampling keeps every emitted token the model's own.
-- **A persistent prefix KV cache.** The transcript is kept a strict token-prefix of the live
+- A persistent prefix KV cache. The transcript is kept a strict token-prefix of the live
   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
+  already read: **~0.55 s per step instead of ~48 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,
+- 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.
 
 ## What chad gives up
@@ -146,16 +155,21 @@ budget; everything else is deliberately plain.
 
 `uv run chad` launches a full-screen terminal UI (built on prompt_toolkit):
 
-- **shift-tab cycles permission modes**: `normal` (confirm each bash/write/edit) →
+- shift-tab cycles permission modes: `normal` (confirm each bash/write/edit) →
   `auto-accept edits` (edits land silently, **terminal commands still ask**) → `yolo`
   (nothing asks) → `plan mode` (read-only: investigate and propose a numbered plan) → back.
-- **type-ahead message queue.** Keep typing while the agent works; messages run in order.
-- **ctrl-c interrupts the running turn** without killing the session. **↑prefilled /
+  A finished plan lands in `./plans/`; ctrl-g (or `/accept`) clears the context and starts
+  implementing it ([details](docs/configuration.md#plan-mode)).
+- Type-ahead message queue. Keep typing while the agent works; messages run in order.
+- ctrl-c interrupts the running turn without killing the session. **↑prefilled /
   ↓generated** token counts show an advancing **%** on an unavoidable full re-prefill, so it
   is never silent.
-- **`@file` / `@dir` mentions** and **`!command` shell passthrough.** Pull a file into
+- `@file` / `@dir` mentions and `!command` shell passthrough. Pull a file into
   context inline, or run a shell command without invoking the model.
-- **voice mode, all local.** `/speech`, then ctrl-t to talk: Parakeet-on-MLX transcribes into
+- Standing project instructions. A `CLAUDE.md` (or `AGENTS.md`) in the working directory is
+  appended to the system prompt, and `/init` reads the project and writes one for you
+  ([details](docs/configuration.md#project-instructions-claudemd--agentsmd)).
+- Voice mode, all local. `/speech`, then ctrl-t to talk: Parakeet-on-MLX transcribes into
   the input box for you to review before Enter sends it, and replies are read aloud via macOS
   `say`. A word table teaches it your identifiers. Needs the `speech` extra
   ([details](docs/configuration.md#voice-mode-speech)).
@@ -169,12 +183,13 @@ budget; everything else is deliberately plain.
 | `--plan` | start in read-only plan mode (investigate and propose, edits blocked) |
 | `--yolo` | auto-approve bash/write/edit (skip confirm prompts) |
 | `--no-think` | skip the model's `<think>` blocks, faster on well-scoped work |
+| `--think-budget N` | soft-cap each step's `<think>` at N tokens, force-close it and carry on (off by default) |
+| `--backend llama` | run the same harness against a remote llama.cpp server, with `--base-url`, `--tokenizer` and `--api-key-env` ([details](docs/configuration.md#alternate-backend-remote)) |
 | `--model` | `auto` (the shipped default), or any HF repo id / local model dir |
 | `--repl` | plain line REPL instead of the TUI |
 
-Three subcommands, each with its own `--help`: `chad prove` (the offline smoke test),
-`chad serve` ([serve this Mac's model to a container or the LAN](docs/configuration.md#serving-the-local-model-to-a-container-chad-serve)),
-and `chad levers` (print the result-channel lever registry as JSON, for A/B ablation).
+Two subcommands, each with its own `--help`: `chad prove` (the offline smoke test) and
+`chad levers` (print the result-channel lever registry as JSON, for A/B ablation).
 
 A headless task (positional, or piped with no TTY) auto-approves mutating tools and runs
 greedy (temp 0). Every conversation is persisted under `~/.chad/sessions/`, and every resume
@@ -220,7 +235,7 @@ uv run chad "add a --json flag to main.py and update the tests"   # one-shot, he
 uv run chad -c               # resume this directory's last conversation
 ```
 
-**Optional extras.** Two features are opt-in because they pull deps not every install wants:
+Two features are opt-in because they pull deps not every install wants:
 `speech` (voice mode: a mic library, no torch) and `highlight` (syntax colour in diffs and
 previews). An extra rides on the install spec, not on a separate command, so how you add it
 depends on how you installed chad:
@@ -234,12 +249,12 @@ uv sync --extra speech                        # from a clone
 `/speech` in the TUI prints whichever of those matches your install, so you never have to
 work it out from here.
 
-**Upgrading** depends on how you installed: `uv tool upgrade chad-code`, `uvx --refresh
+Upgrading depends on how you installed: `uv tool upgrade chad-code`, `uvx --refresh
 chad-code`, or `git pull && uv sync` for a clone. What changed lands in
 [`CHANGELOG.md`](CHANGELOG.md). Model weights are versioned separately, so a code upgrade
 never re-downloads the model.
 
-**Development.** `uv sync` once, then `uv run pytest -q`. The fast unit gate loads **no model
+For development, `uv sync` once, then `uv run pytest -q`. The fast unit gate loads **no model
 weights**, runs in seconds, and is what CI runs. For throughput on your own machine, use
 `uv run chad-bench` (see [Throughput & performance](docs/benchmarks.md)).
 
@@ -247,11 +262,12 @@ weights**, runs in seconds, and is what CI runs. For throughput on your own mach
 
 chad speaks the same two extension formats as Claude Code:
 
-- **[Agent Skills](https://agentskills.io).** Drop a `SKILL.md` folder in
-  `./.claude/skills/` and it becomes a slash command: `/ship`, `/investigate the flaky test`.
-  Skills cost nothing until you run one, because chad puts no skill catalog in the system
-  prompt.
-- **[MCP servers](https://modelcontextprotocol.io).** Configure stdio or HTTP servers in
+- [Agent Skills](https://agentskills.io). Drop a `SKILL.md` folder in `./.agents/skills/`
+  or `./.claude/skills/` (or under `~/` for every project) and it becomes a slash command:
+  `/ship`, `/investigate the flaky test`. Skills cost nothing until you run one, because
+  chad puts no skill catalog in the system prompt. Precedence and the full list of roots
+  are in the [Configuration reference](docs/configuration.md#agent-skills-agentskillsio).
+- [MCP servers](https://modelcontextprotocol.io). Configure stdio or HTTP servers in
   `./.mcp.json` to expose external tools (GitHub, Postgres, Linear, Slack, …) alongside
   chad's builtins, with static-token and OAuth auth.
 
@@ -259,16 +275,17 @@ Both are covered in full in the [Configuration reference](docs/configuration.md)
 
 ## Documentation
 
-- **[Design & internals](docs/design.md)** covers why prefill is the bill, the persistent
+- [Design & internals](docs/design.md) covers why prefill is the bill, the persistent
   prefix cache, the trimmable/append-only trade, why the tool surface is five tools, and the
   ideas borrowed from other agents.
-- **[Throughput & performance](docs/benchmarks.md)** has the prefill, decode and warm-step
+- [Throughput & performance](docs/benchmarks.md) has the prefill, decode and warm-step
   numbers you can reproduce with `chad-bench`, the stock-engine comparison, and what the
   cross-session warm start is worth.
-- **[Configuration reference](docs/configuration.md)** documents Agent Skills, MCP servers,
-  the context window, every environment variable, and the safety opt-outs.
-- **[Troubleshooting](docs/troubleshooting.md)** is the symptom→knob map for when a session
+- [Configuration reference](docs/configuration.md) documents project instructions, Agent
+  Skills, MCP servers, plan mode, the slash commands, the context window, every environment
+  variable, and the safety opt-outs.
+- [Troubleshooting](docs/troubleshooting.md) maps symptoms to knobs for when a session
   rambles, loops, or slows.
-- **[Contributing](CONTRIBUTING.md)** says what lands easily and what needs a conversation
+- [Contributing](CONTRIBUTING.md) says what lands easily and what needs a conversation
   first.
 

{chad_code-2.0.2 → chad_code-2.1.0}/README.md

@@ -8,9 +8,13 @@
 > *Coding under supervision.*
 
 chad is a single-user coding agent that runs entirely on an Apple Silicon Mac via
-[MLX](https://github.com/ml-explore/mlx). One 27B model and no API key. Every other 
-harness assumes a datacenter on the other end of a socket; chad assumes a laptop, 
-and the whole design falls out of that. (Not affiliated with Anthropic.)
+[MLX](https://github.com/ml-explore/mlx). One 27B model and no API key. (Not affiliated
+with Anthropic.)
+
+Plenty of harnesses run local models now, and [pi](https://pi.dev) is a fantastic default
+for the same reason llama.cpp is: it works with everything. I was steering chad in the
+opposite direction. One model and one set of silicon, taken to the max. Swap out your
+`CHAD_MODEL` and it still runs, you just leave the drafter and the kernels behind.
 
 ## Try it
 
@@ -38,32 +42,36 @@ The PyPI package is `chad-code`. Bare `chad` is an unrelated squatted package.
 
 ## Same model, same Mac, stock engine
 
-The question worth answering: what do you gain over pointing a generic local-model tool at
-the same weights? Qwen3.8-27B at the same `UD-Q3_K_XL` recipe (Unsloth's GGUF for
+What do you gain over pointing a generic local-model tool at the same weights?
+Qwen3.8-27B at the same `UD-Q3_K_XL` recipe (Unsloth's GGUF for
 llama.cpp, chad's MLX conversion of the same bit map), the same M4 Pro (24 GB), one engine
 resident at a time, each measured with its own benchmark on a 512-token prompt and a
 128-token generation.
 
 | Engine | Prefill (512-tok prompt) | Decode (128 tok) | Speculative decoding |
 |---|---|---|---|
-| llama.cpp `llama-bench` (stock, build 10470) | 102 tok/s | 10.9 tok/s | none for this model |
-| **chad**, serial (`CHAD_NO_DFLASH=1`) | 99 tok/s | 18.1 tok/s | off |
-| **chad**, default | 98 tok/s | **62 tok/s**¹ | DFlash2 block drafter |
+| llama.cpp `llama-bench` (stock, build 10470) | 102 tok/s | 10.9 tok/s | off in this benchmark |
+| llama.cpp `llama-server` (build 10917), serial | 97 tok/s | 11.3 tok/s | off |
+| llama.cpp `llama-server` (build 10917) | 95 tok/s | 11.1 tok/s² | DFlash2 drafter (Q4_K_M GGUF) |
+| **chad**, serial (`CHAD_NO_DFLASH=1`) | 100 tok/s | 17.9 tok/s | off |
+| **chad**, default | 101 tok/s | **62.9 tok/s**¹ | DFlash2 block drafter |
 
-A 200-token function body takes roughly 18 seconds at 10.9 tok/s and 3 at 62. That is the
-difference between a batch job and a pair programmer, and closing it is what the project is
-for.
+A 200-token function body takes roughly 18 seconds at 10.9 tok/s and 3 at 63. You wait for
+the first one and you talk to the second.
 
-Ollama does not get its own row: it is llama.cpp underneath with no speculative decoding for
-this model, and on the same GGUF (0.32.15, Modelfile `FROM` only) it measures 96 tok/s
+Ollama does not get its own row: it is llama.cpp underneath, measured without speculative
+decoding, and on the same GGUF (0.32.15, Modelfile `FROM` only) it measures 96 tok/s
 prefill and the same **10.9** decode.
 
-¹ 62 is a ceiling: `chad-bench`'s prompt is tiled code the drafter reads easily. Replayed
-against ten real mid-session contexts from `~/.chad/sessions` (12–19k tokens, tool results in
+¹ 63 is a ceiling: `chad-bench`'s prompt is tiled code the drafter reads easily. Replayed
+against ten real mid-session contexts from `~/.chad/sessions` (12-19k tokens, tool results in
 place, 384-token decodes) the same engine measures **31.7 tok/s median / 21.4 floor** greedy
 against 14.8 serial, and **27.6 / 17.7** thinking against 13.9. That ~2× is what a session
-lives at. llama.cpp's Metal path for this hybrid architecture was not profiled, so read its
-row as what a fitted engine buys, not as a verdict on llama.cpp.
+lives at.
+
+² llama.cpp has run DFlash2 since build 10658. Here it accepts 96.5% of drafted tokens and still
+gains nothing: verifying 8 tokens costs ~6.4 serial steps on this GGUF and Mac
+([details](docs/benchmarks.md#same-model-same-mac-stock-engine)).
 
 Method, the longer runs and the caveats are in
 [Throughput & performance](docs/benchmarks.md#same-model-same-mac-stock-engine); the rows are
@@ -75,17 +83,17 @@ committed under [`benchmarks/stock/_runs/`](benchmarks/stock/); reproduce them w
 chad owns its inference loop instead of talking to a server, and the engine is fitted to the
 one checkpoint it ships:
 
-- **DFlash2 block speculation.** A bundled 1.9B drafter ([z-lab's DFlash2](https://huggingface.co/z-lab/Qwen3.8-27B-DFlash2),
+- DFlash2 block speculation. A bundled 1.9B drafter ([z-lab's DFlash2](https://huggingface.co/z-lab/Qwen3.8-27B-DFlash2),
   ported to MLX and quantized) proposes a whole block of tokens from the main model's own
   hidden states. The main model verifies the block in one batched forward, and exact
   rejection sampling keeps every emitted token the model's own.
-- **A persistent prefix KV cache.** The transcript is kept a strict token-prefix of the live
+- A persistent prefix KV cache. The transcript is kept a strict token-prefix of the live
   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
+  already read: **~0.55 s per step instead of ~48 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,
+- 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.
 
 ## What chad gives up
@@ -111,16 +119,21 @@ budget; everything else is deliberately plain.
 
 `uv run chad` launches a full-screen terminal UI (built on prompt_toolkit):
 
-- **shift-tab cycles permission modes**: `normal` (confirm each bash/write/edit) →
+- shift-tab cycles permission modes: `normal` (confirm each bash/write/edit) →
   `auto-accept edits` (edits land silently, **terminal commands still ask**) → `yolo`
   (nothing asks) → `plan mode` (read-only: investigate and propose a numbered plan) → back.
-- **type-ahead message queue.** Keep typing while the agent works; messages run in order.
-- **ctrl-c interrupts the running turn** without killing the session. **↑prefilled /
+  A finished plan lands in `./plans/`; ctrl-g (or `/accept`) clears the context and starts
+  implementing it ([details](docs/configuration.md#plan-mode)).
+- Type-ahead message queue. Keep typing while the agent works; messages run in order.
+- ctrl-c interrupts the running turn without killing the session. **↑prefilled /
   ↓generated** token counts show an advancing **%** on an unavoidable full re-prefill, so it
   is never silent.
-- **`@file` / `@dir` mentions** and **`!command` shell passthrough.** Pull a file into
+- `@file` / `@dir` mentions and `!command` shell passthrough. Pull a file into
   context inline, or run a shell command without invoking the model.
-- **voice mode, all local.** `/speech`, then ctrl-t to talk: Parakeet-on-MLX transcribes into
+- Standing project instructions. A `CLAUDE.md` (or `AGENTS.md`) in the working directory is
+  appended to the system prompt, and `/init` reads the project and writes one for you
+  ([details](docs/configuration.md#project-instructions-claudemd--agentsmd)).
+- Voice mode, all local. `/speech`, then ctrl-t to talk: Parakeet-on-MLX transcribes into
   the input box for you to review before Enter sends it, and replies are read aloud via macOS
   `say`. A word table teaches it your identifiers. Needs the `speech` extra
   ([details](docs/configuration.md#voice-mode-speech)).
@@ -134,12 +147,13 @@ budget; everything else is deliberately plain.
 | `--plan` | start in read-only plan mode (investigate and propose, edits blocked) |
 | `--yolo` | auto-approve bash/write/edit (skip confirm prompts) |
 | `--no-think` | skip the model's `<think>` blocks, faster on well-scoped work |
+| `--think-budget N` | soft-cap each step's `<think>` at N tokens, force-close it and carry on (off by default) |
+| `--backend llama` | run the same harness against a remote llama.cpp server, with `--base-url`, `--tokenizer` and `--api-key-env` ([details](docs/configuration.md#alternate-backend-remote)) |
 | `--model` | `auto` (the shipped default), or any HF repo id / local model dir |
 | `--repl` | plain line REPL instead of the TUI |
 
-Three subcommands, each with its own `--help`: `chad prove` (the offline smoke test),
-`chad serve` ([serve this Mac's model to a container or the LAN](docs/configuration.md#serving-the-local-model-to-a-container-chad-serve)),
-and `chad levers` (print the result-channel lever registry as JSON, for A/B ablation).
+Two subcommands, each with its own `--help`: `chad prove` (the offline smoke test) and
+`chad levers` (print the result-channel lever registry as JSON, for A/B ablation).
 
 A headless task (positional, or piped with no TTY) auto-approves mutating tools and runs
 greedy (temp 0). Every conversation is persisted under `~/.chad/sessions/`, and every resume
@@ -185,7 +199,7 @@ uv run chad "add a --json flag to main.py and update the tests"   # one-shot, he
 uv run chad -c               # resume this directory's last conversation
 ```
 
-**Optional extras.** Two features are opt-in because they pull deps not every install wants:
+Two features are opt-in because they pull deps not every install wants:
 `speech` (voice mode: a mic library, no torch) and `highlight` (syntax colour in diffs and
 previews). An extra rides on the install spec, not on a separate command, so how you add it
 depends on how you installed chad:
@@ -199,12 +213,12 @@ uv sync --extra speech                        # from a clone
 `/speech` in the TUI prints whichever of those matches your install, so you never have to
 work it out from here.
 
-**Upgrading** depends on how you installed: `uv tool upgrade chad-code`, `uvx --refresh
+Upgrading depends on how you installed: `uv tool upgrade chad-code`, `uvx --refresh
 chad-code`, or `git pull && uv sync` for a clone. What changed lands in
 [`CHANGELOG.md`](CHANGELOG.md). Model weights are versioned separately, so a code upgrade
 never re-downloads the model.
 
-**Development.** `uv sync` once, then `uv run pytest -q`. The fast unit gate loads **no model
+For development, `uv sync` once, then `uv run pytest -q`. The fast unit gate loads **no model
 weights**, runs in seconds, and is what CI runs. For throughput on your own machine, use
 `uv run chad-bench` (see [Throughput & performance](docs/benchmarks.md)).
 
@@ -212,11 +226,12 @@ weights**, runs in seconds, and is what CI runs. For throughput on your own mach
 
 chad speaks the same two extension formats as Claude Code:
 
-- **[Agent Skills](https://agentskills.io).** Drop a `SKILL.md` folder in
-  `./.claude/skills/` and it becomes a slash command: `/ship`, `/investigate the flaky test`.
-  Skills cost nothing until you run one, because chad puts no skill catalog in the system
-  prompt.
-- **[MCP servers](https://modelcontextprotocol.io).** Configure stdio or HTTP servers in
+- [Agent Skills](https://agentskills.io). Drop a `SKILL.md` folder in `./.agents/skills/`
+  or `./.claude/skills/` (or under `~/` for every project) and it becomes a slash command:
+  `/ship`, `/investigate the flaky test`. Skills cost nothing until you run one, because
+  chad puts no skill catalog in the system prompt. Precedence and the full list of roots
+  are in the [Configuration reference](docs/configuration.md#agent-skills-agentskillsio).
+- [MCP servers](https://modelcontextprotocol.io). Configure stdio or HTTP servers in
   `./.mcp.json` to expose external tools (GitHub, Postgres, Linear, Slack, …) alongside
   chad's builtins, with static-token and OAuth auth.
 
@@ -224,16 +239,17 @@ Both are covered in full in the [Configuration reference](docs/configuration.md)
 
 ## Documentation
 
-- **[Design & internals](docs/design.md)** covers why prefill is the bill, the persistent
+- [Design & internals](docs/design.md) covers why prefill is the bill, the persistent
   prefix cache, the trimmable/append-only trade, why the tool surface is five tools, and the
   ideas borrowed from other agents.
-- **[Throughput & performance](docs/benchmarks.md)** has the prefill, decode and warm-step
+- [Throughput & performance](docs/benchmarks.md) has the prefill, decode and warm-step
   numbers you can reproduce with `chad-bench`, the stock-engine comparison, and what the
   cross-session warm start is worth.
-- **[Configuration reference](docs/configuration.md)** documents Agent Skills, MCP servers,
-  the context window, every environment variable, and the safety opt-outs.
-- **[Troubleshooting](docs/troubleshooting.md)** is the symptom→knob map for when a session
+- [Configuration reference](docs/configuration.md) documents project instructions, Agent
+  Skills, MCP servers, plan mode, the slash commands, the context window, every environment
+  variable, and the safety opt-outs.
+- [Troubleshooting](docs/troubleshooting.md) maps symptoms to knobs for when a session
   rambles, loops, or slows.
-- **[Contributing](CONTRIBUTING.md)** says what lands easily and what needs a conversation
+- [Contributing](CONTRIBUTING.md) says what lands easily and what needs a conversation
   first.
 

{chad_code-2.0.2 → chad_code-2.1.0}/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.2"
+version = "2.1.0"
 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"
@@ -23,6 +23,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Code Generators",
 ]
 dependencies = [
@@ -42,7 +43,11 @@ dependencies = [
     # A/B-confirmed 2026-08-23: same wheel, same prompt, sane on ==0.32.0, garbled on
     # ==0.32.1). Point releases must be re-gated against the custom QSDPA/DFlash2/MMA
     # kernels before widening this pin.
-    "mlx==0.32.0; sys_platform == 'darwin'",
+    # mlx 0.32.2: re-gated and admitted — greedy output byte-identical to 0.32.0 on the
+    # shipped model, `chad prove` 4/4, full suite green, decode within noise (M4 Pro;
+    # independently on M5 Pro, #50). The range admits only gated releases; the upper
+    # bound moves when the next point release is gated, not before.
+    "mlx>=0.32.0,!=0.32.1,<=0.32.2; sys_platform == 'darwin'",
     "mlx-lm>=0.31.3,<0.32; sys_platform == 'darwin'",
     # mlx-lm requires transformers>=5.0, but 5.13.0 regressed AutoTokenizer.register:
     # it now does `key.__module__.startswith("transformers.")` with no hasattr guard, and
@@ -138,6 +143,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", "tools/anti_slop"]  # vendored linter: not chad's style
 src = ["src", "tests"]
 
 [tool.ruff.lint]
@@ -192,3 +199,51 @@ ignore_errors = true
 # that is likewise Any on Linux.
 module = ["chad.mlx_fastpath", "chad.mlx_qmm_mma", "chad.engine"]
 warn_unused_ignores = false
+
+# anti-slop: the third lane of the gate, next to ruff (style/correctness) and mypy
+# (types). It rejects the evidence-discarding patterns a coding agent reaches for when a
+# checker complains — `Any`/`object` contracts, unexplained `cast`/`# type: ignore`,
+# string-target mocking, `getattr` dispatch — which ruff and mypy both permit by
+# construction. Vendored (tools/anti_slop, MIT, TinyFrontier/anti-slop-py) so it needs
+# no dependency and runs on the stdlib alone; it does need Python 3.12+, so `make slop`
+# runs it under `uv run --python 3.12` regardless of the 3.11 project pin.
+# Run `uv run --python 3.12 --no-project python tools/anti_slop --explain <rule>` for
+# the reasoning behind any finding.
+[tool.anti-slop]
+include = ["src", "tests", "benchmarks"]
+exclude = [
+    ".agents/**",
+    ".claude/**",
+    "src/chad/parakeet/**",          # vendored upstream, not held to chad's gate (see ruff/mypy)
+    "benchmarks/matrix/tasks/**",    # vendored Exercism exercises, kept byte-identical
+    "tools/anti_slop/**",
+]
+# Pre-existing findings live in the baseline (regenerate: `make slop-baseline`). A run
+# fails only on what is NEW; edit a baselined line and its finding comes back, so the
+# debt retires as the code it sits on is touched. Never regenerate to hide a new finding.
+baseline = ".anti-slop-baseline.json"
+
+[tool.anti-slop.rules]
+# Escape-hatch tier: every one at error. These discard evidence the checker already had.
+no-any-parameters = "error"
+no-any-returns = "error"
+no-any-type-aliases = "error"
+no-chained-casts = "error"
+no-conditional-empty-dict-spread = "error"
+no-dynamic-dispatch = "error"
+no-known-value-widening = "error"
+no-unsafe-dict-values = "error"
+no-widen-then-cast = "error"
+require-safety-comment = "error"
+# Architectural tier: policy, also at error, with the two exceptions below.
+no-object-parameters = "error"
+no-string-attribute-access = "error"
+no-module-mocking = "error"
+# chad's domain objects ARE untyped model output: tool args arrive as JSON the model
+# wrote, and validate.py/mcp.py decode them at that boundary with isinstance — which is
+# the recipe this rule prescribes, not the pattern it bans (the linter's own repository
+# turns it off for the same reason over ast nodes). Kept at warn so a new inline
+# isinstance deep in agent code still reports, without failing the run.
+no-adhoc-isinstance = "warn"
+# Tensor shapes are domain vocabulary in the MLX kernel modules; `shape` names the thing.
+no-shape-in-symbol-names = { level = "error", terms = [] }

{chad_code-2.0.2 → chad_code-2.1.0}/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.2"
+__version__ = "2.1.0"
 
 # 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