Open History to see the last commit
1---
2title: intent hooks
3id: intent-hooks
4---
5
6`intent hooks install` installs lifecycle hooks that surface available Intent skills and gate supported edit tools until they observe an Intent guidance check.
7
8<!-- ::start:tabs variant="package-manager" mode="local-install" -->
9
10@tanstack/intent@latest hooks install [--scope project|user] [--agents copilot,claude,codex|all]
11
12<!-- ::end:tabs -->
13
14## Options
15
16- `--scope <scope>`: hook install scope, either `project` or `user`; defaults to `project`
17- `--agents <agents>`: comma-separated hook agents to configure (`copilot`, `claude`, `codex`) or `all`; defaults to `all`
18
19## Behavior
20
21### Session behavior
22
23- Installs hook behavior without writing an `intent-skills` guidance block.
24- Returns a session-start skill catalog as agent context with available `skill-id: description` entries.
25- Builds that catalog with the project's installed `@tanstack/intent` CLI when one is resolvable from `node_modules`. When that same installation has a `node_modules/.bin/intent` shim, the catalog suggests `node_modules/.bin/intent load <skill-id>` for loads; without a shim, or without a local install, it suggests the package-manager runner generated by Intent. Without a local install the catalog itself is also built through that runner.
26- Blocks supported edit tools until the hook observes a recognized `intent list` or `intent load <skill-id>` command, including the `node_modules/.bin/intent` form. If no listed skill matches the task, the agent can continue without loading one.
27- Uses `package.json#intent.skills` and `package.json#intent.exclude` to control which skills appear in the session catalog.
28
29### Installation behavior
30
31- `--scope project` writes project-local hook config for agents that support it.
32- `--scope user` writes user-level agent config and stores runner scripts under `~/.tanstack/intent/hooks`.
33- `--agents all` is the default. In project scope, Copilot is skipped because the supported Copilot CLI hook location is user-scoped.
34- Run `intent install` separately when you also want to write project guidance.
35
36The hook records a recognized list or load command before that command completes.
37
38Hooks do not verify that:
39
40- The command succeeded.
41- The selected skill matched the task.
42- The agent received the returned content.
43- The model applied the guidance.
44
45Hook output is an edit gate and observation signal, not proof of activation or correct agent behavior. See [Lifecycle boundaries](../concepts/trust-model#lifecycle-boundaries).
46
47## Hook support
48
49| Agent | Project scope | User scope | Hooks installed |
50| --- | --- | --- | --- |
51| Claude Code | `.claude/settings.json` | `~/.claude/settings.json` | `SessionStart` skill catalog plus `PreToolUse` edit gate |
52| Codex | `.codex/hooks.json` | `~/.codex/hooks.json` | `SessionStart` skill catalog plus `PreToolUse` edit gate; Codex hook interception is not a complete security boundary |
53| GitHub Copilot CLI | Guidance via `.github/copilot-instructions.md`; blocking hooks are not project-scoped | `$COPILOT_HOME/hooks/hooks.json` or `~/.copilot/hooks/hooks.json` | `SessionStart` skill catalog plus `PreToolUse` edit gate in user scope |
54| Cursor | Guidance only | Guidance only | Use `AGENTS.md` or Cursor rules; no blocking hook is installed |
55| Generic `AGENTS.md` agents | Guidance only | Guidance only | Use the `intent-skills` guidance block; no blocking hook is installed |
56
57`.github/copilot-instructions.md` is a supported project guidance target for `intent install`. GitHub Copilot CLI hook enforcement uses the user-scoped Copilot hooks directory because that is the supported hook location.
58
59Codex requires users to review and trust non-managed hooks before they run. If Codex reports hooks awaiting review, open its hook browser and trust the generated Intent hook.
60
61## Status messages
62
63- Hook installed: `Installed Intent hooks for claude (project) in .claude/settings.json.`
64- Hook skipped: `Skipped Intent hooks for copilot: project scope is not supported; use --scope user`
65
66## Related
67
68- [intent install](./intent-install)
69- [intent list](./intent-list)
70- [intent load](./intent-load)