[install] — setup hooks

[install]
commands = [
  "uv sync",
  "./scripts/fetch-reference-data.sh"
]

Fields

commands (list of strings)

Shell commands to run during rig install, in order. Each runs in the workspace root with the standard PATH.

Hooks are not executed by default. The user must opt in with --run-hooks or accept the interactive confirmation prompt. The reason is simple: hooks are arbitrary code from a rig author.

When the user gets asked

rig install

If [install].commands is non-empty and you're in an interactive terminal, rig prints:

This rig declares install hooks:
  1. uv sync
  2. ./scripts/fetch-reference-data.sh

Run them? [y/N]

y runs them; anything else skips. To run without prompting:

rig install --run-hooks
rig install --yes --run-hooks   # also accept other defaults

To install without ever running hooks (e.g. in untrusted CI):

rig install   # interactive prompt defaults to skip
# or
rig install --yes   # --yes does not imply --run-hooks

Authoring guidance

Make hooks idempotent. rig install is meant to be safe to re-run. A hook that downloads to a temp file, hashes, and only copies on change is fine; one that appends to a log every time is not.

Document side effects. README the hooks loudly. The user is opting in to running them.

Prefer narrow commands. uv sync is better than bash setup-everything.sh. The user can read the former.

Use install hooks for environment setup, not for state mutation. Fetching reference data, syncing dependencies, materialising templates — fine. Calling out to external APIs, sending telemetry, mutating user state — not fine.

Use [run], not [install], for things that run every session. [install] is for one-time setup.

What the agent does

The agent skill is taught to treat install hooks as requiring explicit user approval. Claude Code will not run hooks without asking.

See also

• rig install flags
• Safety
• [run] — every-session entrypoint, not a hook.