@zerotimedev/thinker 0.0.0-stage → 0.1.37

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yoav Shmariahu
+
+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,3 +1,15 @@
-# Temporary Holding Version
+# @zerotimedev/thinker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Installs [thinker](https://github.com/yoavshmariahu/thinker), a knowledge cache for coding agents.
+
+```bash
+npx @zerotimedev/thinker
+```
+
+The package carries thinker's installer and runs it. It downloads the latest thinker release, verifies it
+against the release's sha256, installs it into `~/.thinker`, wires it into the coding agents on
+the machine and opens the warm-up page. The installer's options pass through, for example
+`npx @zerotimedev/thinker --uninstall`.
+
+Requires bash, git, curl, tar and Node 20+. After the install, `thinker update` and the daily
+auto-update keep the tool current; npm is not involved again.

package/install.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// npx @zerotimedev/thinker: runs the installer this package carries (install.sh), with the
+// arguments passed through. Nothing of thinker runs from
+// the npx cache, which npm may clear: the installer puts the tool in THINKER_HOME (~/.thinker),
+// where the hooks and `thinker update` find it. scripts/pack.sh copies install.sh in beside this
+// file and sets the version; the package is not meant to be installed as a dependency.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const script = path.join(path.dirname(fileURLToPath(import.meta.url)), 'install.sh');
+const die = (msg) => { process.stderr.write(`thinker: ${msg}\n`); process.exit(1); };
+if (!fs.existsSync(script)) die(`the installer is missing from this package (${script})`);
+
+const r = spawnSync('bash', [script, ...process.argv.slice(2)], { stdio: 'inherit' });
+if (r.error?.code === 'ENOENT') {
+  die(process.platform === 'win32'
+    ? 'the installer is a bash script: run this from WSL or Git Bash'
+    : 'bash is required to run the installer');
+}
+if (r.error) die(r.error.message);
+if (r.signal) process.kill(process.pid, r.signal);
+process.exit(r.status ?? 1);

package/install.sh

@@ -0,0 +1,410 @@
+#!/usr/bin/env bash
+# thinker install: installs the thinker tool and wires it into the coding agents on
+# this machine (their own settings: hooks and the MCP server, once). Thinker then
+# runs in every git repository on this machine: a cache starts with the first
+# session in a repository, and the warm-up page that opens at the end (thinker ui)
+# builds caches for the repositories your agents have worked in, from their merged
+# pull requests. Nothing is asked in the terminal.
+#
+# Thinker is open source; no access code or GitHub token is required. It installs the latest
+# GitHub release (https://github.com/yoavshmariahu/thinker/releases: a tag vX.Y.Z carrying
+# thinker.tgz, version.json and install.sh), verified against the sha256 in version.json.
+#
+#   npx @zerotimedev/thinker
+#
+# The npm package of that name carries this file and runs it with the arguments passed through.
+#
+# --build from inside a repository builds its cache right here, in the terminal,
+# instead of opening the page. If a cache was already built for the repository,
+# pass --cache instead and nothing has to be built.
+#
+# Options
+#   --build             build the cache of this repository now, in the terminal (the page is not opened)
+#   --no-build          accepted from old scripts: nothing is built without --build anyway
+#   --no-seed, --areas <n>   accepted from old scripts and ignored: a build no longer explores the code
+#   --no-behaviors      accepted from old scripts and ignored: there is no behaviors prompt to print
+#   --depth <d>         with --build: full (default) or shallow, 30% of the full build
+#   --prs <n>           with --build: merged pull requests to mine (default 60; skipped without the gh CLI)
+#   --pr <number>       specific PR number to target for the paired benchmark
+#   --benchmark         run paired PR benchmark during setup
+#   --no-benchmark      skip the paired PR benchmark step
+#   -y, --yes           accept defaults and skip interactive confirmation prompts
+#   --clients <list>    coding agents to wire up: claude, codex, cursor, gemini, pi, windsurf, copilot, opencode, all or auto
+#                       (default auto)
+#   --cache <source>    cache built for this repo. One of: gh:<path in the thinker repo>, an https URL, a local file.
+#                       Omit if .thinker/notes is already in the repo.
+#   --no-learn          do not distill your own sessions into new notes (learning is on by default, for any of the
+#                       agents, and uses that agent's login; switch it off for evals)
+#   --late              also serve notes about files as the agent opens them
+#   --mcp               accepted for compatibility: the MCP server is always registered (needs npm)
+#   --no-git-hook       do not install the git post-commit hook (it re-checks and maintains notes after each commit)
+#   --ref <tag>         release to install, a tag such as v0.1.34 (default latest; --branch also accepted)
+#   --update            update an installed thinker to the latest release and exit
+#   --no-auto-update    do not schedule daily background auto-updates
+#   --no-modify-path    do not add THINKER_HOME/bin to PATH in your shell's startup file
+#   --uninstall         remove hooks and registration from this repo (add --purge to delete notes too); run outside
+#                       a repository, it removes the wiring from your agents' own settings
+#
+# Environment
+#   THINKER_HOME        where the tool is installed (default ~/.thinker)
+#   THINKER_GH_REPO     GitHub repository whose releases to install from (default yoavshmariahu/thinker)
+#   THINKER_REF         release tag (default latest)
+#   THINKER_DIST_URL    install from this tarball URL (with version.json beside it) instead of a GitHub release
+#   GITHUB_TOKEN        only for --cache gh:<path>: a token for the GitHub API (GH_TOKEN works too;
+#                       if neither is set and the GitHub CLI is logged in, its token is used)
+#
+# The script writes to THINKER_HOME, to .thinker/ and the agents' config in this repository, and adds one
+# line putting THINKER_HOME/bin on PATH to your shell's startup file (--no-modify-path leaves it alone). No sudo.
+set -euo pipefail
+export COPYFILE_DISABLE=1
+export COPY_EXTENDED_ATTRIBUTES_DISABLE=1
+
+# add_to_path <dir>: put <dir> on PATH in the startup file of the user's shell, once.
+# Prints the file it wrote to, or nothing when it could not tell which one.
+add_to_path() {
+  local dir="$1" rc line
+  case "$(basename "${SHELL:-}")" in
+    zsh) rc="${ZDOTDIR:-$HOME}/.zshrc"; line="export PATH=\"$dir:\$PATH\"" ;;
+    bash) # macOS terminals start login shells, which read .bash_profile and not .bashrc
+      if [ "$(uname)" = Darwin ]; then rc="$HOME/.bash_profile"; else rc="$HOME/.bashrc"; fi
+      line="export PATH=\"$dir:\$PATH\"" ;;
+    fish) rc="${XDG_CONFIG_HOME:-$HOME/.config}/fish/conf.d/thinker.fish"; line="fish_add_path \"$dir\"" ;;
+    *) return 0 ;;
+  esac
+  if ! grep -qsF "$line" "$rc"; then
+    mkdir -p "$(dirname "$rc")" && printf '\n# thinker\n%s\n' "$line" >> "$rc" || return 0
+  fi
+  printf '%s' "$rc"
+}
+
+# path_hint: how to reach `thinker` from this shell; reads main's $home and $rcfile
+path_hint() {
+  case ":$PATH:" in
+    *":$home/bin:"*) ;;
+    *) if [ -n "$rcfile" ]; then say "  'thinker' is on your PATH in new terminals (added to $rcfile); in this one run: export PATH=\"$home/bin:\$PATH\""
+       else say "  Optional: add $home/bin to your PATH to run 'thinker' directly."; fi ;;
+  esac
+}
+
+main() {
+  local cache="" build="" areas="" depth="" prs="" clients="" learn=1 late=0 mcp=0 githook=0 uninstall=0 purge=0 update=0 autoupdate=1 modpath=1 ref="${THINKER_REF:-latest}" benchmark="" pr_target="" yes=0 no_seed=0
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --cache) cache="${2:-}"; build=0; shift 2 ;;
+      --build) build=1; shift ;;
+      --no-build) build=0; shift ;;
+      --no-seed) shift ;;
+      --no-behaviors) shift ;;
+      -y|--yes) yes=1; shift ;;
+      --areas) shift 2 ;;
+      --depth) depth="${2:-}"; shift 2 ;;
+      --prs) prs="${2:-}"; shift 2 ;;
+      --pr) pr_target="${2:-}"; shift 2 ;;
+      --benchmark) benchmark=1; shift ;;
+      --no-benchmark) benchmark=0; shift ;;
+      --clients) clients="${2:-}"; shift 2 ;;
+      --branch|--ref) ref="${2:-}"; shift 2 ;;
+      --learn) learn=1; shift ;;
+      --no-learn) learn=0; shift ;;
+      --late) late=1; shift ;;
+      --shared) echo "Team sharing is no longer supported." >&2; return 1 ;;
+      --mcp) mcp=1; shift ;;
+      --git-hook) githook=1; shift ;;
+      --no-git-hook) githook=0; shift ;;
+      --update) update=1; shift ;;
+      --auto-update) autoupdate=1; shift ;;
+      --no-auto-update) autoupdate=0; shift ;;
+      --no-modify-path) modpath=0; shift ;;
+      --uninstall) uninstall=1; shift ;;
+      --purge) purge=1; shift ;;
+      -h|--help) echo "see the header of install.sh or ONBOARDING.md for options"; exit 0 ;;
+      *) echo "unknown option: $1" >&2; exit 2 ;;
+    esac
+  done
+
+  local home="${THINKER_HOME:-$HOME/.thinker}"
+  local ghrepo="${THINKER_GH_REPO:-yoavshmariahu/thinker}"
+  local ref="${ref:-${THINKER_REF:-latest}}"
+  local dist="${THINKER_DIST_URL:-}"
+  # the GitHub release for the ref: the latest one, or the tag named
+  if [ -z "$dist" ]; then
+    case "$ref" in
+      latest|main) dist="https://github.com/$ghrepo/releases/latest/download/thinker.tgz" ;;
+      *) dist="https://github.com/$ghrepo/releases/download/$ref/thinker.tgz" ;;
+    esac
+  fi
+  local token="${GITHUB_TOKEN:-${GH_TOKEN:-}}"
+  say() { printf '%s\n' "$*"; }
+  die() { printf 'thinker: %s\n' "$*" >&2; exit 1; }
+  # --- look: colors, boxes and spinners on a terminal, plain lines anywhere else --------------
+  local fancy=0 bold="" dim="" cyan="" green="" yellow="" red="" magenta="" reset=""
+  if [ -t 1 ] && [ -z "${NO_COLOR:-}" ] && [ "${TERM:-}" != dumb ] && [ -z "${CI:-}" ]; then
+    fancy=1 bold=$'\033[1m' dim=$'\033[2m' cyan=$'\033[36m' green=$'\033[32m' yellow=$'\033[33m' red=$'\033[31m' magenta=$'\033[35m' reset=$'\033[0m'
+  fi
+  # box <color> <line>...: a rounded box 74 columns wide, as setup draws it; a line may carry color codes, padded on its plain text
+  # box <color> <line>...: the lines in a rounded frame, at least 68 columns wide and as wide as the
+  # longest line (a path can run past 68, and a frame narrower than its text comes out ragged)
+  box() {
+    local color="$1"; shift
+    local width=68 line plain
+    for line in "$@"; do
+      plain="$(printf '%s' "$line" | sed $'s/\033\\[[0-9;]*m//g')"
+      [ "${#plain}" -gt "$width" ] && width=${#plain}
+    done
+    printf '%s╭%s╮%s\n' "$color" "$(printf '─%.0s' $(seq 1 $((width + 4))))" "$reset"
+    for line in "$@"; do
+      plain="$(printf '%s' "$line" | sed $'s/\033\\[[0-9;]*m//g')"
+      printf '%s│%s  %s%*s  %s│%s\n' "$color" "$reset" "$line" $((width - ${#plain})) "" "$color" "$reset"
+    done
+    printf '%s╰%s╯%s\n' "$color" "$(printf '─%.0s' $(seq 1 $((width + 4))))" "$reset"
+  }
+  # spin <label> <command...>: runs the command with a turning frame and the time so far, then a ✓ or ✗
+  # line; its output is kept and shown only if it fails. Off a terminal: the label, then the command.
+  spin() {
+    local label="$1"; shift
+    if [ "$fancy" != 1 ]; then say "  ${label}…"; "$@"; return; fi
+    local log; log="$(mktemp)"
+    "$@" >"$log" 2>&1 &
+    local pid=$! i=0 start=$SECONDS code=0
+    local frames=(⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏)
+    while kill -0 "$pid" 2>/dev/null; do
+      printf '\r\033[2K  %s%s%s %s %s· %ss%s' "$cyan" "${frames[$((i % 10))]}" "$reset" "$label" "$dim" "$((SECONDS - start))" "$reset"
+      i=$((i + 1)); sleep 0.1
+    done
+    wait "$pid" || code=$?
+    if [ "$code" -eq 0 ]; then
+      printf '\r\033[2K  %s✓%s %s %s· %ss%s\n' "$green" "$reset" "$label" "$dim" "$((SECONDS - start))" "$reset"
+    else
+      printf '\r\033[2K  %s✗%s %s\n' "$red" "$reset" "$label"
+      cat "$log" >&2
+    fi
+    rm -f "$log"
+    return "$code"
+  }
+  # the GitHub CLI is optional: it is only asked for a token when none is set
+  if [ -z "$token" ] && command -v gh >/dev/null; then token="$(gh auth token 2>/dev/null || true)"; fi
+  # gh_fetch <api endpoint in the thinker repo> <output file>
+  gh_fetch() {
+    local url="https://api.github.com/$1" out="$2"
+    if [ -n "$token" ]; then
+      curl -fsSL -H "Authorization: Bearer $token" -H "Accept: application/vnd.github.raw" -o "$out" "$url" && return 0
+      die "could not download $url with the token provided (does it have read access to $ghrepo?)"
+    fi
+    curl -fsSL -H "Accept: application/vnd.github.raw" -o "$out" "$url" 2>/dev/null && return 0
+    die "could not download $url: check connectivity and the repository/ref, or set GITHUB_TOKEN if GitHub rate-limits the request"
+  }
+
+  # --- prerequisites -----------------------------------------------------
+  command -v git >/dev/null || die "git is required"
+  command -v node >/dev/null || die "Node.js 20 or newer is required (https://nodejs.org)"
+  command -v curl >/dev/null || die "curl is required"
+  command -v tar >/dev/null || die "tar is required"
+  local nodemajor; nodemajor="$(node -p 'process.versions.node.split(".")[0]')"
+  [ "$nodemajor" -ge 20 ] || die "Node.js 20 or newer is required (found $(node -v))"
+  # outside a git repository only the tool is installed; `thinker setup` sets a repository up later
+  local repo; repo="$(git rev-parse --show-toplevel 2>/dev/null)" || repo=""
+  [ -n "$repo" ] && cd "$repo"
+  [ -n "$cache" ] && [ -z "$repo" ] && die "--cache needs a repository to put the cache in: run this from inside it"
+
+  local thinker="$home/bin/thinker"
+
+  if [ "$uninstall" = 1 ]; then
+    [ -x "$thinker" ] || die "thinker is not installed in $home"
+    if [ -z "$repo" ]; then "$thinker" uninstall --user
+    elif [ "$purge" = 1 ]; then "$thinker" uninstall --purge --repo "$repo"; else "$thinker" uninstall --repo "$repo"; fi
+    say "To remove the tool itself: rm -rf \"$home\", and delete the '# thinker' PATH line from your shell's startup file"
+    exit 0
+  fi
+
+  if [ "$update" = 1 ]; then
+    [ -x "$thinker" ] || die "thinker is not installed in $home"
+  fi
+
+  # --- install the tool ----------------------------------------------------
+  local tmp; tmp="$(mktemp -d)"
+  # expand now: the variable is local and gone by the time the trap runs
+  # shellcheck disable=SC2064
+  trap "rm -rf '$tmp'" EXIT
+  say ""
+  if [ "$fancy" = 1 ]; then
+    local sparkle="${yellow}*${reset} ${magenta}~${reset} ${yellow}*${reset}"
+    box "$cyan" "$sparkle  ${bold}${cyan}Thinker${reset}  $sparkle" "${bold}A knowledge cache for coding & review agents${reset}" \
+      "${magenta}~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~${reset}" "" \
+      "${dim}Learns from your merged fixes, flags the change that would undo one,${reset}" \
+      "${dim}and hands your coding agents what the repository already knows.${reset}"
+  else
+    say "Thinker"
+    say "A knowledge cache for coding & review agents"
+  fi
+  say ""
+  case "$dist" in https://*) ;; *) die "releases must be downloaded over HTTPS" ;; esac
+  # GitHub answers with a redirect to its asset host; curl follows it over HTTPS only
+  download_release() {
+    curl -fsSL --proto-redir '=https' -o "$tmp/thinker.tgz" "$dist" &&
+      curl -fsSL --proto-redir '=https' -o "$tmp/version.json" "${dist%/*}/version.json"
+  }
+  spin "Downloading the release" download_release || die "could not download $dist or its version.json (is there a release for $ref at https://github.com/$ghrepo/releases?)"
+  say "  Verifying download…"
+  node --input-type=module - "$tmp/thinker.tgz" "$tmp/version.json" <<'JS'
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+const [archive, manifest] = process.argv.slice(2);
+const release = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+if (release.schemaVersion !== 1 || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(release.version || '') ||
+    !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(release.commit || '') || !/^[a-f0-9]{64}$/.test(release.sha256 || '')) {
+  throw new Error('invalid or unsupported release manifest');
+}
+const actual = crypto.createHash('sha256').update(fs.readFileSync(archive)).digest('hex');
+if (actual !== release.sha256) throw new Error('release checksum mismatch; refusing to extract');
+JS
+  tar_extract() {
+    local archive="$1" dest="$2"
+    local warn_opt=""
+    if tar --warning=no-unknown-keyword --version >/dev/null 2>&1; then
+      warn_opt="--warning=no-unknown-keyword"
+    fi
+    local code=0
+    local err
+    # shellcheck disable=SC2086
+    err="$(COPYFILE_DISABLE=1 COPY_EXTENDED_ATTRIBUTES_DISABLE=1 tar ${warn_opt} -xzf "$archive" -C "$dest" 2>&1)" || code=$?
+    if [ -n "$err" ]; then
+      local filtered
+      filtered="$(printf '%s\n' "$err" | grep -v "Ignoring unknown extended header keyword" || true)"
+      if [ -n "$filtered" ]; then
+        printf '%s\n' "$filtered" >&2
+      fi
+    fi
+    [ "$code" -eq 0 ] || return "$code"
+  }
+
+  say "  Installing CLI…"
+  mkdir -p "$tmp/app" && tar_extract "$tmp/thinker.tgz" "$tmp/app"
+  # GitHub archives wrap everything in one top-level directory
+  if [ ! -f "$tmp/app/src/cli.js" ]; then
+    local inner; inner="$(find "$tmp/app" -mindepth 1 -maxdepth 1 -type d | head -1)"
+    [ -n "$inner" ] && [ -f "$inner/src/cli.js" ] || die "downloaded archive does not look like thinker"
+    mv "$inner" "$tmp/app.inner" && rm -rf "$tmp/app" && mv "$tmp/app.inner" "$tmp/app"
+  fi
+  node --input-type=module - "$tmp/app/package.json" "$tmp/version.json" <<'JS'
+import fs from 'node:fs';
+const pkg = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+const release = JSON.parse(fs.readFileSync(process.argv[3], 'utf8'));
+if (pkg.version !== release.version) throw new Error(`release version ${release.version} does not match archive version ${pkg.version}`);
+JS
+  # --update: the downloaded copy's updater installs itself, so an older install (one that still
+  # downloads from the old host, say) moves to the releases. The home and its settings are kept.
+  if [ "$update" = 1 ]; then
+    node --input-type=module - "$tmp/app/src/update.js" "$home" "$dist" "$ref" <<'JS'
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+const [modulePath, home, dist, ref] = process.argv.slice(2);
+const { applyUpdate } = await import(pathToFileURL(modulePath));
+const result = await applyUpdate({ home, rootDir: path.join(home, 'app'), dist, ref });
+console.log(`Updated thinker to v${result.version}`);
+JS
+    exit 0
+  fi
+  # the tool needs only its source and manifest at runtime
+  rm -rf "$tmp/app/bench" "$tmp/app/test" "$tmp/app/caches"
+  mkdir -p "$home/bin"
+  rm -rf "$home/app.new" && mv "$tmp/app" "$home/app.new"
+  rm -rf "$home/app.old"; [ -d "$home/app" ] && mv "$home/app" "$home/app.old"
+  mv "$home/app.new" "$home/app" && rm -rf "$home/app.old"
+  cat > "$thinker" <<SHIM
+#!/bin/sh
+exec node "$home/app/src/cli.js" "\$@"
+SHIM
+  chmod +x "$thinker"
+  cat > "$home/install.json" <<EOF
+{
+  "source": "archive",
+  "ghrepo": "$ghrepo",
+  "ref": "$ref",
+  "dist": "$dist",
+  "installedAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+}
+EOF
+  if [ "$autoupdate" = 1 ]; then
+    "$thinker" update --schedule --quiet 2>/dev/null || true
+  fi
+  local rcfile=""
+  if [ "$modpath" = 1 ]; then rcfile="$(add_to_path "$home/bin")"; fi
+
+  # whatever agents are on this machine are wired up, in their own settings
+  [ -z "$clients" ] && clients="auto"
+  # The dependencies are always installed: the hooks rank notes with a local cross-encoder whose runtime is one
+  # of them, and the MCP server, registered for every agent, needs its SDK. Without npm the hooks still work,
+  # ranking by words alone, and the MCP server is left out (thinker connect registers it once npm ci has run).
+  if command -v npm >/dev/null; then
+    mcp=1
+    install_deps() { cd "$home/app" && npm ci --omit=dev --ignore-scripts --no-audit --no-fund --silent; }
+    spin "Installing dependencies (the ranking runtime is most of it)" install_deps || die "npm ci failed in $home/app"
+    spin "Fetching the ranking model" "$thinker" ranker fetch --quiet || say "  The ranking model could not be fetched (offline?); notes are ranked by words until 'thinker ranker fetch' succeeds."
+  else
+    say "npm was not found: the dependencies were not installed (cd \"$home/app\" && npm ci --omit=dev --ignore-scripts, then thinker ranker fetch and thinker connect). Notes are ranked by words alone until then."
+    mcp=0
+  fi
+
+  # --- wire the agents, once, in their own settings ---------------------------
+  # Nothing is asked here: Codex's hook-review marks are written outright, and every other choice
+  # (which repositories to build a cache for, how deep, with which model) is made on the warm-up
+  # page that opens next. Thinker then runs in every git repository on this machine.
+  local cargs="--clients $clients --yes"
+  [ "$learn" = 1 ] || cargs="$cargs --no-learn"
+  [ "$late" = 1 ] && cargs="$cargs --late"
+  [ "$mcp" = 1 ] || cargs="$cargs --no-mcp"
+  # shellcheck disable=SC2086
+  "$thinker" connect $cargs
+
+  # --- a cache handed over, or a build asked for by flag -------------------------
+  if [ -n "$cache" ]; then
+    case "$cache" in
+      gh:*) gh_fetch "repos/$ghrepo/contents/${cache#gh:}?ref=$ref" "$tmp/cache.tgz"; "$thinker" import "$tmp/cache.tgz" --repo "$repo" ;;
+      *) "$thinker" import "$cache" --repo "$repo" ;;
+    esac
+  elif [ "$build" = 1 ] && [ -n "$repo" ]; then
+    # --build from inside a repository: the build runs here, without the page, as before
+    local args="--build --yes --no-ui"
+    [ -n "$clients" ] && args="$args --clients $clients"
+    [ "$learn" = 1 ] || args="$args --no-learn"
+    [ "$githook" = 0 ] && args="$args --no-git-hook"
+    [ "$mcp" = 1 ] || args="$args --no-mcp"
+    [ -n "$depth" ] && args="$args --depth $depth"
+    [ -n "$prs" ] && args="$args --prs $prs"
+    [ -n "$pr_target" ] && args="$args --pr $pr_target"
+    [ "$benchmark" = 1 ] && args="$args --benchmark"
+    [ "$benchmark" = 0 ] && args="$args --no-benchmark"
+    # shellcheck disable=SC2086
+    THINKER_INSTALLER=1 "$thinker" setup $args --repo "$repo"
+  fi
+
+  # --- the warm-up page -----------------------------------------------------------
+  # The page lists the repositories your agents have worked in; pick the ones to build a cache for.
+  # Opened detached (the server exits on its own once idle); not from CI or a pipe with no terminal.
+  local opened=0
+  if [ -z "${CI:-}" ] && [ -t 1 ] && [ "$build" != 1 ]; then
+    ( "$thinker" ui --from-setup --tab warmup >/dev/null 2>&1 & ) && opened=1
+  fi
+  local version; version="$(node -p "require('$home/app/package.json').version" 2>/dev/null || echo '?')"
+  path_hint
+  say ""
+  local how="Pick the repositories to warm up on the page that just opened"
+  [ "$opened" = 1 ] || how="Pick the repositories to warm up: ${cyan}thinker ui${reset}"
+  if [ "$fancy" = 1 ]; then
+    box "$green" "${green}✓${reset} ${bold}Install complete${reset} ${dim}· Thinker v$version${reset}" "" \
+      "Installed into ${home/#$HOME/~} and wired into your agents." \
+      "Thinker now runs in every git repository on this machine." \
+      "$how" \
+      "${dim}(open it again any time with thinker ui).${reset}" \
+      "${dim}Notes stay on this machine; Thinker uploads none.${reset}" "" \
+      "${yellow}*${reset} ${magenta}~${reset} ${yellow}*${reset}  ${bold}all done · happy shipping${reset}  ${yellow}*${reset} ${magenta}~${reset} ${yellow}*${reset}"
+  else
+    say "Install complete: Thinker v$version, installed into $home and wired into your agents."
+    say "Thinker now runs in every git repository on this machine."
+    if [ "$opened" = 1 ]; then say "Pick the repositories to warm up on the page that just opened (open it again any time with thinker ui)."
+    else say "Pick the repositories to warm up: thinker ui"; fi
+    say "Notes stay on this machine; Thinker uploads none."
+  fi
+}
+
+main "$@"

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@zerotimedev/thinker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.37",
+  "description": "Installer for thinker, a knowledge cache for coding agents: npx @zerotimedev/thinker",
+  "type": "module",
+  "bin": {
+    "thinker-install": "install.mjs"
+  },
+  "files": [
+    "install.mjs",
+    "install.sh"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yoavshmariahu/thinker.git"
+  },
+  "homepage": "https://github.com/yoavshmariahu/thinker#readme",
+  "license": "MIT"
+}