@nzkbuild/toche 1.0.9

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Toche Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,18 @@
+Toche
+Copyright 2026 Toche Contributors
+
+This product includes software developed by:
+
+- rtk-ai (https://github.com/rtk-ai/rtk) — Apache-2.0
+  Copyright 2024 rtk-ai and rtk-ai Labs
+
+- ryoppippi (https://github.com/ccusage/ccusage) — MIT
+  Copyright (c) 2025 ryoppippi
+
+- Safi Shamsi (https://github.com/Graphify-Labs/graphify) — MIT
+  Copyright (c) 2026 Safi Shamsi
+
+- Julius Brussee (https://github.com/juliusbrussee/caveman) — MIT
+  Copyright (c) 2026 Julius Brussee
+
+- multica-ai (https://github.com/multica-ai/andrej-karpathy-skills) — MIT

package/README.md

@@ -0,0 +1,367 @@
+<p align="center">
+  <img src="assets/branding/toche-wordmark.png" alt="Toche" width="620">
+</p>
+
+<p align="center">
+  <strong>Claude Code repeats less, carries less noise, and leaves you a receipt.</strong>
+</p>
+
+<p align="center">
+  Toche is a local gateway between Claude Code and your Anthropic API endpoint.
+  It removes avoidable work while keeping every optimization visible and reversible.
+</p>
+
+<p align="center">
+  <img src="assets/branding/toche-status.svg" alt="Toche 1.0.9: 65 filters, duplicate requests coalesced from many to one, zero hosted accounts, 354 Rust tests" width="820">
+</p>
+
+<p align="center">
+  <a href="#why-toche">Why Toche</a> ·
+  <a href="#what-changes">What changes</a> ·
+  <a href="#install">Install</a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="#command-reference">Commands</a> ·
+  <a href="#safety-and-control">Safety</a> ·
+  <a href="#documentation">Docs</a>
+</p>
+
+## Why Toche
+
+Claude Code sessions often pay for the same kind of waste more than once: an
+identical request is already running, a safe response was just fetched, or a tool
+prints thousands of tokens when the useful result is a few lines. Toche handles
+those cases before they consume another upstream call or more conversation space.
+
+The useful part is not a universal marketing percentage. Toche measures your
+actual traffic and reports what happened with `toche stats`.
+
+## What changes
+
+- **Three identical requests at the same time can become one upstream call.** The
+  first request runs while the other two wait for and share its response.
+- **An eligible local replay becomes zero new upstream calls.** Toche only replays
+  workspace-matched, text-only responses that pass its safety checks.
+- **Sixty-five command filters remove known noise.** Cargo, Git, Terraform, Helm,
+  Ansible, linters, and other supported output can be shortened while the original
+  remains recoverable with `toche expand`.
+- **Every routed request leaves a local record.** Token counts, estimated cost,
+  latency, cache decisions, coalescing, and reduction are written to a local SQLite
+  ledger instead of a Toche cloud account.
+
+Here is a deliberately simple example. If a supported tool prints an estimated
+10,000 tokens and its useful reduced form is 3,000, the ledger records 7,000 tokens
+removed, or 70%. That explains the measurement. It does not promise that every
+command, repository, or session will save 70%.
+
+Toche is most useful during long coding sessions, repeated test and diff cycles,
+parallel agent work, and projects where you want to inspect the cost of the work.
+A short conversation with no repetition or noisy tools may show little difference.
+
+## Install
+
+### Before you start
+
+You need:
+
+1. Claude Code installed and already working.
+2. Node.js 18 or newer for the npm installer.
+3. Windows x64, Linux x64, macOS Intel, or macOS Apple silicon.
+
+Rust is not required when installing from npm.
+
+### One-time setup
+
+1. Install Toche globally. This makes the `toche` command available anywhere.
+
+   ```shell
+   npm install -g @nzkbuild/toche
+   ```
+
+2. Import your existing Claude Code endpoint into a local Toche profile.
+
+   ```shell
+   toche setup
+   ```
+
+3. Start Toche and leave this terminal open while using Claude Code.
+
+   ```shell
+   toche
+   ```
+
+4. Open a second terminal, connect Claude Code, and verify the setup.
+
+   ```shell
+   toche connect
+   toche doctor
+   ```
+
+5. Start Claude Code normally.
+
+   ```shell
+   claude
+   ```
+
+`toche connect` creates a backup before changing Claude Code's local routing.
+
+### Normal daily use
+
+After the one-time setup, the routine is only:
+
+1. Run `toche` and leave it open.
+2. Run `claude` in another terminal.
+
+You do not need to run `setup` again. You also do not need to run `connect` again
+unless you previously used `toche disconnect`.
+
+### Use these only when needed
+
+| Command | When to use it |
+|---|---|
+| `toche stats` | You want to see requests, tokens, estimated cost, and measured savings |
+| `toche doctor` | Something is not connecting or you want a health check |
+| `toche disconnect` | You want Claude Code to bypass Toche and use its original endpoint |
+| `toche setup --force` | You intentionally want to replace the current Toche profile; a backup is created |
+
+To uninstall cleanly, restore Claude Code's original route first:
+
+```shell
+toche disconnect
+npm uninstall -g @nzkbuild/toche
+```
+
+<details>
+<summary><strong>Build from source instead of npm</strong></summary>
+
+You need Rust 1.86 or newer.
+
+```shell
+git clone https://github.com/nzkbuild/toche.git
+cd toche
+cargo build --release
+```
+
+The binary is `target/release/toche` on Linux and macOS or
+`target\release\toche.exe` on Windows. Run that binary with the same numbered setup
+steps above.
+
+</details>
+
+## How it works
+
+```mermaid
+flowchart LR
+    A[Claude Code] --> B[Toche on 127.0.0.1:8743]
+    B --> C{Local pipeline}
+    C --> D[Shield and safe cache]
+    C --> E[Output reduction]
+    C --> F[Efficiency and prompt cache]
+    D --> G[Configured Anthropic API endpoint]
+    E --> G
+    F --> G
+    G --> B
+    B --> H[Local ledger and content store]
+    B --> A
+```
+
+In plain language, Claude Code sends its normal Anthropic Messages API request to
+Toche on `127.0.0.1:8743`. Toche then:
+
+1. Gives the request a stable fingerprint.
+2. Shares an already-running identical request or checks for an eligible local replay.
+3. Shortens supported tool output and keeps the original locally recoverable.
+4. Applies the selected efficiency and provider prompt-cache policy.
+5. Forwards any remaining work to your configured Anthropic API endpoint.
+6. Records the outcome locally so `toche stats` can explain it.
+
+The exact internal order is:
+
+```text
+fingerprint -> shield -> safe cache -> reduce -> efficiency -> cache -> forward -> ledger
+```
+
+Toche fingerprints the canonical request, checks whether work can be safely shared
+or replayed, reduces known tool-output noise, applies the selected efficiency and
+prompt-cache policy, forwards the resulting request upstream, then records the
+outcome locally.
+
+For the module map, database schema, cache rules, and content-addressed storage
+layout, see [the architecture guide](docs/ARCHITECTURE.md).
+
+## Safety and control
+
+- The gateway binds to `127.0.0.1:8743` by default.
+- Toche configuration, its ledger, cache metadata, checkpoints, and stored content live locally.
+- Requests that require upstream work still go to the Anthropic API endpoint configured in your profile.
+- Persistent replay is limited to eligible responses. Responses containing `tool_use` blocks are rejected.
+- `toche doctor` reports configuration and integration health.
+- Every optimization stage has an explicit bypass header.
+- `toche expand <hash>` restores original tool output after reduction.
+- Cache entries can be inspected, explained, and cleared.
+- `toche disconnect` restores direct Claude Code routing.
+
+These controls make Toche inspectable and reversible. They are not a promise that
+every request will be cheaper or that an optimization can never affect model behavior.
+
+## Command reference
+
+<details>
+<summary><strong>Gateway, setup, and diagnostics</strong></summary>
+
+| Command | What it does |
+|---|---|
+| `toche` | Start the gateway on `127.0.0.1:8743` |
+| `toche setup` | Generate `profiles.toml` from Claude Code configuration |
+| `toche setup --force` | Regenerate the profile and back up the existing file |
+| `toche connect` | Route Claude Code through Toche |
+| `toche disconnect` | Restore direct upstream routing |
+| `toche doctor` | Show configuration and integration health |
+| `toche status` | Show gateway status |
+
+</details>
+
+<details>
+<summary><strong>Usage, reduction, and persistent cache</strong></summary>
+
+| Command | What it does |
+|---|---|
+| `toche stats` | Show a human-readable usage and cost breakdown |
+| `toche stats --json` | Print machine-readable statistics |
+| `toche stats --entries 100` | Include the last 100 ledger entries |
+| `toche expand <hash>` | Restore original tool output from a reduction hash |
+| `toche cache inspect` | List persistent safe-cache entries |
+| `toche cache clear` | Clear entries for the current project |
+| `toche cache clear --all` | Clear all persistent cache entries |
+| `toche cache why <fingerprint>` | Explain the cache decision for a fingerprint |
+
+</details>
+
+<details>
+<summary><strong>Continuity and project graph</strong></summary>
+
+| Command | What it does |
+|---|---|
+| `toche checkpoint save` | Save a session checkpoint |
+| `toche checkpoint list` | List saved checkpoints |
+| `toche checkpoint show` | Show the latest checkpoint |
+| `toche checkpoint delete <id>` | Delete a checkpoint |
+| `toche graph query <question>` | Query the optional knowledge graph |
+| `toche graph status` | Show graph node and edge counts |
+| `toche graph extract` | Rebuild the knowledge graph |
+
+</details>
+
+### Per-request bypasses
+
+Set a header to `true`, case-insensitively, to skip a stage for one request.
+The umbrella bypass takes precedence over individual bypasses.
+
+| Header | Skips |
+|---|---|
+| `x-toche-bypass` | The complete optimization pipeline |
+| `x-toche-bypass-shield` | Request coalescing |
+| `x-toche-bypass-safe-cache` | Persistent cache lookup and storage |
+| `x-toche-bypass-reduce` | Tool-output reduction |
+| `x-toche-bypass-efficiency` | Efficiency instruction injection |
+| `x-toche-bypass-cache` | Provider prompt-cache injection |
+
+## Configuration
+
+Profiles live in `~/.toche/profiles.toml`. Running `toche setup` generates a
+profile from your existing Claude Code configuration.
+
+<details>
+<summary><strong>Example profile</strong></summary>
+
+```toml
+default = "default"
+
+[[profiles]]
+name = "default"
+upstream_url = "https://api.anthropic.com"
+auth_method = { type = "api_key", header_name = "x-api-key", key = "YOUR_ANTHROPIC_API_KEY" }
+
+[profiles.cache]
+enabled = true
+mode = "auto"
+breakpoint = "standard"
+
+[profiles.reduce]
+enabled = true
+
+[profiles.efficiency]
+mode = "concise"
+
+[profiles.safe_cache]
+enabled = true
+ttl_days = 30
+max_entry_bytes = 1048576
+
+[profiles.graphify]
+enabled = false
+```
+
+</details>
+
+Set `TOCHE_CONFIG_DIR` to override the default `~/.toche/` directory.
+
+## Troubleshooting
+
+<details>
+<summary><strong>The gateway will not start</strong></summary>
+
+- Check that nothing else is listening on port 8743.
+- Run `toche doctor` to verify that `profiles.toml` exists and is valid.
+- Enable debug logging with `RUST_LOG=toche=debug toche`.
+
+</details>
+
+<details>
+<summary><strong>Claude Code cannot connect</strong></summary>
+
+- Start the gateway before running `toche connect`.
+- Run `toche doctor` in a second terminal after connecting.
+
+</details>
+
+<details>
+<summary><strong>Stats or cache entries are empty</strong></summary>
+
+- The ledger records only requests routed through the gateway.
+- The persistent cache stores only eligible text-only responses without `tool_use` blocks.
+- Use `toche cache why <fingerprint>` to inspect a cache rejection.
+
+</details>
+
+<details>
+<summary><strong>Routing still points to Toche after disconnecting</strong></summary>
+
+Run `toche doctor`. If `env.ANTHROPIC_BASE_URL` still points to Toche while the
+gateway is stopped, inspect `~/.claude/settings.json` and its Toche backup.
+
+</details>
+
+## Requirements
+
+- Rust 1.86 or newer, edition 2024
+- Claude Code or another Anthropic Messages API client
+- No hosted Toche service
+- SQLite is bundled through `rusqlite`
+
+## Documentation
+
+- [Architecture](docs/ARCHITECTURE.md): pipeline, modules, databases, and storage
+- [Changelog](CHANGELOG.md): release history from 0.1.0 through 1.0.9
+- [Bug tracker](docs/BUG_TRACKER.md): issues found and fixed during dogfooding
+- [npm publishing](docs/NPM_PUBLISHING.md): maintainer checklist for the first npm release
+- [Third-party notices](THIRD_PARTY_NOTICES.md): reused ideas, integration decisions, and attribution
+
+## Built from good work
+
+Toche's Rust implementation was informed by ideas and patterns from ccusage, RTK,
+Graphify, andrej-karpathy-skills, and caveman-claude. Their licenses and attribution
+are preserved in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+## License
+
+Licensed under the [Apache License 2.0](LICENSE).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,73 @@
+# Third-Party Notices
+
+Toche's Rust implementation draws on design ideas and patterns from the projects
+listed below. The repository keeps reference clones in the gitignored
+`vendor_reuse/` directory, while Toche implements its integration under `src/`
+and commits required build inputs under `assets/`. Applicable licenses,
+copyright notices, project links, and integration decisions are preserved here.
+
+## Reuse inventory
+
+| Project | License | Clone commit | Integration | Purpose |
+|---------|---------|-------------|-------------|---------|
+| [ccusage](https://github.com/ccusage/ccusage) | MIT | `ba99c0d` | Reference: adapt pricing/reporting patterns | Usage ledger concepts, pricing models, reporting |
+| [RTK](https://github.com/rtk-ai/rtk) | Apache-2.0 | `5d32d07` | Reference: adapt filter and hook architecture | Command/tool-output reduction, Claude Code hook integration |
+| [Graphify](https://github.com/Graphify-Labs/graphify) | MIT | `43b2aff` | External CLI/MCP adapter | Local project graph and query service |
+| [andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) | MIT | `2c60614` | Reference: adapt policy rules | Careful-work policy profile (Section 0.6.0) |
+| [caveman-claude](https://github.com/juliusbrussee/caveman) | MIT | `0d95a81` | Reference: adapt concision patterns | Concise response profile, token reduction strategies |
+
+## License texts
+
+### ccusage: MIT
+
+```
+MIT License
+Copyright (c) 2025 ryoppippi
+```
+Full text: `vendor_reuse/ccusage/apps/ccusage/LICENSE`
+
+### RTK: Apache-2.0
+
+```
+Apache License, Version 2.0
+Copyright 2024 rtk-ai and rtk-ai Labs
+```
+The imported filter definitions are documented in
+[`assets/filters/README.md`](assets/filters/README.md). The applicable
+Apache-2.0 terms are reproduced in Toche's [LICENSE](LICENSE).
+
+### Graphify: MIT
+
+```
+MIT License
+Copyright (c) 2026 Safi Shamsi
+```
+Full text: `vendor_reuse/graphify/LICENSE`
+
+### andrej-karpathy-skills: MIT
+
+License type confirmed as MIT per project documentation. No standalone LICENSE file in repository root as of the cloned commit.
+
+### caveman-claude: MIT
+
+```
+MIT License
+Copyright (c) 2026 Julius Brussee
+```
+Full text: `vendor_reuse/caveman-claude/LICENSE`
+
+## Integration decisions
+
+Per Section 4 of the Toche plan, the decision for each project:
+
+- **ccusage**: Reference adaptation. Study Rust usage-tracking patterns; adapt pricing models and reporting concepts into Toche's Meter module. Not a library dependency. Toche implements its own SQLite ledger.
+- **RTK**: Reference adaptation. Toche implements its own deterministic reducer and imports 63 Apache-2.0 TOML filter definitions from the pinned RTK commit. The RTK binary is not bundled.
+- **Graphify**: External adapter. Toche calls Graphify's CLI/MCP interface as an optional integration. Graphify is not compiled into Toche. No Python engine code is ported.
+- **andrej-karpathy-skills**: Reference adaptation. Policy rules (think-first, surgical-change, verify-outcome) adapted into Toche's efficiency profiles. No verbatim copy.
+- **caveman-claude**: Reference adaptation. Concision patterns and intensity levels adapted into Toche's response profiles. Hook architecture patterns inform Toche's own hook system.
+
+No transitive dependencies from these projects are included in Toche. Each project's own dependency tree is documented in its respective repository.
+
+## Toche license
+
+Toche is distributed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full text.

package/npm/bin/toche.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawn } = require("node:child_process");
+
+const executable = process.platform === "win32" ? "toche-bin.exe" : "toche-bin";
+const binary = path.join(__dirname, executable);
+
+if (!fs.existsSync(binary)) {
+  console.error("Toche's native binary is missing.");
+  console.error("Reinstall without --ignore-scripts: npm install -g @nzkbuild/toche");
+  process.exit(1);
+}
+
+const child = spawn(binary, process.argv.slice(2), {
+  argv0: "toche",
+  stdio: "inherit"
+});
+
+child.on("error", (error) => {
+  console.error(`Could not start Toche: ${error.message}`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code === null ? 1 : code);
+});

package/npm/install.js

@@ -0,0 +1,147 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const https = require("node:https");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const packageJson = require("../package.json");
+const binDir = path.join(__dirname, "bin");
+
+const targets = {
+  "darwin-arm64": { triple: "aarch64-apple-darwin", format: "tar.gz" },
+  "darwin-x64": { triple: "x86_64-apple-darwin", format: "tar.gz" },
+  "linux-x64": { triple: "x86_64-unknown-linux-gnu", format: "tar.gz" },
+  "win32-x64": { triple: "x86_64-pc-windows-msvc", format: "zip" }
+};
+
+function releaseAsset(platform = process.platform, arch = process.arch) {
+  const key = `${platform}-${arch}`;
+  const target = targets[key];
+  if (!target) {
+    const supported = Object.keys(targets).join(", ");
+    throw new Error(`Unsupported platform ${key}. Supported platforms: ${supported}.`);
+  }
+
+  const stem = `toche-${packageJson.version}-${target.triple}`;
+  return { ...target, archive: `${stem}.${target.format}`, folder: stem };
+}
+
+function parseChecksum(text) {
+  const match = text.trim().match(/^([a-fA-F0-9]{64})\s+/);
+  if (!match) throw new Error("Release checksum file is malformed.");
+  return match[1].toLowerCase();
+}
+
+function sha256(file) {
+  const hash = crypto.createHash("sha256");
+  hash.update(fs.readFileSync(file));
+  return hash.digest("hex");
+}
+
+function download(url, destination, redirects = 0) {
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, { headers: { "user-agent": "toche-npm-installer" } }, (response) => {
+        if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+          response.resume();
+          if (redirects >= 5) {
+            reject(new Error(`Too many redirects while downloading ${url}.`));
+            return;
+          }
+          const next = new URL(response.headers.location, url).toString();
+          download(next, destination, redirects + 1).then(resolve, reject);
+          return;
+        }
+
+        if (response.statusCode !== 200) {
+          response.resume();
+          reject(new Error(`Download failed with HTTP ${response.statusCode}: ${url}`));
+          return;
+        }
+
+        const file = fs.createWriteStream(destination, { mode: 0o600 });
+        response.pipe(file);
+        file.on("finish", () => file.close(resolve));
+        file.on("error", reject);
+      })
+      .on("error", reject);
+  });
+}
+
+function extract(archive, destination, format) {
+  fs.mkdirSync(destination, { recursive: true });
+  if (format === "tar.gz") {
+    const result = spawnSync("tar", ["-xzf", archive, "-C", destination], { stdio: "inherit" });
+    if (result.status !== 0) throw new Error("Could not extract the Toche tar archive.");
+    return;
+  }
+
+  const powershell = process.env.SystemRoot
+    ? path.join(process.env.SystemRoot, "System32", "WindowsPowerShell", "v1.0", "powershell.exe")
+    : "powershell.exe";
+  const command = "Expand-Archive -LiteralPath $args[0] -DestinationPath $args[1] -Force";
+  const result = spawnSync(
+    powershell,
+    ["-NoProfile", "-NonInteractive", "-Command", command, archive, destination],
+    { stdio: "inherit" }
+  );
+  if (result.status !== 0) throw new Error("Could not extract the Toche zip archive.");
+}
+
+async function install() {
+  const executable = process.platform === "win32" ? "toche-bin.exe" : "toche-bin";
+  const destination = path.join(binDir, executable);
+  fs.mkdirSync(binDir, { recursive: true });
+
+  if (process.env.TOCHE_BINARY_PATH) {
+    fs.copyFileSync(path.resolve(process.env.TOCHE_BINARY_PATH), destination);
+    if (process.platform !== "win32") fs.chmodSync(destination, 0o755);
+    console.log(`Toche ${packageJson.version} installed from TOCHE_BINARY_PATH.`);
+    return;
+  }
+
+  const asset = releaseAsset();
+  const tag = `v${packageJson.version}`;
+  const base = process.env.TOCHE_DOWNLOAD_BASE ||
+    `https://github.com/nzkbuild/toche/releases/download/${tag}`;
+  const temporary = fs.mkdtempSync(path.join(os.tmpdir(), "toche-install-"));
+
+  try {
+    const archive = path.join(temporary, asset.archive);
+    const checksumFile = `${archive}.sha256`;
+    console.log(`Downloading Toche ${packageJson.version} for ${process.platform}-${process.arch}...`);
+    await download(`${base}/${asset.archive}`, archive);
+    await download(`${base}/${asset.archive}.sha256`, checksumFile);
+
+    const expected = parseChecksum(fs.readFileSync(checksumFile, "utf8"));
+    const actual = sha256(archive);
+    if (actual !== expected) throw new Error(`Checksum mismatch for ${asset.archive}.`);
+
+    const extracted = path.join(temporary, "extracted");
+    extract(archive, extracted, asset.format);
+    const binaryName = process.platform === "win32" ? "toche.exe" : "toche";
+    const source = path.join(extracted, asset.folder, binaryName);
+    if (!fs.existsSync(source)) {
+      throw new Error(`Release archive does not contain ${asset.folder}/${binaryName}.`);
+    }
+
+    fs.copyFileSync(source, destination);
+    if (process.platform !== "win32") fs.chmodSync(destination, 0o755);
+    console.log(`Toche ${packageJson.version} installed. Run: toche setup`);
+  } finally {
+    fs.rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+if (require.main === module) {
+  install().catch((error) => {
+    console.error(`Toche installation failed: ${error.message}`);
+    console.error("See https://github.com/nzkbuild/toche#install");
+    process.exit(1);
+  });
+}
+
+module.exports = { install, parseChecksum, releaseAsset };

package/npm/install.test.js

@@ -0,0 +1,25 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const test = require("node:test");
+const { parseChecksum, releaseAsset } = require("./install");
+
+test("maps every published platform to its release archive", () => {
+  assert.equal(releaseAsset("linux", "x64").archive, "toche-1.0.9-x86_64-unknown-linux-gnu.tar.gz");
+  assert.equal(releaseAsset("win32", "x64").archive, "toche-1.0.9-x86_64-pc-windows-msvc.zip");
+  assert.equal(releaseAsset("darwin", "x64").archive, "toche-1.0.9-x86_64-apple-darwin.tar.gz");
+  assert.equal(releaseAsset("darwin", "arm64").archive, "toche-1.0.9-aarch64-apple-darwin.tar.gz");
+});
+
+test("rejects a platform without a published binary", () => {
+  assert.throws(() => releaseAsset("linux", "arm64"), /Unsupported platform/);
+});
+
+test("parses sha256sum output", () => {
+  const hash = "a".repeat(64);
+  assert.equal(parseChecksum(`${hash}  toche.tar.gz\n`), hash);
+});
+
+test("rejects malformed checksums", () => {
+  assert.throws(() => parseChecksum("not-a-checksum"), /malformed/);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@nzkbuild/toche",
+  "version": "1.0.9",
+  "description": "Local efficiency gateway for Claude Code",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nzkbuild/toche.git"
+  },
+  "homepage": "https://github.com/nzkbuild/toche#readme",
+  "bugs": {
+    "url": "https://github.com/nzkbuild/toche/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "anthropic",
+    "context",
+    "cache",
+    "cli",
+    "rust"
+  ],
+  "bin": {
+    "toche": "npm/bin/toche.js"
+  },
+  "files": [
+    "npm/bin/toche.js",
+    "npm/install.js",
+    "npm/install.test.js",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "postinstall": "node npm/install.js",
+    "test:npm": "node --test npm/install.test.js",
+    "check:package": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}