@spatz/cli 0.0.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lorenz Hilpert
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,251 @@
-Placeholder. See https://github.com/lorenzh/spatz
+# spatz
+
+**Choose a model and effort for your coding task. Learn from the result.**
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/github/v/release/lorenzh/spatz)](https://github.com/lorenzh/spatz/releases/latest)
+[![Bun 1.4](https://img.shields.io/badge/Bun-1.4-black?logo=bun)](https://bun.sh)
+
+Do not use a cannon to shoot sparrows.
+
+spatz ranks the model and effort pairs that you can use for a coding task.
+It learns from task results to help choose cheaper pairs that succeed.
+You or your coding agent run the task with the recommended pair.
+
+[Quickstart](#quickstart) · [Documentation](#documentation) · [Contributing](#contributing) · [Releases](https://github.com/lorenzh/spatz/releases)
+
+## Why spatz?
+
+Different tasks need different models and effort levels.
+spatz combines task classification with results from your previous tasks.
+
+- **Use your available models.** Pass the candidates with `--models`.
+- **Learn from results.** Record outcomes through hooks or `spatz report`.
+- **Compare performance.** Use `spatz stats` to see results per task type or routing scope.
+- **Connect to coding agents.** Hooks support Claude Code and Codex CLI. Other agents can use the CLI directly.
+- **Keep learning data local.** spatz stores results in `~/.spatz/spatz.db`. It does not store task text.
+
+## Quickstart
+
+### 1. Install
+
+Install the stable CLI with Node.js 18 or newer:
+
+```bash
+npm install -g @spatz/cli
+spatz --version
+```
+
+The npm package includes the Bun runtime. Keep optional dependencies enabled.
+Linux needs glibc. spatz does not support Alpine Linux.
+Windows x64 support is experimental. Some releases omit it.
+
+For installation without Node.js, use a [release archive](#releases).
+For the unstable nightly version, use `npm install -g @spatz/cli@nightly`.
+
+### 2. Ask for a recommendation
+
+Pass the task and the model pairs that your agent can run:
+
+```bash
+spatz "Fix the off-by-one error in src/list.ts" \
+  --models claude-opus-5-5:high+medium,claude-sonnet-5-5:medium+low
+```
+
+Each candidate uses `<model-id>:<effort>+<effort>...`.
+Use model IDs and efforts that your environment supports.
+The output includes a `suggestion_id` and a ranked list of pairs.
+Add `--json` for machine-readable output.
+
+spatz works without an API key.
+Without Jev or learned results, it recommends the most expensive candidate.
+Jev is the TypeSafe AI model that classifies the task and estimates candidate suitability.
+To enable Jev, set your TypeSafe AI key:
+
+```bash
+export TYPESAFE_AI_API_KEY="<your-key>"
+```
+
+When you enable Jev, spatz sends task text and candidate details to TypeSafe AI.
+Read [Privacy](#privacy) before using sensitive task text.
+
+### 3. Run the task and report the result
+
+Run the task with the chosen model and effort in your coding agent.
+Then report the pair you actually used:
+
+```bash
+spatz report <suggestion_id> \
+  --model claude-sonnet-5-5 --effort medium --result pass
+
+spatz stats
+```
+
+Replace `<suggestion_id>` with the ID from the recommendation.
+Results can be `pass`, `partial`, or `fail`.
+An explicit report overrides hook signals for that recommendation.
+
+For experiments, add `--dry-run` to the recommendation command.
+These suggestions never count toward learning or statistics.
+
+## How it works
+
+1. A local filter checks the task text for known secret patterns.
+2. Jev classifies the task. Without Jev, spatz uses local keyword rules.
+3. spatz ranks your candidates using classification and learned success estimates.
+4. You or your agent choose a pair and run the task.
+5. Hooks or `spatz report` record the outcome for future recommendations.
+
+The CLI recommends pairs. The optional Claude Code mod can apply them automatically.
+See [How it works](docs/how-it-works.md) and [Recommendation rules](docs/recommendation.md) for the decision process.
+
+## Agent integrations
+
+| Integration | What it does | Setup |
+| --- | --- | --- |
+| Claude Code `spatz-hooks` plugin | Record task signals and model usage. | [Hooks guide](docs/hooks.md) |
+| Codex `spatz-hooks` plugin | Record shell results and model usage. | [Hooks guide](docs/hooks.md) |
+| Claude Code `spatz` plugin (mod) | Show recommendations or apply model and effort choices. | [Mod guide](docs/claude-mod.md) |
+| Other agents | Request recommendations and report outcomes through the CLI. | [CLI reference](docs/cli.md) |
+
+The Claude Code mod supports `step`, `turn`, `subagent`, `session`, and `escalate` routing scopes.
+Hooks and the mod can run together. The mod's `record: auto` avoids duplicate usage recording with the `spatz-hooks` plugin.
+
+### Install the plugins
+
+In Claude Code:
+
+```text
+/plugin marketplace add lorenzh/spatz
+/plugin install spatz-hooks@spatz
+/plugin install spatz@spatz
+```
+
+`spatz-hooks` records outcomes. `spatz` is the mod that recommends or applies model and effort. Install one or both.
+
+In Codex:
+
+```bash
+codex plugin marketplace add lorenzh/spatz
+codex plugin add spatz-hooks@spatz
+```
+
+Codex runs new hooks only after you trust them with `/hooks`.
+
+Every plugin ships the `spatz` skill, which tells the agent when to ask spatz and how to report results, so you do not need to edit your agent instructions.
+The plugins also ship a launcher. It uses `spatz` from your `PATH` if present. Otherwise it runs the matching `@spatz/cli` version through Bun or npx, which downloads about 60 MB on first use.
+Codex hooks time out after 10 seconds, so run the launcher once before the first session: `"<plugin root>/bin/spatz" --version`.
+The plugins need a POSIX shell. Native Windows is not supported yet.
+If you added spatz hooks to `~/.claude/settings.json` or `~/.codex/hooks.json` by hand, remove them to avoid duplicate records.
+See [Installation](docs/installation.md) for details.
+
+## Privacy
+
+spatz stores learning data under `~/.spatz`. It does not store task text or tool output.
+Hooks process task signals locally and make no network requests.
+
+When you enable Jev, spatz sends task text and candidate details to TypeSafe AI.
+The secret filter catches known patterns. It cannot detect every secret.
+Do not put secrets in task text.
+
+To disable Jev:
+
+```bash
+export SPATZ_NO_JEV=1
+```
+
+For a project, put `{"jev": false}` in `.spatz.json` in the working directory.
+Without `TYPESAFE_AI_API_KEY`, Jev is also disabled.
+
+Disabling Jev still allows OpenRouter requests for model prices. These requests contain no task data.
+spatz caches prices for 24 hours. When the network is unavailable, spatz can still use cached prices.
+The first `spatz stats` run downloads DuckDB's SQLite extension.
+
+See the [Privacy guide](docs/privacy.md) for data flows and deletion instructions.
+See [Configuration](docs/configuration.md) for environment variables and local files.
+
+## Releases
+
+Download an archive and its matching `.sha256` file from [GitHub Releases](https://github.com/lorenzh/spatz/releases).
+Archives include the runtime. You do not need Node.js or Bun installed.
+
+Choose `linux` or `darwin` (macOS), then `x64` or `arm64`.
+Apple Silicon uses `darwin-arm64`. Linux builds need glibc.
+Windows x64 ZIP archives are experimental. The agent plugins do not support native Windows.
+
+Check the checksum before extraction. This Linux x64 example uses version `0.1.0`:
+
+```bash
+version=0.1.0
+archive="spatz-cli-$version-linux-x64.tar.gz"
+sha256sum --check "$archive.sha256"
+
+mkdir -p ~/.local/lib/spatz ~/.local/bin
+tar -xzf "$archive" -C ~/.local/lib/spatz
+ln -sfn "$HOME/.local/lib/spatz/${archive%.tar.gz}/spatz" ~/.local/bin/spatz
+export PATH="$HOME/.local/bin:$PATH"
+spatz --version
+```
+
+Use your downloaded version. On macOS, use `shasum -a 256 --check "$archive.sha256"`.
+If your shell does not include `~/.local/bin`, add the `PATH` line to your shell profile.
+Keep the executable and DuckDB libraries together. `spatz stats` needs these libraries beside the executable.
+
+The [nightly release](https://github.com/lorenzh/spatz/releases/tag/nightly) is unstable.
+See [Releasing spatz](RELEASING.md) for the release process.
+
+## Install from source
+
+Install Bun 1.4, then clone the repository:
+
+```bash
+git clone https://github.com/lorenzh/spatz.git
+cd spatz
+bun install
+```
+
+Put a wrapper on your `PATH` so hooks can find `spatz` in non-interactive shells:
+
+```bash
+mkdir -p ~/.local/bin
+printf '#!/bin/sh\nexec bun "%s/packages/cli/src/cli.ts" "$@"\n' "$PWD" > ~/.local/bin/spatz
+chmod +x ~/.local/bin/spatz
+export PATH="$HOME/.local/bin:$PATH"
+spatz --version
+```
+
+A shell alias does not work for hooks.
+See [Contributing](CONTRIBUTING.md) for the full development setup.
+
+## Documentation
+
+| Guide | What you will find |
+| --- | --- |
+| [CLI reference](docs/cli.md) | Commands, flags, model IDs, output fields, and exit codes. |
+| [How it works](docs/how-it-works.md) | Architecture and the flow from task to outcome. |
+| [Recommendation rules](docs/recommendation.md) | Ranking, exploration, and control groups. |
+| [Hooks](docs/hooks.md) | Claude Code and Codex CLI setup and recorded signals. |
+| [Claude Code mod](docs/claude-mod.md) | Modes, routing scopes, and `/spatz` commands. |
+| [Configuration](docs/configuration.md) | Environment variables and local files. |
+| [Privacy](docs/privacy.md) | Network requests, stored data, and deletion. |
+
+## Contributing
+
+Bug reports and pull requests are welcome.
+For larger changes, [open an issue](https://github.com/lorenzh/spatz/issues) first to agree on the scope.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and the test-first workflow.
+Changes to `main` must go through a pull request.
+
+Run the checks before submitting a change:
+
+```bash
+bun test
+bun run typecheck
+bun run lint
+```
+
+For vulnerabilities, follow [SECURITY.md](SECURITY.md). Do not open a public issue.
+
+## License
+
+[MIT](LICENSE) © 2026 Lorenz Hilpert.

package/bin/spatz.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+const { spawnSync } = require("node:child_process");
+const { constants } = require("node:os");
+const { dirname, join } = require("node:path");
+
+const packages = {
+	"linux-x64": "@spatz/cli-linux-x64",
+	"linux-arm64": "@spatz/cli-linux-arm64",
+	"darwin-arm64": "@spatz/cli-darwin-arm64",
+	"darwin-x64": "@spatz/cli-darwin-x64",
+	"win32-x64": "@spatz/cli-win32-x64",
+};
+const target = `${process.platform}-${process.arch}`;
+const pkg = packages[target];
+if (!pkg) {
+	console.error(`spatz: unsupported platform ${target}`);
+	process.exit(1);
+}
+let dir;
+try {
+	dir = dirname(require.resolve(`${pkg}/package.json`));
+} catch {
+	console.error(
+		`spatz: missing ${pkg}. Reinstall @spatz/cli with optional dependencies enabled (omit --no-optional / --omit=optional). The experimental Windows package may be unavailable for this release.`,
+	);
+	process.exit(1);
+}
+const child = spawnSync(
+	join(dir, process.platform === "win32" ? "spatz.exe" : "spatz"),
+	process.argv.slice(2),
+	{ stdio: "inherit" },
+);
+if (child.error) {
+	console.error(`spatz: ${child.error.message}`);
+	process.exit(1);
+}
+if (child.signal) {
+	process.kill(process.pid, child.signal);
+	process.exit(128 + constants.signals[child.signal]);
+} else process.exit(child.status ?? 1);

package/package.json

@@ -1 +1,26 @@
-{ "name": "@spatz/cli", "version": "0.0.0", "description": "Placeholder for spatz. Real releases are published from GitHub Actions.", "license": "MIT", "repository": { "type": "git", "url": "git+https://github.com/lorenzh/spatz.git" } }
+{
+  "name": "@spatz/cli",
+  "version": "0.1.1",
+  "description": "Model and effort recommendations for coding agents",
+  "bin": {
+    "spatz": "bin/spatz.js"
+  },
+  "optionalDependencies": {
+    "@spatz/cli-linux-x64": "0.1.1",
+    "@spatz/cli-linux-arm64": "0.1.1",
+    "@spatz/cli-darwin-arm64": "0.1.1",
+    "@spatz/cli-darwin-x64": "0.1.1",
+    "@spatz/cli-win32-x64": "0.1.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lorenzh/spatz.git"
+  },
+  "files": [
+    "bin"
+  ]
+}