@spatz/cli 0.1.5 → 0.1.6-nightly.20261006.gd6cb139

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +21 -11
  2. package/package.json +6 -6
package/README.md CHANGED
@@ -1,3 +1,8 @@
1
+ <picture>
2
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.svg">
3
+ <img src="docs/assets/banner-light.svg" alt="spatz" width="340" height="84">
4
+ </picture>
5
+
1
6
  # spatz
2
7
 
3
8
  **Choose a model and effort for your coding task. Learn from the result.**
@@ -7,8 +12,9 @@ Harness model defaults refresh from a [daily catalog](docs/configuration.md#harn
7
12
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
8
13
  [![Version](https://img.shields.io/github/v/release/lorenzh/spatz)](https://github.com/lorenzh/spatz/releases/latest)
9
14
  [![Bun 1.4](https://img.shields.io/badge/Bun-1.4-black?logo=bun)](https://bun.sh)
10
-
11
- Do not use a cannon to shoot sparrows.
15
+ [![CI](https://github.com/lorenzh/spatz/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/lorenzh/spatz/actions/workflows/ci.yml)
16
+ [![Harness catalog](https://github.com/lorenzh/spatz/actions/workflows/harness-catalog.yml/badge.svg)](https://github.com/lorenzh/spatz/actions/workflows/harness-catalog.yml)
17
+ [![Nightly](https://github.com/lorenzh/spatz/actions/workflows/nightly.yml/badge.svg)](https://github.com/lorenzh/spatz/actions/workflows/nightly.yml)
12
18
 
13
19
  spatz ranks the model and effort pairs that you can use for a coding task.
14
20
  It learns from task results to help choose cheaper pairs that succeed.
@@ -40,10 +46,10 @@ spatz --version
40
46
 
41
47
  The npm package includes the Bun runtime. Keep optional dependencies enabled.
42
48
  Linux needs glibc. spatz does not support Alpine Linux.
43
- Windows x64 support is experimental. Some releases omit it.
49
+ For Windows, see [Platform support](docs/installation.md#platform-support).
44
50
 
45
51
  For installation without Node.js, use a [release archive](#releases).
46
- For the unstable nightly version, use `npm install -g @spatz/cli@nightly`.
52
+ For the unstable nightly version, use `npm install -g @spatz/cli@nightly`. To test a release candidate, use `npm install -g @spatz/cli@next`.
47
53
 
48
54
  ### 2. Ask for a recommendation
49
55
 
@@ -85,7 +91,11 @@ spatz stats
85
91
 
86
92
  Replace `<suggestion_id>` with the ID from the recommendation.
87
93
  Results can be `pass`, `partial`, or `fail`.
88
- An explicit report overrides hook signals for that recommendation.
94
+ An explicit report overrides hook signals for its selected attempt.
95
+ A changed verdict creates a retry. Use `--correct` to fix a mistaken report.
96
+ Use `--attempt <id> --confirm` to report on an existing attempt without creating a retry.
97
+ Use `spatz suggest "Retry the task" --retry-of <suggestion_id>` to link a new suggestion to the same recovery chain.
98
+ See [report flags](docs/cli.md#spatz-report) for explicit attempt selection.
89
99
 
90
100
  For experiments, add `--dry-run` to the recommendation command.
91
101
  These suggestions never count toward learning or statistics.
@@ -108,15 +118,14 @@ See [How it works](docs/how-it-works.md) and [Recommendation rules](docs/recomme
108
118
  | Claude Code `spatz` plugin | Record task signals and model usage. | [Hooks guide](docs/hooks.md) |
109
119
  | Codex `spatz` plugin | Record shell results and model usage. | [Hooks guide](docs/hooks.md) |
110
120
  | Claude Code `spatz-mod` plugin (mod) | Show recommendations or apply model and effort choices. | [Mod guide](docs/claude-mod.md) |
111
- | Other agents | Request recommendations and report outcomes through the CLI. | [Installation](docs/installation.md) | CLI and plugin setup, runtime requirements, and release-specific installs. |
112
- | [CLI reference](docs/cli.md) |
121
+ | Other agents | Request recommendations and report outcomes through the CLI. | [CLI reference](docs/cli.md) |
113
122
 
114
123
  The Claude Code mod supports `step`, `turn`, `subagent`, `session`, and `escalate` routing scopes.
115
- Hooks and the mod can run together. The mod's `record: auto` avoids duplicate usage recording with the `spatz` hooks plugin.
124
+ Hooks and the mod can run together. With `record: auto`, the mod records step usage and hooks record signals.
116
125
 
117
126
  ### Install for Claude Code
118
127
 
119
- Use macOS or Linux with a POSIX shell. The plugins do not support native Windows.
128
+ Use macOS or Linux with a POSIX shell (see [Platform support](docs/installation.md#platform-support)).
120
129
  The plugins run the CLI through a bundled launcher: an installed `spatz` on `PATH` wins, otherwise it uses Bun or npx from the `PATH` Claude Code starts with.
121
130
  The mod needs Claude Code 2.1.287 or newer.
122
131
 
@@ -142,7 +151,7 @@ The mod needs Claude Code 2.1.287 or newer.
142
151
  /spatz status
143
152
  ```
144
153
 
145
- When you install both plugins, keep `record: auto`. The hooks then handle recording.
154
+ When you install both plugins, keep `record: auto`. Hooks record signals. The mod owns usage for its registered execution segments.
146
155
  To apply recommendations to the main session too, enable `/spatz main on`.
147
156
 
148
157
  3. Remove any manual `spatz hook` entries from `~/.claude/settings.json` and project settings.
@@ -219,7 +228,7 @@ Archives include the runtime. You do not need Node.js or Bun installed.
219
228
 
220
229
  Choose `linux` or `darwin` (macOS), then `x64` or `arm64`.
221
230
  Apple Silicon uses `darwin-arm64`. Linux builds need glibc.
222
- Windows x64 ZIP archives are experimental. The agent plugins do not support native Windows.
231
+ For Windows archives, see [Platform support](docs/installation.md#platform-support).
223
232
 
224
233
  Check the checksum before extraction. This Linux x64 example uses version `0.1.0`:
225
234
 
@@ -272,6 +281,7 @@ See [Contributing](CONTRIBUTING.md) for the full development setup.
272
281
  | [CLI reference](docs/cli.md) | Commands, flags, model IDs, output fields, and exit codes. |
273
282
  | [How it works](docs/how-it-works.md) | Architecture and the flow from task to outcome. |
274
283
  | [Recommendation rules](docs/recommendation.md) | Ranking, exploration, and control groups. |
284
+ | [Measurements](docs/measurements.md) | Benchmark results for model and effort selection. |
275
285
  | [Hooks](docs/hooks.md) | Claude Code and Codex CLI setup and recorded signals. |
276
286
  | [Claude Code mod](docs/claude-mod.md) | Modes, routing scopes, and `/spatz` commands. |
277
287
  | [Configuration](docs/configuration.md) | Environment variables and local files. |
package/package.json CHANGED
@@ -1,16 +1,16 @@
1
1
  {
2
2
  "name": "@spatz/cli",
3
- "version": "0.1.5",
3
+ "version": "0.1.6-nightly.20261006.gd6cb139",
4
4
  "description": "Model and effort recommendations for coding agents",
5
5
  "bin": {
6
6
  "spatz": "bin/spatz.js"
7
7
  },
8
8
  "optionalDependencies": {
9
- "@spatz/cli-linux-x64": "0.1.5",
10
- "@spatz/cli-linux-arm64": "0.1.5",
11
- "@spatz/cli-darwin-arm64": "0.1.5",
12
- "@spatz/cli-darwin-x64": "0.1.5",
13
- "@spatz/cli-win32-x64": "0.1.5"
9
+ "@spatz/cli-linux-x64": "0.1.6-nightly.20261006.gd6cb139",
10
+ "@spatz/cli-linux-arm64": "0.1.6-nightly.20261006.gd6cb139",
11
+ "@spatz/cli-darwin-arm64": "0.1.6-nightly.20261006.gd6cb139",
12
+ "@spatz/cli-darwin-x64": "0.1.6-nightly.20261006.gd6cb139",
13
+ "@spatz/cli-win32-x64": "0.1.6-nightly.20261006.gd6cb139"
14
14
  },
15
15
  "engines": {
16
16
  "node": ">=18"