@ascenda-one/claude-code-hooks 0.1.33 → 0.1.35
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/NOTICE +6 -0
- package/README.md +46 -30
- package/dist/cli.js +2257 -1008
- package/dist/cli.js.map +1 -1
- package/dist/hookHealth.js +21 -0
- package/dist/hookHealth.js.map +1 -0
- package/dist/launcher.js +14 -0
- package/dist/launcher.js.map +1 -0
- package/dist/liveDoctor.js +27 -0
- package/dist/liveDoctor.js.map +1 -0
- package/dist/liveEvent.js +8 -0
- package/dist/liveEvent.js.map +1 -1
- package/dist/paths.js +30 -1
- package/dist/paths.js.map +1 -1
- package/dist/setup.js +241 -90
- package/dist/setup.js.map +1 -1
- package/package.json +3 -2
package/NOTICE
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
@ascenda-one/claude-code-hooks
|
|
2
|
+
Copyright 2026 Ascenda One Pty Ltd
|
|
3
|
+
|
|
4
|
+
Licensed under the Apache License, Version 2.0. See LICENSE.
|
|
5
|
+
|
|
6
|
+
Metadata-only AI workload telemetry adapter. Do not send source code, raw prompts, raw responses, file names, branch names, repository names, or terminal output by default.
|
package/README.md
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
Claude Code hooks adapter for Ascenda AI workload telemetry.
|
|
4
4
|
|
|
5
5
|
Part of [ai-engineer-tools](../). For what these measurements do and do not
|
|
6
|
-
establish, see [What this measures](../#what-this-measures
|
|
6
|
+
establish, see [What this measures](../#what-this-measures).
|
|
7
7
|
Event mapping: [docs/CLAUDE_MAPPING.md](./docs/CLAUDE_MAPPING.md).
|
|
8
8
|
|
|
9
9
|
## What it sends
|
|
@@ -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
|
|
63
|
-
|
|
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,8 @@ 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
|
-
| `--
|
|
77
|
+
| `--event-log [path\|off]` | keep every event in a local JSONL file (default `~/.ascenda/events.jsonl`). On by default without a pairing; `off` stops it |
|
|
78
|
+
| `--scope user\|project` | register in `~/.claude/settings.json` (default, every project) or in this project's `.claude/settings.local.json` |
|
|
78
79
|
| `--project-dir <path>` | project root for `--scope project` (default cwd) |
|
|
79
80
|
| `--dry-run` | print what would change, write nothing |
|
|
80
81
|
|
|
@@ -87,10 +88,12 @@ DevAuth. Stop it with `./scripts/setup-local.sh --stop`. See
|
|
|
87
88
|
|
|
88
89
|
| Path | |
|
|
89
90
|
| --- | --- |
|
|
90
|
-
| `~/.ascenda/bin/ascenda-claude-hook` | the
|
|
91
|
+
| `~/.ascenda/bin/ascenda-claude-hook` | the launcher every hook command names: a small `sh` script that finds Node and runs the bundle |
|
|
92
|
+
| `~/.ascenda/bin/ascenda-claude-hook.mjs` | the self-contained bundle — no `npm -g`, no sudo, no PATH edit |
|
|
93
|
+
| `~/.ascenda/bin/ascenda-claude-hook.node` | the Node the launcher last found, starting with the one that ran setup |
|
|
91
94
|
| `~/.ascenda/credentials.json` | `apiBaseUrl` + `toolInstallationId`, `0600` (plus `localOnly` on an install with no pairing) |
|
|
92
95
|
| `~/.ascenda/tokens/<id>` | the event write token, `0600`, rotated in place on renew |
|
|
93
|
-
|
|
|
96
|
+
| `~/.claude/settings.json` | one hook entry per lifecycle event, `timeout: 5` (`.claude/settings.local.json` under `--scope project`) |
|
|
94
97
|
|
|
95
98
|
Registration is idempotent and marker-keyed: re-running replaces our entries
|
|
96
99
|
rather than appending, hooks belonging to anyone else are left alone, and the
|
|
@@ -114,41 +117,44 @@ Code afterwards: a session keeps the hooks it started with.
|
|
|
114
117
|
|
|
115
118
|
If you use the plugin, run `claude plugin update ascenda@ascenda-one` instead.
|
|
116
119
|
Its `hooks.json` registers the same set. Having both the plugin and a `setup` install runs every hook
|
|
117
|
-
twice
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
120
|
+
twice. `setup` moves its own entries out of the other scope's file (and out of
|
|
121
|
+
`~/.claude/settings.local.json`, where a project install run from the home
|
|
122
|
+
folder used to put them, loading only when Claude Code started in `~`), but it
|
|
123
|
+
can't remove the plugin's.
|
|
124
|
+
|
|
125
|
+
Hooks then need **no environment at all**. The command names the launcher, and
|
|
126
|
+
the launcher finds Node: the one that ran setup while it's still there, and
|
|
127
|
+
otherwise the first Node 20 or newer on `PATH`, in Homebrew, volta, nvm's
|
|
128
|
+
default alias, fnm, asdf or mise, which it records for next time. So a hook
|
|
129
|
+
keeps working when Claude Code is opened from the Dock or an IDE, and after a
|
|
130
|
+
version manager removes the Node that ran setup. If there is no Node at all,
|
|
131
|
+
`SessionStart` says so once and the other hooks stay quiet. Configuration comes
|
|
132
|
+
from the credentials file; the variables below still override it when set.
|
|
125
133
|
|
|
126
134
|
`status` also flags hook entries pointing at a binary that no longer exists —
|
|
127
|
-
those fail silently on every event otherwise
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
135
|
+
those fail silently on every event otherwise — and names the Node the hooks
|
|
136
|
+
will run and the last hook Claude Code ran. It checks one scope, defaulting to
|
|
137
|
+
`user` like `setup`; if it finds nothing there it looks in the other one and
|
|
138
|
+
says where the hooks actually are.
|
|
131
139
|
|
|
132
140
|
#### Installing without a pairing
|
|
133
141
|
|
|
134
142
|
`--no-pair` installs the hooks and stops before pairing. A `setup` that tried
|
|
135
143
|
to pair and couldn't finish — the backend unreachable, nobody at the keyboard
|
|
136
144
|
to confirm the code, the session expired — lands in the same place instead of
|
|
137
|
-
failing. The install completes either way, and the summary
|
|
138
|
-
|
|
145
|
+
failing. The install completes either way, and the summary says which it was.
|
|
146
|
+
Asked for, it reads as finished; a pairing that didn't finish warns, and offers
|
|
147
|
+
the retry:
|
|
139
148
|
|
|
140
|
-
|
|
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
|
-
```
|
|
149
|
+

|
|
146
150
|
|
|
147
|
-
|
|
151
|
+
Three things work with no pairing at all, which is why this mode exists. The
|
|
148
152
|
session prompts are composed locally in the hook process. The live signal goes
|
|
149
153
|
to a socket on your own machine, so a listener there sees an agent working the
|
|
150
|
-
moment it starts.
|
|
151
|
-
|
|
154
|
+
moment it starts. And every event is written to `~/.ascenda/events.jsonl`, the
|
|
155
|
+
same metadata a paired install would send, for you or any other tool to read.
|
|
156
|
+
[examples/local-event-reader](../examples/local-event-reader/) is a small
|
|
157
|
+
script that does. None of it owes anything to a backend.
|
|
152
158
|
|
|
153
159
|
What that install holds: the hook binary, the registered events, and a
|
|
154
160
|
credentials file with an installation id, `localOnly: true` and `installedAt`.
|
|
@@ -227,6 +233,7 @@ Optional environment:
|
|
|
227
233
|
| `ASCENDA_EVENT_WRITE_TOKEN` | Only if you have no prior pairing to reuse — normally the token file supplies this |
|
|
228
234
|
| `ASCENDA_EVENT_WRITE_TOKEN_FILE` | Override token file path (default `~/.ascenda/tokens/<toolInstallationId>`) |
|
|
229
235
|
| `ASCENDA_SESSION_ID` | Stable session id across hooks |
|
|
236
|
+
| `ASCENDA_EVENT_LOG_FILE` | Local JSONL event log path, or `off`. Wins over `setup --event-log`. Without either, an unpaired install writes `~/.ascenda/events.jsonl` and a paired one writes nothing |
|
|
230
237
|
| `ASCENDA_WORKSPACE_HASH` | Override only. By default the hook derives this from the payload's own `cwd`: a machine-salted hash of the checkout folder's basename (never the path itself) |
|
|
231
238
|
| `ASCENDA_PROJECT_HASH` | Override only. Defaults to the salted hash of the canonical repository's basename — a git worktree folds into the repo it was created from |
|
|
232
239
|
| `ASCENDA_STATE_FILE` | Override the send journal path (default `~/.ascenda/state/<toolInstallationId>.json`) |
|
|
@@ -299,7 +306,16 @@ SessionEnd hooks share 1.5s between them.
|
|
|
299
306
|
npx -y @ascenda-one/claude-code-hooks doctor
|
|
300
307
|
```
|
|
301
308
|
|
|
302
|
-
`doctor`
|
|
309
|
+
`doctor` starts with the local half, which needs no pairing: the Node the
|
|
310
|
+
hooks will run (found with a bare `PATH`, the way a Dock-launched Claude Code
|
|
311
|
+
starts them), which settings files register them and whether those load in
|
|
312
|
+
every project, the last hook Claude Code ran, who is listening on the live
|
|
313
|
+
socket (the desktop app, or the Waterline screen saver and whether it is the
|
|
314
|
+
one on screen), and a ping that the saver answers in its heartbeat. The System
|
|
315
|
+
Settings preview never listens, so testing with it shows resting water;
|
|
316
|
+
`doctor` says so.
|
|
317
|
+
|
|
318
|
+
Then it prints the installation id and where it came from (environment,
|
|
303
319
|
credentials file, or the token store on disk), the token's presence and age,
|
|
304
320
|
the last recorded send outcome, any sends skipped for want of an installation
|
|
305
321
|
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
|