@ascenda-one/claude-code-hooks 0.1.33 → 0.1.34

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -59,8 +59,8 @@ npx @ascenda-one/claude-code-hooks setup
59
59
 
60
60
  This pairs (printing a 6-digit code to confirm in the Ascenda app), installs a
61
61
  self-contained hook bundle to `~/.ascenda/bin`, writes
62
- `~/.ascenda/credentials.json`, and registers the hooks in this project's
63
- `.claude/settings.local.json`. Restart Claude Code and events flow — no shell
62
+ `~/.ascenda/credentials.json`, and registers the hooks in `~/.claude/settings.json`,
63
+ so they load in every project. Restart Claude Code and events flow — no shell
64
64
  exports, no settings file to hand-edit.
65
65
 
66
66
  ```bash
@@ -74,7 +74,7 @@ npx @ascenda-one/claude-code-hooks uninstall # removes hooks and the binary
74
74
  | `--local [port]` | shorthand for a local [dev server](../ascenda-dev-server/) (default `4477`) |
75
75
  | `--tool-installation-id <id>` / `--token <t>` | reuse an existing pairing instead of creating one |
76
76
  | `--no-pair` | install the local half only: hooks work, nothing is sent |
77
- | `--scope project\|user` | register in this project (default) or in `~/.claude/settings.json` |
77
+ | `--scope user\|project` | register in `~/.claude/settings.json` (default, every project) or in this project's `.claude/settings.local.json` |
78
78
  | `--project-dir <path>` | project root for `--scope project` (default cwd) |
79
79
  | `--dry-run` | print what would change, write nothing |
80
80
 
@@ -87,10 +87,12 @@ DevAuth. Stop it with `./scripts/setup-local.sh --stop`. See
87
87
 
88
88
  | Path | |
89
89
  | --- | --- |
90
- | `~/.ascenda/bin/ascenda-claude-hook` | the self-contained bundle — no `npm -g`, no sudo, no PATH edit |
90
+ | `~/.ascenda/bin/ascenda-claude-hook` | the launcher every hook command names: a small `sh` script that finds Node and runs the bundle |
91
+ | `~/.ascenda/bin/ascenda-claude-hook.mjs` | the self-contained bundle — no `npm -g`, no sudo, no PATH edit |
92
+ | `~/.ascenda/bin/ascenda-claude-hook.node` | the Node the launcher last found, starting with the one that ran setup |
91
93
  | `~/.ascenda/credentials.json` | `apiBaseUrl` + `toolInstallationId`, `0600` (plus `localOnly` on an install with no pairing) |
92
94
  | `~/.ascenda/tokens/<id>` | the event write token, `0600`, rotated in place on renew |
93
- | `.claude/settings.local.json` | one hook entry per lifecycle event, `timeout: 5` |
95
+ | `~/.claude/settings.json` | one hook entry per lifecycle event, `timeout: 5` (`.claude/settings.local.json` under `--scope project`) |
94
96
 
95
97
  Registration is idempotent and marker-keyed: re-running replaces our entries
96
98
  rather than appending, hooks belonging to anyone else are left alone, and the
@@ -114,35 +116,36 @@ Code afterwards: a session keeps the hooks it started with.
114
116
 
115
117
  If you use the plugin, run `claude plugin update ascenda@ascenda-one` instead.
116
118
  Its `hooks.json` registers the same set. Having both the plugin and a `setup` install runs every hook
117
- twice, and `setup` warns when the other scope already registers them.
118
-
119
- Hooks then need **no environment at all**: the command pins the absolute path
120
- of the Node that ran setup, and configuration comes from the credentials file.
121
- Claude Code spawns hooks with whatever environment it was launched from, so
122
- anything depending on shell exports stops working the moment the editor is
123
- opened from a launcher rather than a terminal. The variables below still
124
- override the file when set.
119
+ twice. `setup` moves its own entries out of the other scope's file (and out of
120
+ `~/.claude/settings.local.json`, where a project install run from the home
121
+ folder used to put them, loading only when Claude Code started in `~`), but it
122
+ can't remove the plugin's.
123
+
124
+ Hooks then need **no environment at all**. The command names the launcher, and
125
+ the launcher finds Node: the one that ran setup while it's still there, and
126
+ otherwise the first Node 20 or newer on `PATH`, in Homebrew, volta, nvm's
127
+ default alias, fnm, asdf or mise, which it records for next time. So a hook
128
+ keeps working when Claude Code is opened from the Dock or an IDE, and after a
129
+ version manager removes the Node that ran setup. If there is no Node at all,
130
+ `SessionStart` says so once and the other hooks stay quiet. Configuration comes
131
+ from the credentials file; the variables below still override it when set.
125
132
 
126
133
  `status` also flags hook entries pointing at a binary that no longer exists —
127
- those fail silently on every event otherwise. It checks one scope, defaulting
128
- to `project` like `setup`; if it finds nothing there it looks in the other one
129
- and says where the hooks actually are. User settings apply in every project, so
130
- hooks found there answer a project-scope check.
134
+ those fail silently on every event otherwise — and names the Node the hooks
135
+ will run and the last hook Claude Code ran. It checks one scope, defaulting to
136
+ `user` like `setup`; if it finds nothing there it looks in the other one and
137
+ says where the hooks actually are.
131
138
 
132
139
  #### Installing without a pairing
133
140
 
134
141
  `--no-pair` installs the hooks and stops before pairing. A `setup` that tried
135
142
  to pair and couldn't finish — the backend unreachable, nobody at the keyboard
136
143
  to confirm the code, the session expired — lands in the same place instead of
137
- failing. The install completes either way, and the summary names which half is
138
- running:
144
+ failing. The install completes either way, and the summary says which it was.
145
+ Asked for, it reads as finished; a pairing that didn't finish warns, and offers
146
+ the retry:
139
147
 
140
- ```text
141
- Installed, not paired.
142
- active the session prompts, and the live signal to a socket on this machine
143
- inactive delivery to https://api.ascenda.one. Nothing is sent, and nothing is queued for later.
144
- pair later npx @ascenda-one/claude-code-hooks pair
145
- ```
148
+ ![setup --no-pair finishing with "Ready."](https://raw.githubusercontent.com/ascendaone-com/ai-engineer-tools/main/docs/images/cli-setup-no-pair.png)
146
149
 
147
150
  Two things work with no pairing at all, which is why this mode exists. The
148
151
  session prompts are composed locally in the hook process. The live signal goes
@@ -299,7 +302,16 @@ SessionEnd hooks share 1.5s between them.
299
302
  npx -y @ascenda-one/claude-code-hooks doctor
300
303
  ```
301
304
 
302
- `doctor` prints the installation id and where it came from (environment,
305
+ `doctor` starts with the local half, which needs no pairing: the Node the
306
+ hooks will run (found with a bare `PATH`, the way a Dock-launched Claude Code
307
+ starts them), which settings files register them and whether those load in
308
+ every project, the last hook Claude Code ran, who is listening on the live
309
+ socket (the desktop app, or the Waterline screen saver and whether it is the
310
+ one on screen), and a ping that the saver answers in its heartbeat. The System
311
+ Settings preview never listens, so testing with it shows resting water;
312
+ `doctor` says so.
313
+
314
+ Then it prints the installation id and where it came from (environment,
303
315
  credentials file, or the token store on disk), the token's presence and age,
304
316
  the last recorded send outcome, any sends skipped for want of an installation
305
317
  id, and the result of a live round trip against the real ingest endpoint. It is the first thing to run when the Ascenda app shows a