init

Temper: Set Up This Project

Goal: get a project fully set up in one command. Seeds .claude/temper.config, scaffolds .temper/, and installs the native commit gate — the one control that physically blocks git commit while a gate is red. Idempotent: safe to run any number of times; an existing config is never overwritten.

/temper runs this automatically the first time it's used in an un-set-up project, so most people never call /temper:init by hand — it's here for an explicit re-run.

Uninstall

When the arguments hold --uninstall, do nothing else: run ${CLAUDE_PLUGIN_ROOT}/scripts/temper guards uninstall, print what it says, and stop. It removes the Temper commit hook and its folder; the person runs it in a terminal while no run is active.

Steps

1. Paths. Plugin folder: the folder that holds ${CLAUDE_PLUGIN_ROOT}/scripts/temper (that
   path with /scripts/temper taken off); wherever a reference page writes the
   CLAUDE_PLUGIN_ROOT variable, use this folder. If that file does not exist, stop and
   say "Cannot locate the Temper plugin folder. Reinstall the plugin." Never search the
   disk for another copy. Every path below that is not in the plugin folder is in the
   user's project, the current directory. Nothing here writes into the plugin folder.
   Before anything is written, check the project folder, in this order:
   a. When it is the home folder, stop and say in one line: "The project folder is your
      home folder, which holds Claude Code's own files and is never a project. Run
      /temper:init from a project folder."
   b. Run ${CLAUDE_PLUGIN_ROOT}/scripts/temper status. When it prints a line that starts
      with "FAIL: run temper from a project folder", the CLI refused this folder (the
      home folder, an installed copy of the plugin, or a folder inside the plugin
      folder): stop and show that line, and write nothing. Any other result, "FAIL: no
      intent.md to report on" among them, means go on.

2. Config — .claude/temper.config:
   a. EXISTS → report "Temper config already present" and do NOT overwrite it (it's the
      user's). Check for retired blocks and keys and report what's now ignored:
        grep -nE '^(tokens|observability|capabilities|eval):' .claude/temper.config
      then, as two separate calls:
        ${CLAUDE_PLUGIN_ROOT}/scripts/temper config get models.routing
        ${CLAUDE_PLUGIN_ROOT}/scripts/temper config get models.tiers
      Print one "NOTE: '{key}:' block found, retired, now ignored" line per grep match,
      and one "NOTE: 'models.routing' found (the v6 routing table), retired, now
      ignored" line (or 'models.tiers') for each of the two calls that prints anything.
      A flat models: block (models.plan, models.build and so on) is the live per-stage
      model override, so it is never flagged. If nothing matches, print nothing.
      Read-only: never edits the file.
   b. MISSING → mkdir -p .claude, copy
      ${CLAUDE_PLUGIN_ROOT}/templates/temper.config.default → .claude/temper.config,
      report "Created .claude/temper.config from the default template."

3. Scaffold — run `${CLAUDE_PLUGIN_ROOT}/scripts/temper init` (creates .temper/: gates
   ledger, overrides log, feedback-loops registry). Idempotent.

4. Commit gate — the headline guarantee. Run:
      bash "${CLAUDE_PLUGIN_ROOT}/scripts/guards/install.sh"
   It installs a native git pre-commit hook that runs the secret scan and
   `${CLAUDE_PLUGIN_ROOT}/scripts/temper gate commit` on every commit, and fails open
   if Temper isn't in use for a commit. It keeps that hook in `temper-gate/pre-commit`
   in the repository's git folder (the folder `git rev-parse --git-common-dir` names,
   which every worktree of the repository shares; never committed, never in the plugin
   folder), written through a new file moved into place, and runs
   `git config --local core.hooksPath` with that folder's absolute path, so git runs
   the hook in every worktree. The `pre-commit` file in the folder `git rev-parse --git-path hooks`
   names, the file git runs as the pre-commit hook, is then the kept hook. It never writes into a
   folder named `hooks`: not git's own hooks folder, not the folder
   `git rev-parse --git-path hooks` names, and not a `core.hooksPath` folder that is
   not Temper's. It only reads the hooks there to decide. Its one other write is the
   file `temper-pre-commit` in the git folder, made current only when the user's hook
   holds the line Temper 9.6.5 printed.
   Once `core.hooksPath` is set, git stops running the hooks in its own hooks folder,
   so install.sh leaves `core.hooksPath` as it is when that would switch hooks of the
   user's off: when git's own hooks folder holds an executable hook under any of git's
   hook names (a `commit-msg`, git-lfs's `pre-push`, the pre-commit framework's or
   lefthook's hooks; an older Temper `pre-commit` does not count) or a
   `pre-commit.bak.<timestamp>` that an older installer set aside, and when
   `core.hooksPath` already names another tool's folder (husky's `.husky/_`,
   lefthook, a team folder). It still keeps the Temper hook, and the user's own
   pre-commit hook needs one line, with no path of this machine in it, to run it: the
   `pre-commit` file in git's hooks folder or in that tool's folder (for husky,
   `.husky/pre-commit`). A hook that holds that line, or the line Temper 9.6.5 printed
   (which runs `temper-pre-commit`), with no line before it that starts with `exit` or
   `exec`, calls the Temper hook: install.sh makes the kept hook current, says so and
   exits 0. When an `exit` or `exec` line comes first, the Temper line never runs, so
   install.sh refuses and says to move it above that line.
   A `core.hooksPath` that holds Temper's older folder (`.git/hooks-temper`, set by
   `--global` from 5.5.0 to 9.6.4; `.git/temper-git-hooks`, set by `--global` in
   9.6.5; or the `temper-gate` folder of where the repository used to be) is pointed
   at `temper-gate`, with a note naming the old value, unless that folder holds other
   hooks git runs (`git lfs install` writes its hooks into the folder `core.hooksPath`
   names): then it stays as it is, as for git's own hooks folder (a relative value is set
   to this repository's own older folder by its absolute path, so linked worktrees, and a
   moved or copied repository, reach it), and the
   `pre-commit` there needs the line. When that folder is the `temper-gate` folder of
   another repository that is still there (a copy), it refuses and says to point
   `core.hooksPath` at this repository's own folder, never to change that repository's
   hook. A host hook counts only when git can run it (executable; for husky v9, husky's own
   hook in `.husky/_` must be there and executable instead), and for the pre-commit
   framework and lefthook, a config file at the repository's top that holds the line
   outside a comment counts too (its text only, which the installer's line says). When husky's `.husky/_`
   holds a `pre-commit` from an older Temper, it refuses and says to run `npx husky`. When it installs while an older Temper hook sits in git's own
   hooks folder, it notes that git no longer runs that file and that it can be
   deleted. When it refuses while git still runs a `pre-commit` from an older Temper
   (next to other hooks, or in another tool's folder), it warns that git runs that
   hook in place of the kept one, with the stale plugin path it carries, and the hint
   says to replace all of its lines with `#!/bin/sh` and the line. `core.hooksPath`
   holds an absolute path, so every worktree finds the folder; after the repository,
   or a folder above it, is moved or renamed, git runs no pre-commit hook until
   `/temper` or `/temper:init` runs install.sh again, which points it at the new
   place. Re-running is idempotent: it makes the
   kept hook current, and says when it updated the plugin paths in it (as after a
   plugin upgrade, which moves the plugin folder). When an older version set a hook
   that was not Temper's aside as `pre-commit.bak.<timestamp>`, it names that file in
   a warning and says how to bring it back: move it back to `pre-commit` in git's
   hooks folder, then add to it the line it prints between its BEGIN and END lines.
   `--global` does the same as the default, with a note. It also prints how to
   uninstall: `temper guards uninstall` (or `/temper:init --uninstall`, or `install.sh --uninstall`) removes the Temper
   hook and the `temper-gate` folder (and any `temper-pre-commit` that 9.6.5 left), unsets `core.hooksPath` when it points
   at that folder and no other hook is left there, and names a Temper line in the user's own hook, which the user removes.
   A second run changes nothing. A hook tool added
   later needs `core.hooksPath` unset first: the pre-commit framework refuses to install
   while it is set, and lefthook installs into the folder it names, which is Temper's. The
   next `/temper` or `/temper:init` then keeps the Temper hook and prints the line to add.
   If a tool already wrote its `pre-commit` into Temper's folder, the installer refuses and
   its hint says how to move it out.
   Report by how it ended:
   a. Exit 0 → the gate is installed, was already installed (or was updated to the
      current plugin paths), or the user's own hook calls the Temper hook, which is
      now current; carry its line about that into the report. Carry each `Note:` and
      `Warning:` line it printed into the report too, with the restore steps and the
      line it printed after a warning about an old `pre-commit.bak.<timestamp>` file,
      in a fenced code block.
   b. Exit 1 with "FAIL: not inside a git repository" → report "not a git repo yet; run
      /temper:init again after `git init` to install the commit gate" and continue (the
      config + scaffold still succeeded).
   c. Any other non-zero exit → the commit gate is not installed. Report "commit gate
      not installed: {the FAIL reason}", or, when its output has no FAIL line, "commit
      gate not installed" followed by its whole output in a fenced code block. When its
      output says "The Temper hook is kept in {file}", say that install.sh kept the
      Temper hook in that file, in the repository's git folder (never committed), and
      wrote nothing else; otherwise say that it wrote nothing. Then, when it printed
      lines between its BEGIN and END lines, show them verbatim in a fenced code block,
      so the user has them to copy: one line that runs the Temper hook kept in the git
      folder, or, when it refused before it knew the git folder, the Temper hook's own
      lines in a subshell, so that their exits end only the subshell. Never only say
      that it printed them. Then carry each `Warning:` line it printed (a hook an older
      version set aside, or a `pre-commit` from an older Temper that git still runs,
      with its stale plugin path). Then give its `Hint:` line as it printed it. The
      hint says where the line goes: husky: `.husky/pre-commit`, safe to commit
      because the line holds no path of this machine; the pre-commit framework: a
      local hook in `.pre-commit-config.yaml` whose entry is `sh -c '<the line>'`, as
      the hint prints it, because the framework runs that entry with no shell;
      lefthook: a pre-commit command in `lefthook.yml`, because lefthook writes its
      hook again; a hook from an older Temper: in place of all of its lines, after
      `#!/bin/sh`; any other hook: its start or its end, because the line keeps that
      hook's own result (the hint says to create that file, executable, when it does
      not exist).
      install.sh refuses and exits 1 when git's own hooks folder holds hooks that git
      would stop running if `core.hooksPath` pointed at Temper's folder (its FAIL line
      names them), or a hook an older version set aside, and the `pre-commit` there
      does not call the Temper hook; when `core.hooksPath` names another tool's folder,
      or Temper's older folder that holds other hooks git runs, and the pre-commit hook
      there does not call the Temper hook; when the `pre-commit` in Temper's own folder is not
      Temper's (a hook tool such as lefthook wrote it there; the installer never writes over it,
      and its hint says how to move it out); when the user's hook holds the Temper line after an
      `exit` or `exec` line; when the repository, or a place it would write once
      symlinks are followed, lies inside the plugin's own folder; and when a folder or
      file it needs cannot be made. It ignores GIT_DIR, GIT_WORK_TREE and GIT_CONFIG,
      so it always works on the repository that holds the current folder. Continue (the
      config + scaffold still succeeded).

5. Agents in the foreground. Claude Code runs each Temper stage agent in the background (since
   v2.1.198; with fork mode on, always), and a run goes on only in the turn Claude Code starts
   when the agent finishes, which an idle session may not get. A plugin cannot change that, and
   Temper never edits a Claude Code settings file for it. Say in one line, in the report, that
   the person can keep agents in the foreground by setting `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`
   to `1` themselves, as `${CLAUDE_PLUGIN_ROOT}/docs/getting-started.md` ("Stage agents in the
   background") shows, and that any message moves a waiting run on.

6. Report done, and name the one optional add-on in a single line:
   "Set up. Optional: `/temper:pack enable guardrails` prints edit-time guardrails (secret
   blocking, frozen-path protection, auto-format, an approval prompt before overrides)
   for you to add to a project settings file. The commit gate above works without it."