Request
installSessionStartHooks() currently writes only to the user's home dir — ~/.claude/settings.json, ~/.codex/*, and the OpenCode plugin (via the homeDir option, default os.homedir()). There's no first-class way to install a project-scoped hook into <cwd>/.claude/settings.json.
It'd be great to support a scope/target option, e.g.:
installSessionStartHooks({ scope: "project" }) // -> <cwd>/.claude/settings.json
installSessionStartHooks({ scope: "global" }) // -> ~/.claude/settings.json (current behavior)
// or a lower-level: installSessionStartHooks({ targetDir, apps: ["claude-code"] })Use case
Building an AXI CLI bundled inside a Claude Code skill, we want an opt-in ambient hook that some users install per-project (committed .claude/settings.json so a team shares it) rather than globally. Two gaps make installSessionStartHooks not directly usable for that:
- It only targets
homeDir, so project scope isn't expressible (passing homeDir: cwd is a hack and also drags in .codex/ + the OpenCode plugin under the project).
- No way to limit which agents are written (we wanted Claude Code only for the project case).
Workaround
We reimplemented project/global install ourselves using the exported primitives — computeSessionStartHookUpdate() to merge the managed SessionStart hook into a chosen .claude/settings.json, plus our own command string. That works well (those exports are great!), but it means re-deriving the path resolution and uninstall logic that installSessionStartHooks already encapsulates.
Suggestion
Add a scope/targetDir option and an apps filter to installSessionStartHooks (and a matching uninstall helper) so project-scoped, single-agent installs are first-class. Happy to PR if the shape is agreed.
Request
installSessionStartHooks()currently writes only to the user's home dir —~/.claude/settings.json,~/.codex/*, and the OpenCode plugin (via thehomeDiroption, defaultos.homedir()). There's no first-class way to install a project-scoped hook into<cwd>/.claude/settings.json.It'd be great to support a scope/target option, e.g.:
Use case
Building an AXI CLI bundled inside a Claude Code skill, we want an opt-in ambient hook that some users install per-project (committed
.claude/settings.jsonso a team shares it) rather than globally. Two gaps makeinstallSessionStartHooksnot directly usable for that:homeDir, so project scope isn't expressible (passinghomeDir: cwdis a hack and also drags in.codex/+ the OpenCode plugin under the project).Workaround
We reimplemented project/global install ourselves using the exported primitives —
computeSessionStartHookUpdate()to merge the managed SessionStart hook into a chosen.claude/settings.json, plus our own command string. That works well (those exports are great!), but it means re-deriving the path resolution and uninstall logic thatinstallSessionStartHooksalready encapsulates.Suggestion
Add a
scope/targetDiroption and anappsfilter toinstallSessionStartHooks(and a matching uninstall helper) so project-scoped, single-agent installs are first-class. Happy to PR if the shape is agreed.