chutes-build 0.1.0

package/LICENSE

@@ -0,0 +1,204 @@
+Copyright 2023-2026 SpaceXAI
+
+
+                                 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 [yyyy] [name of copyright owner]
+
+   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 @@
+Chutes Build
+Copyright 2026 Michael Gasperini (Mikesoft)
+
+This product is derived from xai-org/grok-build, originally distributed under
+the Apache License, Version 2.0, and includes substantial modifications for the
+Chutes ecosystem, including Chutes authentication and endpoints, model routing
+and fallbacks, multimodal media tools, advisor and orchestration behavior,
+Context7 integration, local memory, web/browser tools, privacy controls, and
+Chutes Build branding.
+
+The upstream copyright and attribution notices are retained in LICENSE and
+THIRD-PARTY-NOTICES. Files changed from the upstream work carry their changes
+through this repository's version-control history and this notice.
+
+The native Chutes media subsystem incorporates the workflow and project-owned
+implementation concepts from chutes-media-mcp, Copyright 2026 Michael Gasperini
+(Mikesoft), originally available under the MIT License. The applicable MIT
+license notice is preserved in this repository's third-party notices.

package/PRIVACY.md

@@ -0,0 +1,78 @@
+# Privacy
+
+Chutes Build is privacy-first: it collects no product analytics, emits no
+telemetry, performs no remote error reporting, and does not upload traces or
+sessions. There is no hidden opt-in or installation identifier.
+
+## Local data
+
+The CLI may store configuration, an encrypted or OS-protected credential entry
+where supported, sessions, logs, local exports, and user memory under
+`~/.chutes-build` (or `CHUTES_BUILD_HOME`). Project memory is maintained in
+`memories.md`. Known secret formats are filtered before memory writes, but users
+should still avoid entering secrets into prompts.
+
+`chutes-build trace` always creates a local archive. Remote session sharing and
+upstream managed configuration commands are disabled. Automatic update checks
+are disabled.
+
+Sampling diagnostics are disabled by default. When explicitly enabled with
+`--log-sampling` or `CHUTES_BUILD_LOG_SAMPLING=1`, the local
+`logs/sampling.jsonl` file records operational metadata such as model, endpoint,
+effort, token counts, errors, and SSE chunk byte lengths. It does not record
+credential values or prefixes, request/response bodies, or normal SSE chunk
+text. Provider-supplied error messages may still appear and should be reviewed
+before sharing a diagnostic archive.
+
+Prompt-efficiency debug events and the optional deterministic benchmark contain
+only local numeric size estimates and built-in fixture data, never prompt or
+source contents. Generated-media preview and audio playback stay local:
+image/video decoding uses local image codecs and FFmpeg tools when installed,
+and audio uses `ffplay` or the operating system's default player. Preview work
+is bounded, off-thread, serialized, and deferred while inference is active. No
+remote preview, thumbnail, codec, waveform, or playback service is used.
+
+## Outbound connections
+
+Connections occur only when required by an explicit feature:
+
+| Destination | Purpose | Data sent |
+| --- | --- | --- |
+| `model-router-ten.vercel.app` | default Chutes-compatible model routing | prompts, selected tool schemas, model responses, Chutes API credential |
+| `llm.chutes.ai` | Chutes inference and model catalog | prompts/model requests and Chutes API credential |
+| `api.chutes.ai` | Chutes account and media APIs | requested media parameters/assets and Chutes API credential |
+| `chutes.ai/docs`, `chutes.ai/news` | mandatory primary-source verification for Chutes topics | requested official page URLs; no Chutes API credential |
+| `context7.com` | current library documentation | library names and documentation queries; credentials and known secrets are rejected |
+| DuckDuckGo or Brave Search | web search | search query; Brave receives only its dedicated key |
+| User-selected web pages | web fetch/browser automation | normal HTTP/browser traffic required by the requested action |
+| User-configured MCP servers/plugins | external tools | data required by the selected tool and its own configuration |
+
+The Chutes API credential is accepted only for allowlisted Chutes and router
+hosts. It is never reused for web search, Context7, arbitrary websites, MCP
+servers, or browser automation.
+
+For Chutes research, the agent prefers direct official pages and indexes over a
+broad search query. Search and page requests must not include credentials,
+private code, prompts, or repository content. If web access is disabled, the
+agent reports that current official verification could not be completed.
+
+## Browser isolation
+
+Agentic browser control launches a temporary Chrome/Edge profile and connects
+through a loopback-only DevTools endpoint. It does not attach to the user's
+normal browser profile. Sync and background network features are disabled.
+Screenshots are restricted to the active workspace.
+
+Browser actions can still disclose data to websites the user asks the agent to
+visit. Review navigation, form submissions, uploads, and authenticated actions
+before approval.
+
+## Disabling stateful features
+
+- Start with `--no-memory` to disable agent memory for a session.
+- Disable web search with `--disable-web-search`.
+- Do not configure external MCP servers or plugins you do not trust.
+- Set `CHUTES_STRICT_MODEL=1` to disable model fallback.
+
+Privacy regressions are security issues and should be reported through the
+private process in [SECURITY.md](SECURITY.md).

package/README.md

@@ -0,0 +1,246 @@
+# Chutes Build
+
+[![CI](https://github.com/TheStreamCode/chutes-build/actions/workflows/ci.yml/badge.svg)](https://github.com/TheStreamCode/chutes-build/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/chutes-build.svg)](https://www.npmjs.com/package/chutes-build)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+
+Chutes Build is a privacy-first, open-source coding agent optimized for the
+[Chutes](https://chutes.ai) ecosystem. It combines an interactive terminal UI,
+coding tools, model routing, parallel subagents, multimodal generation, web
+research, browser automation, and local memory in one CLI.
+
+![Chutes Build terminal UI](assets/chutes/screenshot/chutes-build.png)
+
+> **Development preview:** the project is under active development. Build it
+> from source and review agent actions before approving changes.
+
+## What is included
+
+- **Chutes-native inference:** API-key authentication, live model discovery,
+  `Auto (Chutes Router)` as the first model choice, configurable fallback
+  chains, and automatic retry when a selected model is temporarily unavailable.
+- **Coding agent runtime:** repository inspection, edits, shell commands,
+  planning, goals, MCP servers, skills, sessions, worktrees, and permission
+  controls inherited from the mature upstream runtime.
+- **Advisor:** a read-only, on-demand reasoning agent that reviews plans,
+  difficult decisions, blockers, and completion claims without taking over the
+  executor loop.
+- **Subagent orchestration:** foreground and background workers, concurrent
+  fan-out, multi-worker waits, bounded nesting, and isolated worktrees. The
+  `chutes-build-orchestrator` preset is tuned for parallel decomposition.
+- **Chutes account:** read-only subscription, quota, and usage access through
+  `get_chutes_usage`, a compact plan/quota indicator in the TUI, and detailed
+  `/usage` output. Per-model statistics remain disabled unless requested.
+- **Chutes media:** live discovery and invocation for image generation and
+  editing, video, music, speech, and other supported Chutes media models through
+  `list_media_models`, `describe_media_model`, and `generate_media`. This is the
+  native Rust integration of the `chutes-media-mcp` workflow, so Chutes Build
+  does not need to spawn a separate Node/MCP process for its core media tools.
+  Generated output crosses the tool/ACP/TUI boundary as a typed artifact:
+  images use bounded lazy previews, videos use a two-frame rolling decoder,
+  and music/speech expose local pause/resume, seek, volume, duration, and
+  waveform controls with native-player fallback. Media work starts only while
+  inference is idle, never autoplays, and stays off the TUI render thread.
+- **Capability routing:** image inputs stay with the selected model when it
+  supports vision and are otherwise delegated to a vision-capable Chutes route.
+- **Current coding documentation:** Context7 search and documentation tools are
+  built in and avoid sending credentials or known secrets.
+- **Official Chutes research:** before answering Chutes-specific questions, the
+  main agent and subagents consult both the official
+  [documentation](https://chutes.ai/docs) and [news](https://chutes.ai/news),
+  treating directly relevant official pages as primary authority.
+- **Research and browser tools:** native web search (DuckDuckGo by default,
+  optionally Brave) plus agentic Chrome/Edge control through a local DevTools
+  connection and an isolated temporary browser profile.
+- **Local memory:** Chutes Build maintains a secret-filtered `memories.md` file
+  and can be launched with `--no-memory` when a stateless session is preferred.
+- **Time awareness and wellness:** the agent receives the local date, time, and
+  timezone and can suggest a break after long or late sessions.
+- **Privacy by construction:** telemetry, remote error reporting, automatic
+  update checks, remote trace upload, and upstream session sharing are disabled.
+
+## Install with npm
+
+Release builds install without a Rust toolchain:
+
+```powershell
+npm install -g chutes-build
+chutes-build
+```
+
+For one-off use:
+
+```powershell
+npx chutes-build
+```
+
+The npm launcher selects a native binary for Windows, macOS, or Linux. It does
+not collect telemetry and does not download executables from an install script.
+
+## Build from source
+
+Prerequisites:
+
+- Rust stable (`rustup` is recommended)
+- Git
+- a platform C/C++ build toolchain supported by Rust
+
+Protocol Buffer tooling is vendored for normal builds; a separate `protoc`
+installation is not required.
+
+```powershell
+git clone https://github.com/TheStreamCode/chutes-build.git
+cd chutes-build
+cargo build -p chutes-build --release
+```
+
+The Windows executable is `target\release\chutes-build.exe`; on macOS and
+Linux it is `target/release/chutes-build`.
+
+## Quick start
+
+Run `chutes-build` with no prior setup and log in from the welcome screen:
+press `l` for "Login with Chutes" (opens your browser) or `k` to paste a
+Chutes API key directly. `/login` reopens this choice at any time and
+`/apikey` jumps straight to the API-key prompt.
+
+To provide a key non-interactively instead, create one in Chutes and either
+expose it only to the current process:
+
+```powershell
+$env:CHUTES_API_KEY = "your-api-key"
+chutes-build
+```
+
+or store it using the hidden-input login flow:
+
+```powershell
+chutes-build login
+chutes-build
+```
+
+`Auto (Chutes Router)` is the first entry in the model picker and the default
+when no preference has been saved. Select a concrete model with `/model` or
+`chutes-build --model <model-id>`. Inspect the resolved catalog with
+`chutes-build models`.
+
+## Model selection, reasoning, and routing
+
+Auto sends `model-router` requests to the Chutes router endpoint, allowing the
+service to select a model for the task and handle cold or unavailable capacity.
+A concrete model remains pinned unless a qualifying pre-stream failure advances
+the explicit fallback chain.
+
+Reasoning is model-specific. The model picker exposes only the controls
+supported by the exact deployed generation: binary `Instant`/`Thinking` modes,
+GLM-5.2's three modes, or no selector for fixed and non-reasoning models. Use
+`/effort` interactively or `--effort <option-id>` in headless invocations. The
+published model default is preserved unless the user explicitly changes it.
+
+See [Model reasoning compatibility](docs/model-reasoning-compatibility.md) for
+the current model matrix and forward-compatibility rules.
+
+```powershell
+# Ordered comma-separated fallback chain. model-router is appended as the
+# final Chutes fallback unless strict mode is enabled.
+$env:CHUTES_FALLBACK_MODELS = "model-a,model-b"
+
+# Never change the selected model automatically.
+$env:CHUTES_STRICT_MODEL = "1"
+```
+
+Fallback happens only for transient availability/capability responses and only
+before response streaming begins. Chutes Build does not redirect requests or
+credentials to a non-Chutes inference endpoint.
+
+The inference client shares pooled HTTP connections, enables TCP no-delay, and
+forwards parsed SSE events without an application-level streaming buffer. Cold
+starts and model-side generation can still dominate latency. Auto is the
+recommended default when a particular model is not required. The client does
+not apply reduced-quality generation settings; target selection and quality
+remain router decisions.
+Selecting `Instant` can reduce reasoning latency, but it intentionally changes
+the model's reasoning behavior and is never enabled silently.
+
+## Account plan and quota
+
+When authenticated, Chutes Build fetches subscription usage, plan metadata, and
+quota data concurrently. The TUI status bar shows the plan plus the rolling
+four-hour and monthly percentages when available; its color follows the most
+constrained active window and changes at 80% and 100%. Click the indicator or
+run `/usage` for every active window, percentage, and reset time. If aggregate
+quota usage is unavailable, the client falls back concurrently to the
+documented per-chute quota endpoints.
+
+## Optional web and browser configuration
+
+Web search uses DuckDuckGo without a dedicated key. For Brave Search:
+
+```powershell
+$env:BRAVE_SEARCH_API_KEY = "your-brave-key"
+$env:CHUTES_WEB_SEARCH_PROVIDER = "brave"
+```
+
+Browser automation discovers Chrome or Edge automatically. Overrides:
+
+```powershell
+$env:CHUTES_BROWSER_EXECUTABLE = "C:\Program Files\Google\Chrome\Application\chrome.exe"
+$env:CHUTES_BROWSER_HEADFUL = "1" # optional; default is headless
+```
+
+Browser screenshots may only be written inside the active workspace. The
+automation profile is temporary, isolated from the user's normal browser
+profile, and launched with sync and background-update features disabled.
+
+Video attachments are sampled locally with FFmpeg and routed as representative
+frames through the same Chutes vision path. Set `CHUTES_FFMPEG_EXECUTABLE` when
+FFmpeg is not discoverable on `PATH`; restart Chutes Build after installing or
+changing FFmpeg so the per-process capability cache is refreshed.
+
+Media behavior can be tuned with the compatible `chutes-media-mcp` variables
+`CHUTES_OUTPUT_DIR`, `CHUTES_WARMUP`, `CHUTES_COLD_START_RETRIES`,
+`CHUTES_ALLOW_UNKNOWN_PARAMS`, and `CHUTES_PROVENANCE`. Downloaded media is
+limited to 512 MiB by default (`CHUTES_MAX_MEDIA_BYTES`, hard ceiling 2 GiB),
+while workspace inputs are limited to 64 MiB by default
+(`CHUTES_MAX_INPUT_ASSET_BYTES`, hard ceiling 512 MiB).
+
+## Local data
+
+User-level state defaults to `~/.chutes-build` or the directory set in
+`CHUTES_BUILD_HOME`. Project memory is stored in `memories.md`. Configuration,
+sessions, logs, exports, and credentials remain local unless a tool action
+explicitly calls an external service.
+
+See [PRIVACY.md](PRIVACY.md) for the exact network and data boundaries.
+
+## Security model
+
+Chutes Build is an agent capable of reading files, running commands, editing
+code, and controlling an isolated browser. Use it only in repositories you
+trust, review proposed commands, and keep the default permission checks enabled
+for sensitive work. Never place API keys in prompts, source files, or committed
+configuration. See the [security review](docs/security-review.md) for release
+controls, trust boundaries, and tracked dependency exceptions.
+
+## Project provenance
+
+Chutes Build is a substantially modified fork of
+[`xai-org/grok-build`](https://github.com/xai-org/grok-build). The upstream
+project is licensed under Apache License 2.0; this fork retains the upstream
+license and third-party notices.
+
+See [NOTICE](NOTICE), [LICENSE](LICENSE), and
+[THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES) for attribution.
+
+New upstream releases and commits are detected by a read-only scheduled check
+and reviewed through the documented [upstream synchronization
+procedure](docs/upstream-sync.md); upstream changes are never merged or released
+automatically.
+
+## Contributing
+
+Issues and focused pull requests are welcome. Read
+[CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and
+[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before contributing.
+
+Copyright 2026 Michael Gasperini (Mikesoft).

package/npm/README.md

@@ -0,0 +1,49 @@
+# npm distribution
+
+The public `chutes-build` package is a dependency-free Node.js launcher. Its
+optional dependencies contain the native Rust executable for each supported
+platform, so installation does not require Rust and does not download an
+executable from a lifecycle script.
+
+Supported release targets:
+
+- Windows x64 and ARM64
+- macOS x64 and ARM64
+- Linux glibc x64 and ARM64
+
+## Prepare a platform package
+
+Build the release executable for the target first, then stage its npm package:
+
+```powershell
+node npm/scripts/prepare-platform-package.mjs --target win32-x64 --binary target/release/chutes-build.exe --out-dir target/npm
+npm pack ./target/npm/chutes-build-win32-x64
+```
+
+Valid target names are `win32-x64`, `win32-arm64`, `darwin-x64`,
+`darwin-arm64`, `linux-x64-gnu`, and `linux-arm64-gnu`.
+
+Publish all platform packages for a version before publishing the root
+launcher. The version in `package.json` must match the Rust binary crate and
+every platform package. Publishing is intentionally not performed by the build
+or test scripts. Validate release metadata before packaging:
+
+```powershell
+npm run verify:release
+```
+
+The manual GitHub Actions workflow in `.github/workflows/package-release.yml`
+builds all six native packages. Its publish input is disabled by default and
+requires the protected `npm-release` environment when enabled. See
+[`docs/releasing.md`](../docs/releasing.md) for the full release procedure.
+
+## Verify the launcher
+
+The launcher accepts `CHUTES_BUILD_BINARY` as a local development override:
+
+```powershell
+$env:CHUTES_BUILD_BINARY = (Resolve-Path target/debug/chutes-build.exe)
+node npm/bin/chutes-build.js --help
+npm test
+npm pack --dry-run
+```

package/npm/bin/chutes-build.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const TARGETS = Object.freeze({
+  'darwin-arm64': ['chutes-build-darwin-arm64', 'chutes-build'],
+  'darwin-x64': ['chutes-build-darwin-x64', 'chutes-build'],
+  'linux-arm64': ['chutes-build-linux-arm64-gnu', 'chutes-build'],
+  'linux-x64': ['chutes-build-linux-x64-gnu', 'chutes-build'],
+  'win32-arm64': ['chutes-build-win32-arm64', 'chutes-build.exe'],
+  'win32-x64': ['chutes-build-win32-x64', 'chutes-build.exe']
+});
+
+function resolveBinary() {
+  const override = process.env.CHUTES_BUILD_BINARY;
+  if (override && override.trim()) {
+    return path.resolve(override.trim());
+  }
+
+  const target = `${process.platform}-${process.arch}`;
+  const descriptor = TARGETS[target];
+  if (!descriptor) {
+    throw new Error(
+      `Chutes Build does not provide a prebuilt binary for ${target}. ` +
+        `Supported targets: ${Object.keys(TARGETS).join(', ')}.`
+    );
+  }
+
+  const [packageName, executable] = descriptor;
+  try {
+    return require.resolve(`${packageName}/bin/${executable}`);
+  } catch (cause) {
+    const error = new Error(
+      `The optional package ${packageName} is missing. Reinstall without ` +
+        '`--omit=optional`, or install it explicitly with ' +
+        `\`npm install -g ${packageName}\`.`
+    );
+    error.cause = cause;
+    throw error;
+  }
+}
+
+function main() {
+  let binary;
+  try {
+    binary = resolveBinary();
+  } catch (error) {
+    console.error(`chutes-build: ${error.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = spawnSync(binary, process.argv.slice(2), {
+    stdio: 'inherit',
+    windowsHide: false
+  });
+
+  if (result.error) {
+    console.error(`chutes-build: failed to start ${binary}: ${result.error.message}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (typeof result.status === 'number') {
+    process.exitCode = result.status;
+    return;
+  }
+
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+    return;
+  }
+
+  process.exitCode = 1;
+}
+
+main();

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "chutes-build",
+  "version": "0.1.0",
+  "description": "Privacy-first coding agent optimized for the Chutes ecosystem",
+  "license": "Apache-2.0",
+  "author": "Michael Gasperini (Mikesoft)",
+  "homepage": "https://github.com/TheStreamCode/chutes-build#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TheStreamCode/chutes-build.git"
+  },
+  "bugs": {
+    "url": "https://github.com/TheStreamCode/chutes-build/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs",
+  "bin": {
+    "chutes-build": "npm/bin/chutes-build.js"
+  },
+  "files": [
+    "npm/bin",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "PRIVACY.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test npm/tests/*.test.cjs",
+    "verify:release": "node npm/scripts/verify-release.mjs"
+  },
+  "optionalDependencies": {
+    "chutes-build-darwin-arm64": "0.1.0",
+    "chutes-build-darwin-x64": "0.1.0",
+    "chutes-build-linux-arm64-gnu": "0.1.0",
+    "chutes-build-linux-x64-gnu": "0.1.0",
+    "chutes-build-win32-arm64": "0.1.0",
+    "chutes-build-win32-x64": "0.1.0"
+  },
+  "keywords": [
+    "ai",
+    "chutes",
+    "cli",
+    "coding-agent"
+  ]
+}