@mainwave/cli 0.7.1 → 0.9.0

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.
Files changed (139) hide show
  1. package/README.md +141 -42
  2. package/dist/adapters/claude-code.js +33 -7
  3. package/dist/adapters/claude-desktop.js +0 -1
  4. package/dist/adapters/codex-cli.js +1 -2
  5. package/dist/adapters/copilot-chat.js +0 -1
  6. package/dist/adapters/copilot-cli.js +0 -1
  7. package/dist/adapters/cursor-enterprise.js +0 -1
  8. package/dist/adapters/cursor.js +15 -4
  9. package/dist/adapters/index.js +0 -1
  10. package/dist/adapters/types.js +0 -1
  11. package/dist/api/index.js +0 -1
  12. package/dist/api/types.gen.js +0 -1
  13. package/dist/cli.js +0 -1
  14. package/dist/core/apply.js +151 -42
  15. package/dist/core/auth-commands.js +0 -1
  16. package/dist/core/behaviour-hooks.js +0 -1
  17. package/dist/core/browser.js +0 -1
  18. package/dist/core/codecs/cursor-hooks-json.js +0 -1
  19. package/dist/core/codecs/env-file.js +0 -1
  20. package/dist/core/codecs/json-env.js +0 -1
  21. package/dist/core/codecs/json-flat.js +0 -1
  22. package/dist/core/codecs/json-managed.js +0 -1
  23. package/dist/core/codecs/toml-otel.js +0 -1
  24. package/dist/core/codecs/types.js +0 -1
  25. package/dist/core/detect.js +0 -1
  26. package/dist/core/device-login.js +0 -1
  27. package/dist/core/doctor.js +45 -9
  28. package/dist/core/edit.js +9 -5
  29. package/dist/core/effective-settings.js +71 -20
  30. package/dist/core/entry-script.js +90 -0
  31. package/dist/core/env-command.js +0 -1
  32. package/dist/core/errors.js +0 -1
  33. package/dist/core/flags.js +0 -1
  34. package/dist/core/format.js +0 -1
  35. package/dist/core/git-bash.js +40 -0
  36. package/dist/core/git.js +0 -1
  37. package/dist/core/headers.js +0 -1
  38. package/dist/core/install-hooks.js +127 -44
  39. package/dist/core/interview.js +53 -4
  40. package/dist/core/keys.js +0 -1
  41. package/dist/core/layer-policy.js +2 -1
  42. package/dist/core/markers.js +826 -133
  43. package/dist/core/pinned-use-case.js +0 -1
  44. package/dist/core/platform.js +0 -1
  45. package/dist/core/post-setup.js +0 -1
  46. package/dist/core/prompts.js +0 -1
  47. package/dist/core/settings.js +32 -8
  48. package/dist/core/skills.js +5 -2
  49. package/dist/core/status.js +7 -5
  50. package/dist/core/store.js +0 -1
  51. package/dist/core/tty.js +0 -1
  52. package/dist/core/ucid.js +0 -1
  53. package/dist/core/ui.js +0 -1
  54. package/dist/core/use-case.js +0 -1
  55. package/dist/core/validate.js +0 -1
  56. package/dist/core/verify.js +0 -1
  57. package/dist/core/version.js +0 -1
  58. package/dist/core/wizard.js +49 -8
  59. package/dist/main.js +16 -10
  60. package/hooks/cursor-otlp.mjs +13 -15
  61. package/hooks/github-pr-marker.mjs +55 -31
  62. package/hooks/glab-mr-marker.mjs +795 -0
  63. package/hooks/jira-ticket-marker.mjs +35 -23
  64. package/hooks/linear-ticket-marker.mjs +35 -21
  65. package/hooks/mainwave-hook-node.mjs +42 -0
  66. package/hooks/mainwave-hook.mjs +301 -0
  67. package/hooks/managed-entry.mjs +42 -0
  68. package/hooks/marker-core.mjs +389 -62
  69. package/hooks/matchers.json +82 -6
  70. package/hooks/plan-snapshot.mjs +529 -0
  71. package/hooks/stop-failure.mjs +43 -0
  72. package/hooks/vocabulary.d.mts +48 -0
  73. package/hooks/vocabulary.mjs +181 -0
  74. package/package.json +6 -5
  75. package/skills/mainwave-instrument/SKILL.md +21 -7
  76. package/skills/mainwave-instrument/reference/api.md +29 -10
  77. package/skills/mainwave-instrument/reference/frameworks.md +3 -3
  78. package/skills/mainwave-instrument/reference/troubleshooting.md +12 -5
  79. package/skills/mainwave-instrument-node/SKILL.md +420 -0
  80. package/skills/mainwave-instrument-node/reference/api.md +96 -0
  81. package/skills/mainwave-instrument-node/reference/frameworks.md +82 -0
  82. package/skills/mainwave-instrument-node/reference/troubleshooting.md +152 -0
  83. package/skills/mainwave-setup/SKILL.md +47 -12
  84. package/dist/adapters/claude-code.js.map +0 -1
  85. package/dist/adapters/claude-desktop.js.map +0 -1
  86. package/dist/adapters/codex-cli.js.map +0 -1
  87. package/dist/adapters/copilot-chat.js.map +0 -1
  88. package/dist/adapters/copilot-cli.js.map +0 -1
  89. package/dist/adapters/cursor-enterprise.js.map +0 -1
  90. package/dist/adapters/cursor.js.map +0 -1
  91. package/dist/adapters/index.js.map +0 -1
  92. package/dist/adapters/types.js.map +0 -1
  93. package/dist/api/index.js.map +0 -1
  94. package/dist/api/types.gen.js.map +0 -1
  95. package/dist/cli.js.map +0 -1
  96. package/dist/core/apply.js.map +0 -1
  97. package/dist/core/auth-commands.js.map +0 -1
  98. package/dist/core/behaviour-hooks.js.map +0 -1
  99. package/dist/core/browser.js.map +0 -1
  100. package/dist/core/codecs/cursor-hooks-json.js.map +0 -1
  101. package/dist/core/codecs/env-file.js.map +0 -1
  102. package/dist/core/codecs/json-env.js.map +0 -1
  103. package/dist/core/codecs/json-flat.js.map +0 -1
  104. package/dist/core/codecs/json-managed.js.map +0 -1
  105. package/dist/core/codecs/toml-otel.js.map +0 -1
  106. package/dist/core/codecs/types.js.map +0 -1
  107. package/dist/core/detect.js.map +0 -1
  108. package/dist/core/device-login.js.map +0 -1
  109. package/dist/core/doctor.js.map +0 -1
  110. package/dist/core/edit.js.map +0 -1
  111. package/dist/core/effective-settings.js.map +0 -1
  112. package/dist/core/env-command.js.map +0 -1
  113. package/dist/core/errors.js.map +0 -1
  114. package/dist/core/flags.js.map +0 -1
  115. package/dist/core/format.js.map +0 -1
  116. package/dist/core/git.js.map +0 -1
  117. package/dist/core/headers.js.map +0 -1
  118. package/dist/core/install-hooks.js.map +0 -1
  119. package/dist/core/interview.js.map +0 -1
  120. package/dist/core/keys.js.map +0 -1
  121. package/dist/core/layer-policy.js.map +0 -1
  122. package/dist/core/markers.js.map +0 -1
  123. package/dist/core/pinned-use-case.js.map +0 -1
  124. package/dist/core/platform.js.map +0 -1
  125. package/dist/core/post-setup.js.map +0 -1
  126. package/dist/core/prompts.js.map +0 -1
  127. package/dist/core/settings.js.map +0 -1
  128. package/dist/core/skills.js.map +0 -1
  129. package/dist/core/status.js.map +0 -1
  130. package/dist/core/store.js.map +0 -1
  131. package/dist/core/tty.js.map +0 -1
  132. package/dist/core/ucid.js.map +0 -1
  133. package/dist/core/ui.js.map +0 -1
  134. package/dist/core/use-case.js.map +0 -1
  135. package/dist/core/validate.js.map +0 -1
  136. package/dist/core/verify.js.map +0 -1
  137. package/dist/core/version.js.map +0 -1
  138. package/dist/core/wizard.js.map +0 -1
  139. package/dist/main.js.map +0 -1
package/README.md CHANGED
@@ -75,10 +75,12 @@ rather than leaving it stale.
75
75
 
76
76
  ## What gets captured
77
77
 
78
- Setup enables content capture by default: **prompt text**, **shell commands and file paths**, and
79
- **tool result bodies** are sent to your collector alongside the metadata (tool names, tokens, cost,
80
- who ran what). The wizard says so before it finishes — it is not a question, because what an
81
- organization collects is a policy decision rather than a per-developer one.
78
+ Setup enables content capture by default: **prompt text**, **shell commands and file paths**,
79
+ **tool result bodies** and, for Claude Code, **repository names** (`OTEL_METRICS_INCLUDE_REPOSITORY`,
80
+ which stamps the session's repository on Claude Code's own events, metrics and trace spans) are
81
+ sent to your collector alongside the metadata (tool names, tokens, cost, who ran what). The wizard
82
+ says so before it finishes — it is not a question, because what an organization collects is a
83
+ policy decision rather than a per-developer one.
82
84
 
83
85
  To send metadata only:
84
86
 
@@ -91,7 +93,8 @@ and per-person activity are all metadata. **Codex is different:** it reports too
91
93
  approvals only when tool logging is on, so `--opt-in none` leaves Codex's tool views empty. Keep
92
94
  `--opt-in tool-details` for Codex if you want those without sending prompt text or tool output.
93
95
 
94
- Or pick exactly what you want: `--opt-in tool-details`, `--opt-in prompts,tool-details`, and so on.
96
+ Or pick exactly what you want: `--opt-in tool-details`, `--opt-in prompts,tool-details`,
97
+ `--opt-in tool-details,repository`, and so on.
95
98
  Re-running with a different `--opt-in` removes the flags it no longer wants rather than leaving them
96
99
  stale.
97
100
 
@@ -129,30 +132,33 @@ mainwave-cli setup claude-code codex \
129
132
  --opt-in none --no-markers --yes --json
130
133
  ```
131
134
 
132
- | Flag | Answers |
133
- | ---------------------------------------------------------------- | ------------------------------------------------------------- |
134
- | `--api-key <k>` | the collector key (otherwise minted for you when signed in) |
135
- | `--collector-url <u>` / `--api-url <u>` | which deployment |
136
- | `--ucid <id\|url>` / `--use-case <name>` / `--no-use-case` | pin one use case, or `--no-use-case` to unpin (default: none) |
137
- | `--email <e>` | attribution identity for tools that need it injected |
138
- | `--opt-in prompts,tool-details,tool-content` (or `all` / `none`) | content capture (default: all on; `none` sends metadata only) |
139
- | `--no-markers` | skip the ticket & PR marker hooks (installed by default) |
140
- | `--new-key` | mint a fresh machine key instead of reusing this machine's |
141
- | `--yes` | write without the confirmation prompt |
142
- | `--no-verify` / `--verify-timeout <s>` | the closing first-span check |
143
- | `--skills` / `--no-skills` | the agent skills payload |
135
+ | Flag | Answers |
136
+ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
137
+ | `--api-key <k>` | the collector key (otherwise minted for you when signed in) |
138
+ | `--collector-url <u>` / `--api-url <u>` | which deployment |
139
+ | `--ucid <id\|url>` / `--use-case <name>` / `--no-use-case` | pin one use case, or `--no-use-case` to unpin (default: none) |
140
+ | `--email <e>` | attribution identity for tools that need it injected |
141
+ | `--opt-in prompts,tool-details,tool-content,repository` (or `all` / `none`) | content capture (default: all on; `none` sends metadata only; `repository` is Claude Code's repository names) |
142
+ | `--no-markers` | skip the Mainwave hooks (installed by default): the ticket & PR markers and the Claude plan snapshot |
143
+ | `--new-key` | mint a fresh machine key instead of reusing this machine's |
144
+ | `--yes` | write without the confirmation prompt |
145
+ | `--no-verify` / `--verify-timeout <s>` | the closing first-span check |
146
+ | `--skills` / `--no-skills` | the agent skills payload |
144
147
 
145
148
  Without a terminal the CLI never prompts: it answers from flags and environment, or fails naming the
146
149
  flag it needed. `status` and `doctor` also take `--json`.
147
150
 
148
151
  ## Agent skills
149
152
 
150
- Setup installs two skills alongside the telemetry config — one detection, one pass, two outputs:
153
+ Setup installs three skills alongside the telemetry config — one detection, one pass, two outputs:
151
154
 
152
155
  - **`mainwave-setup`** — lets your coding agent run this whole flow itself: sign in, configure a
153
156
  tool, verify. It knows the flags, so you can just ask it to connect you.
154
157
  - **`mainwave-instrument`** — wires the `mainwave` Python SDK into an application, so an agent or
155
158
  service of your own reports runs, tokens, and cost.
159
+ - **`mainwave-instrument-node`** — wires the `@mainwave/sdk` Node.js SDK into a Node or TypeScript
160
+ application (eve, the Vercel AI SDK, OpenAI, Anthropic), so it reports runs, tokens, and cost.
161
+ Your agent picks it for a Node repository and `mainwave-instrument` for a Python one.
156
162
 
157
163
  The bundles are copied to `~/.mainwave/skills/`, then registered on each tool's own instruction
158
164
  surface: a native skill directory for Claude Code, `AGENTS.md` for Codex, `copilot-instructions.md`
@@ -161,7 +167,7 @@ rather than counted as installed.
161
167
 
162
168
  The payload is installed at user scope, like the telemetry config — the skills teach an agent how to
163
169
  use Mainwave anywhere, so a copy per repo would be pure duplication. Re-running setup refreshes them,
164
- the same way it refreshes the marker hook scripts.
170
+ the same way it refreshes the hook scripts.
165
171
 
166
172
  ```bash
167
173
  mainwave-cli setup claude-code --skills-only # instructions, no telemetry config
@@ -179,38 +185,113 @@ mainwave-cli login --device
179
185
 
180
186
  For Claude Code, setup also installs **ticket & PR markers**: small post-tool hooks that emit one
181
187
  event when a Linear or Jira issue is filed and one when a pull request is opened with
182
- `gh pr create`. They are what populates "Tickets filed" and "PRs created" on the use case — without
188
+ `gh pr create` or a GitLab merge request is opened with `glab mr create` (or a `glab api` POST to a
189
+ project's `merge_requests` endpoint). Claude Code starts the pull-request hooks only for a Bash
190
+ command that begins with `gh` or `glab` (a wrapper or a path, such as `env gh …` or
191
+ `/usr/local/bin/glab …`, isn't matched), and runs every Mainwave hook in the background, so none of
192
+ them adds time to a tool call. They are what populates "Tickets filed" and "PRs created" on the use case — without
183
193
  them those counts read zero, which is why they are on by default rather than a question.
184
194
 
185
195
  What leaves your machine: the issue key, whether it was a create or an update, and the PR's
186
- url/number/title plus aggregate diff counts. Never ticket bodies, never diff content. The hooks fail
196
+ url/number/title plus aggregate diff counts. For a GitLab merge request that is the url, number,
197
+ title, project id and the changed-file count. Never ticket bodies, never diff content. The hooks fail
187
198
  open — a telemetry problem can never block or slow a coding session — and count forward only from
188
199
  when you enable them.
189
200
 
190
- Mechanics: the hook scripts are copied to `~/.mainwave/hooks/` and referenced from the same settings
191
- file the wizard writes. Upgrading the CLI does not update them by itself — **re-run setup after an
192
- upgrade** to refresh both the scripts and the tool-matching rules; `doctor` warns when the installed
193
- entries were written by an older CLI version. To disable, re-run setup with `--no-markers` — the
194
- entries are removed cleanly.
201
+ For Claude Code, the same install adds a **Claude plan snapshot**: a hook on Claude Code's
202
+ `UserPromptSubmit` event (each prompt you submit) that reads Claude Code's local account record (`.claude.json`) and sends one event every time
203
+ it runs. What leaves your machine: your Claude account id, organization id and email (the identity
204
+ Claude Code's own telemetry already carries); from your account profile, exactly as Claude Code
205
+ stores them, the plan's organization type, seat tier, rate-limit tier and billing type, your
206
+ organization and workspace roles, when the subscription started, the trial's end date and length,
207
+ the date of your first Claude Code use, and when Claude Code fetched that profile; from Claude
208
+ Code's usage cache, your 5-hour and 7-day usage and when they reset, each rate limit's percent used,
209
+ group, severity, whether it is the active one and when it resets (and, for a limit Claude Code
210
+ applies per model, which model it is, by the name Claude Code stores), whether extra usage is on, the
211
+ extra-usage amount spent and monthly limit, their currency, whether the spend limit is reached,
212
+ whether and why extra usage is disabled, and when Claude Code fetched those figures. Each event also
213
+ carries which event sent it, the prompt id, the
214
+ session id, the ids of the turn's trace and span, and the session's OpenTelemetry resource attributes, as the
215
+ other markers do. Never your prompt, and nothing else in that file. A figure Claude Code hasn't
216
+ recorded is left out, not sent as zero; Claude Code refreshes its usage figures only when you open
217
+ its usage view, so the same figures repeat until then, each with the time Claude Code fetched it. Figures
218
+ refreshed by a `/usage` just before you quit reach Mainwave at your next prompt, since Claude Code
219
+ keeps them on disk. Nothing is sent when a session ends.
220
+ It runs only in sessions signed in with a Claude account, keeps no state it reads back (a one-line
221
+ timestamp file, `~/.mainwave/logs/plan-snapshot.log.ok`, records the last successful send for `doctor`),
222
+ and never makes a
223
+ prompt wait: Claude Code runs it in the background without waiting for it, and it gives up on the
224
+ send after 4 seconds. Under `claude -p`, Claude Code stops a snapshot that is still sending when the
225
+ run ends, so that snapshot is lost. Setup says that it is on, and what it sends, on every run.
226
+ It has no switch of its own: it installs wherever setup installs the Mainwave hooks for Claude Code,
227
+ and `--no-markers`, which installs no Mainwave hooks at all, leaves it out too.
228
+ Where Claude Code runs only the hooks your organization's managed settings deliver
229
+ (`allowManagedHooksOnly`), or a settings file turns hooks off (`disableAllHooks`), and the managed
230
+ settings don't send the snapshot themselves, your own copy can't run; setup says so and names the
231
+ setting.
232
+
233
+ It comes with one smaller Claude account event. When a turn ends on an API error (a rate
234
+ limit, a billing error, an overloaded API, a sign-in that stopped working), one event carries the
235
+ error type only — never the error details or message. It also carries the session id, the prompt id,
236
+ the turn's trace ids and, when the session is signed in with a Claude account, your Claude account id
237
+ and email, so it lines up with the plan snapshot. Unlike the snapshot, it is sent from any Claude
238
+ Code session.
239
+
240
+ Mechanics: every Mainwave hook group in your settings runs one small shell entry,
241
+ `~/.mainwave/hooks/managed/mainwave-hook.sh`, with the event it is for (`claude-code PostToolUse gh`,
242
+ `claude-code UserPromptSubmit`, …). The entry prints nothing, never reads the hook input itself
243
+ (only Codex's one Bash hook does, to skip commands that can't open a PR or MR), and exits 0 whatever
244
+ happens; it runs the current release's scripts, kept in `~/.mainwave/hooks/managed/versions/`.
245
+ Setup also adds a session-start hook that runs
246
+ `{ cd "$HOME" && npx -y --registry=https://registry.npmjs.org @mainwave/cli@latest install-hooks --quiet; } >/dev/null 2>&1; exit 0`
247
+ in the background when a session starts, resumes or forks — its output discarded and exit 0
248
+ whatever happens, so an unreachable npm registry never shows up as a failed hook: it installs the latest release's scripts
249
+ and points the entry at them, and keeps the hooks setup installed in your user settings current —
250
+ on the events setup told you about only. A release that adds a new kind of hook waits for your next
251
+ setup run, which says what it sends. It is written only when at least one hook is on, so
252
+ `--no-markers` writes no hooks at all. Your `--no-markers` choice is also recorded as a file
253
+ under `~/.mainwave/hooks/off/`, which the entry reads, so a hook you turned off sends nothing even
254
+ from a copy setup didn't write (unless your organization's managed settings deliver it, which you
255
+ can't turn off). Re-running setup removes hooks written by an earlier CLI version, and the scripts
256
+ an earlier version copied into `~/.mainwave/hooks/` once nothing runs them. To disable the hooks,
257
+ the plan snapshot included, re-run setup with `--no-markers` — the entries are removed cleanly. `doctor` checks that the entry is installed, that it names an installed release with every
258
+ script, and that every Mainwave hook group is in the background and narrowed by its matcher.
259
+
260
+ On Windows, the Claude Code hooks need Git for Windows. Claude Code runs hook commands through Git
261
+ Bash, and through PowerShell when it finds none, where the entry's shell command can't run. Without
262
+ Git Bash, setup installs no Claude Code hooks and says why, and `doctor` reports it as an error;
263
+ hooks an earlier CLI version installed that run `node` directly are kept. Claude Code looks for Git
264
+ Bash at `CLAUDE_CODE_GIT_BASH_PATH`, then Git for Windows' default install paths, then beside the
265
+ `git` on your `PATH`, and setup looks in the same places: if yours is elsewhere, set
266
+ `CLAUDE_CODE_GIT_BASH_PATH` to its `bash.exe` and re-run setup.
195
267
 
196
268
  Organizations that configure Claude Code centrally (managed settings from the Claude admin console,
197
- or an MDM `managed-settings.json`) deliver the markers without anyone running setup: when a session
198
- starts or resumes (not on `/clear` or a compaction), the managed settings run
199
- `cd "$HOME" && npx -y --registry=https://registry.npmjs.org @mainwave/cli@latest install-hooks --quiet`
200
- — from your home directory, so a repository's own `.npmrc` or `node_modules` can't choose what runs —
201
- which installs or refreshes the scripts in `~/.mainwave/hooks/managed/` with no prompts, no
202
- sign-in and no network calls of its own. `@latest` means each new release reaches your machine at
203
- its next session start, whatever copy of the CLI you have installed: npx asks the registry for the
204
- current release each time, and while you're offline the scripts already installed keep working.
205
- That directory is separate from the one a per-developer setup installs to, so neither overwrites the
206
- other's scripts. When managed settings deliver the
207
- hooks, it also removes the copy an earlier per-developer setup left in your user settings, so each ticket and PR is marked once, and `setup` itself leaves
208
- out any hook your managed settings already run. It never edits project settings; `doctor` lists
269
+ or an MDM `managed-settings.json`) deliver the markers and the Claude plan snapshot without anyone
270
+ running setup: when a session starts, resumes or forks (not on `/clear` or a compaction), the
271
+ managed settings run the same `install-hooks` command — from your home directory, so a repository's
272
+ own `.npmrc` or `node_modules` can't choose what runs — which installs or refreshes the scripts in
273
+ `~/.mainwave/hooks/managed/` with no prompts, no sign-in and no network calls of its own. `@latest`
274
+ means each new release reaches your machine at its next session start, whatever copy of the CLI you
275
+ have installed: npx asks the registry for the current release each time, and while you're offline
276
+ the scripts already installed keep working. Each release's scripts sit in their own directory and
277
+ the entry is switched to a new one only once it is complete, so two installs racing never mix
278
+ releases. The org-wide payload writes exactly the hook commands setup writes, so on a machine with
279
+ both, Claude Code runs each hook once. Managed settings your admin pasted before the entry existed
280
+ run one script per hook, in the foreground, and have no plan snapshot; they keep working, and get
281
+ the current hooks only when your admin pastes the current version from Mainwave's Org-wide setup,
282
+ since `install-hooks` refreshes the scripts, not your organization's managed settings. An admin who
283
+ adds the current version without removing the earlier one gets every marker twice; `doctor` flags
284
+ both being present. When managed settings deliver the
285
+ hooks, `install-hooks` also removes your user settings' copy of each hook they deliver, so each ticket and PR is marked once and each prompt sends one plan snapshot, and `setup` itself leaves
286
+ out any hook your managed settings already run. Your own session-start hook stays: while the
287
+ managed settings run the same command Claude Code runs it once (a payload pasted before the
288
+ silent form runs beside it until your admin re-pastes — harmless), and if they stop delivering the
289
+ hooks it puts back the ones setup installed for you. It never edits project settings; `doctor` lists
209
290
  every settings file that installs the hooks and warns when two of them would fire for the same
210
291
  ticket or PR. The org-wide setup follows how Claude Code 2.1.282 and later apply managed settings;
211
292
  `doctor` warns on an older install.
212
293
 
213
- Two kinds of session don't get the admin console's markers:
294
+ Two kinds of session don't get the admin console's markers or plan snapshot:
214
295
 
215
296
  - A session that skips server-managed settings: one started with a `CLAUDE_CODE_USE_*` provider
216
297
  variable or a non-Anthropic `ANTHROPIC_BASE_URL` in your shell or user settings. Once the org's
@@ -228,9 +309,10 @@ Two kinds of session don't get the admin console's markers:
228
309
  Under the org's settings, which carry no use case of their own, a marker is attributed through the
229
310
  Claude account the session is signed in with. A session signed in another way (an API key, a
230
311
  `CLAUDE_CODE_OAUTH_TOKEN`, a cloud provider through MDM delivery) sends markers no developer is
231
- attached to.
312
+ attached to, and no plan snapshot.
232
313
 
233
- Markers are available only for tools with a hooks mechanism (today: Claude Code). For other tools
314
+ Markers are available only for tools with a hooks mechanism (today: Claude Code and Codex; the plan
315
+ snapshot is Claude Code only). For other tools
234
316
  the wizard says so instead of appearing to succeed.
235
317
 
236
318
  ## Signing in
@@ -275,7 +357,7 @@ mainwave-cli doctor <adapter> # settings hierarchy + health checks
275
357
  mainwave-cli doctor <adapter> --validate # also auth-check against the collector
276
358
  mainwave-cli edit <adapter> # open the settings file in $EDITOR
277
359
  mainwave-cli env <adapter> # print shell export lines
278
- mainwave-cli install-hooks [--quiet] # install or refresh the Claude Code marker hook scripts
360
+ mainwave-cli install-hooks [--quiet] # install or refresh the Mainwave hook entry and the latest release's scripts
279
361
  mainwave-cli --help
280
362
  ```
281
363
 
@@ -312,6 +394,23 @@ permissions in your home directory — never inside a repository. `status` shows
312
394
  knows about, masked; `doctor <adapter>` walks the full hierarchy, including repo-local files an
313
395
  older CLI or a colleague may have written.
314
396
 
397
+ ## Removing Mainwave
398
+
399
+ Deleting `~/.mainwave` is safe. Every Mainwave hook checks that its script is there and exits
400
+ quietly when it isn't, so nothing reaches your coding sessions. Where your organization delivers
401
+ Mainwave through Claude Code's managed settings, the next session start reinstalls what the hooks
402
+ run and telemetry resumes on its own. A setup you ran yourself stays off until you run
403
+ `mainwave-cli setup` again — signed in, that creates a new key, since the record of the old one
404
+ lived there — and Cursor and VS Code Copilot Chat stop sending until then.
405
+
406
+ To stop entirely, also remove the Mainwave entries from your tools' settings — for Claude Code,
407
+ `mainwave-cli setup claude-code --no-markers` removes its hooks, or delete the hook groups that
408
+ name `mainwave-hook.sh`, `install-hooks` or `--managed-by @mainwave/cli` from
409
+ `~/.claude/settings.json`, along with the `OTEL_*` telemetry keys setup wrote. Hooks delivered
410
+ through your organization's managed settings stay until your Claude admin removes them. Hooks
411
+ now log under `~/.mainwave/logs/`; releases before that logged to `~/.mainwave-*.log` files in your
412
+ home directory, which are left for you to delete.
413
+
315
414
  ## License
316
415
 
317
416
  Apache-2.0
@@ -19,6 +19,7 @@ const MANAGED_ENV_KEYS = [
19
19
  'OTEL_LOG_USER_PROMPTS',
20
20
  'OTEL_LOG_TOOL_DETAILS',
21
21
  'OTEL_LOG_TOOL_CONTENT',
22
+ 'OTEL_METRICS_INCLUDE_REPOSITORY',
22
23
  ];
23
24
  const buildResourceAttrs = (ucid, userEmail) => {
24
25
  const deploymentEnv = process.env.MAINWAVE_DEPLOYMENT_ENV ?? 'production';
@@ -79,6 +80,7 @@ const parseEnv = (env) => {
79
80
  userPrompts: env.OTEL_LOG_USER_PROMPTS === '1',
80
81
  toolDetails: env.OTEL_LOG_TOOL_DETAILS === '1',
81
82
  toolContent: env.OTEL_LOG_TOOL_CONTENT === '1',
83
+ repository: env.OTEL_METRICS_INCLUDE_REPOSITORY === '1',
82
84
  };
83
85
  return out;
84
86
  };
@@ -100,6 +102,8 @@ const buildEnv = ({ ucid, collectorUrl, apiKey, optIns, userEmail, }) => {
100
102
  env.OTEL_LOG_TOOL_DETAILS = '1';
101
103
  if (optIns.toolContent)
102
104
  env.OTEL_LOG_TOOL_CONTENT = '1';
105
+ if (optIns.repository)
106
+ env.OTEL_METRICS_INCLUDE_REPOSITORY = '1';
103
107
  return env;
104
108
  };
105
109
  const collectChecks = (env) => {
@@ -160,11 +164,11 @@ const managedSettingsDir = (() => {
160
164
  return 'C:\\Program Files\\ClaudeCode';
161
165
  return '/etc/claude-code';
162
166
  })();
163
- const HIERARCHY = [
167
+ const hierarchyFor = (userDir) => [
164
168
  {
165
169
  id: 'managed-server',
166
170
  label: 'Managed (server, cached)',
167
- path: join(USER_DIR, 'remote-settings.json'),
171
+ path: join(userDir, 'remote-settings.json'),
168
172
  kind: 'file',
169
173
  managedSource: 'server',
170
174
  },
@@ -197,10 +201,11 @@ const HIERARCHY = [
197
201
  {
198
202
  id: 'user',
199
203
  label: 'User (global)',
200
- path: join(USER_DIR, 'settings.json'),
204
+ path: join(userDir, 'settings.json'),
201
205
  kind: 'file',
202
206
  },
203
207
  ];
208
+ const HIERARCHY = hierarchyFor(USER_DIR);
204
209
  const EXPORTER_SELECTORS = ['OTEL_TRACES_EXPORTER', 'OTEL_METRICS_EXPORTER', 'OTEL_LOGS_EXPORTER'];
205
210
  const OFF_SWITCH_CONTENT_KEYS = [
206
211
  'OTEL_LOG_USER_PROMPTS',
@@ -278,13 +283,20 @@ const isManagedTelemetryUnitKey = (key) => key.startsWith('OTEL_EXPORTER_OTLP_')
278
283
  key === 'OTEL_LOGS_EXPORTER' ||
279
284
  key === 'ENABLE_BETA_TRACING_DETAILED' ||
280
285
  key === 'BETA_TRACING_ENDPOINT';
286
+ const OTEL_HEADERS_HELPER = 'otelHeadersHelper';
287
+ const claimsManagedTelemetryUnit = (settings) => {
288
+ const helper = settings[OTEL_HEADERS_HELPER];
289
+ return typeof helper === 'string' && helper.replace(/^[ \t\n\r\v\f]+|[ \t\n\r\v\f]+$/g, '') !== ''
290
+ ? OTEL_HEADERS_HELPER
291
+ : undefined;
292
+ };
281
293
  const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
282
294
  const OTLP = 'OTEL_EXPORTER_OTLP_';
283
295
  const OTLP_SIGNALS = ['TRACES', 'METRICS', 'LOGS'];
284
296
  const OTLP_CREDENTIALS = ['HEADERS', 'CLIENT_KEY', 'CLIENT_CERTIFICATE'];
285
297
  const perSignal = (suffix) => OTLP_SIGNALS.map((s) => `${OTLP}${s}_${suffix}`);
286
298
  const OFF_SELECTOR_VALUES = new Set(['none', 'console', '']);
287
- const isManagedLockedKey = (key, managed) => {
299
+ const isManagedLockedKey = (key, managed, unitClaim) => {
288
300
  const set = (k) => (managed[k] ?? '') !== '';
289
301
  if (set(`${OTLP}ENDPOINT`) && perSignal('ENDPOINT').includes(key))
290
302
  return true;
@@ -315,7 +327,7 @@ const isManagedLockedKey = (key, managed) => {
315
327
  const signalOff = ['OTEL_LOGS_EXPORTER', 'OTEL_TRACES_EXPORTER'].some((k) => k in managed && OFF_SELECTOR_VALUES.has(managed[k].trim().toLowerCase()));
316
328
  const telemetryOff = 'CLAUDE_CODE_ENABLE_TELEMETRY' in managed &&
317
329
  !TRUTHY.has(managed.CLAUDE_CODE_ENABLE_TELEMETRY.trim().toLowerCase());
318
- return decides || signalOff || telemetryOff;
330
+ return decides || unitClaim === OTEL_HEADERS_HELPER || signalOff || telemetryOff;
319
331
  }
320
332
  return false;
321
333
  };
@@ -418,6 +430,7 @@ export const claudeCode = {
418
430
  hierarchy: HIERARCHY,
419
431
  layerKeyPolicy: CLAUDE_CODE_LAYER_POLICY,
420
432
  managedUnitKey: isManagedTelemetryUnitKey,
433
+ managedUnitClaim: claimsManagedTelemetryUnit,
421
434
  managedLock: isManagedLockedKey,
422
435
  inactiveLayers: (env) => serverManagedBypassed(env)
423
436
  ? [
@@ -438,7 +451,20 @@ export const claudeCode = {
438
451
  label: 'skill directory',
439
452
  },
440
453
  markers: {
441
- disclosure: 'Sends Linear/Jira issue ids and GitHub PR urls to the collector — never ticket bodies or diff content.',
454
+ disclosure: 'Sends Linear/Jira issue ids and GitHub PR / GitLab MR urls to the collector — never ticket bodies or diff content.',
455
+ planSnapshotDisclosure: 'On each prompt it sends, from your Claude account: its email, account id and organization id; ' +
456
+ "the plan's tier names and roles; the subscription start date, trial end date and length, first-use date and profile refresh time; " +
457
+ 'your usage against its rate limits; whether extra usage is on, its amount, limit and currency, whether the limit is reached and why it is off; ' +
458
+ 'when Claude Code fetched those figures; and the session id, prompt id and turn trace and span ids. ' +
459
+ "It never includes prompt text; prompt text reaches Mainwave only through Claude Code's own telemetry, when prompt capture is on (it is by default) or raw API body logging is enabled. " +
460
+ 'When a turn ends on an API error, it sends only the error type ' +
461
+ '(never its message) with the same identity and ids.',
442
462
  },
443
463
  };
444
- //# sourceMappingURL=claude-code.js.map
464
+ export const claudeCodeFor = (userDir) => ({
465
+ ...claudeCode,
466
+ paths: { ...claudeCode.paths, global: join(userDir, 'settings.json') },
467
+ detect: () => hasPath(userDir) || hasBinary('claude'),
468
+ hierarchy: hierarchyFor(userDir),
469
+ instructionSurface: { ...claudeCode.instructionSurface, global: join(userDir, 'skills') },
470
+ });
@@ -163,4 +163,3 @@ export const claudeDesktop = {
163
163
  normalizeForGenericChecks,
164
164
  printPostSetupInstructions,
165
165
  };
166
- //# sourceMappingURL=claude-desktop.js.map
@@ -189,7 +189,7 @@ export const codexCli = {
189
189
  collectFileChecks,
190
190
  normalizeForGenericChecks,
191
191
  markers: {
192
- disclosure: 'Sends Linear/Jira issue ids and GitHub PR urls to the collector — never ticket bodies or diff content.',
192
+ disclosure: 'Sends Linear/Jira issue ids and GitHub PR / GitLab MR urls to the collector — never ticket bodies or diff content.',
193
193
  hooksFile: {
194
194
  path: join(homedir(), '.codex', 'hooks.json'),
195
195
  localPath: join('.codex', 'hooks.json'),
@@ -198,4 +198,3 @@ export const codexCli = {
198
198
  runtimeTool: 'codex',
199
199
  },
200
200
  };
201
- //# sourceMappingURL=codex-cli.js.map
@@ -181,4 +181,3 @@ export const copilotChat = {
181
181
  printPostSetupInstructions,
182
182
  additionalWrites: [envFileWrite],
183
183
  };
184
- //# sourceMappingURL=copilot-chat.js.map
@@ -107,4 +107,3 @@ export const copilotCli = {
107
107
  normalizeForGenericChecks,
108
108
  printPostSetupInstructions,
109
109
  };
110
- //# sourceMappingURL=copilot-cli.js.map
@@ -103,4 +103,3 @@ export const cursorEnterprise = {
103
103
  normalizeForGenericChecks,
104
104
  printPostSetupInstructions,
105
105
  };
106
- //# sourceMappingURL=cursor-enterprise.js.map
@@ -1,10 +1,12 @@
1
+ import { existsSync } from 'node:fs';
1
2
  import { homedir } from 'node:os';
2
3
  import { join } from 'node:path';
3
4
  import { cursorHooksJsonCodec } from '../core/codecs/cursor-hooks-json.js';
4
5
  import { envFileCodec } from '../core/codecs/env-file.js';
5
6
  import { hasBinary, hasPath } from '../core/detect.js';
6
7
  import { buildHeaders, HEADER_NAME, headerBearerToken, kvPairsHeaders } from '../core/headers.js';
7
- import { buildHookCommand, installedHooksDir } from '../core/markers.js';
8
+ import { buildScriptHookCommand, installedHooksDir } from '../core/markers.js';
9
+ import { isSamePath } from '../core/settings.js';
8
10
  import { VERSION } from '../core/version.js';
9
11
  const SOURCE_VALUE = 'coding_agent.cursor';
10
12
  const CONFIG_MANAGED_KEYS = ['OTEL_EXPORTER_OTLP_ENDPOINT', 'OTEL_EXPORTER_OTLP_HEADERS'];
@@ -32,7 +34,7 @@ const ALWAYS_EVENTS = [
32
34
  const PROMPT_EVENT = 'beforeSubmitPrompt';
33
35
  const hookKey = (event) => `hooks.${event}`;
34
36
  const HOOKS_MANAGED_KEYS = [...ALWAYS_EVENTS, PROMPT_EVENT].map(hookKey);
35
- const hookCommand = () => buildHookCommand(join(installedHooksDir(), 'cursor-otlp.mjs'), VERSION);
37
+ const hookCommand = () => buildScriptHookCommand(join(installedHooksDir(), 'cursor-otlp.mjs'), VERSION);
36
38
  const stripTrailingSlash = (url) => url.replace(/\/+$/, '');
37
39
  const buildHeadersValue = (apiKey, ucid) => kvPairsHeaders.encode(buildHeaders({ apiKey, ucid, source: SOURCE_VALUE }));
38
40
  const parseHeaders = (raw) => kvPairsHeaders.decode(raw) ?? {};
@@ -107,9 +109,17 @@ const hooksWrite = {
107
109
  },
108
110
  };
109
111
  const HIERARCHY = [
110
- { id: 'projectLocal', label: 'Project (local)', path: CONFIG_LOCAL, kind: 'file' },
111
112
  { id: 'user', label: 'User (global)', path: CONFIG_GLOBAL, kind: 'file' },
112
113
  ];
114
+ const LOCAL_IGNORED = `The Cursor hook ignores ${CONFIG_LOCAL}: it reads only ~/.mainwave/cursor.env`;
115
+ const collectFileChecks = () => !isSamePath(CONFIG_LOCAL, CONFIG_GLOBAL) && existsSync(CONFIG_LOCAL)
116
+ ? [
117
+ {
118
+ level: 'warn',
119
+ message: `${LOCAL_IGNORED}, so this file has no effect. Remove it.`,
120
+ },
121
+ ]
122
+ : [];
113
123
  export const cursor = {
114
124
  name: 'cursor',
115
125
  displayName: 'Cursor',
@@ -122,6 +132,7 @@ export const cursor = {
122
132
  paths: {
123
133
  local: CONFIG_LOCAL,
124
134
  global: CONFIG_GLOBAL,
135
+ localIgnored: LOCAL_IGNORED,
125
136
  },
126
137
  runInstruction: 'cursor (restart any open window so the hooks reload)',
127
138
  detect: () => hasPath(join(homedir(), '.cursor')) || hasBinary('cursor'),
@@ -131,6 +142,7 @@ export const cursor = {
131
142
  buildEnv,
132
143
  parseEnv,
133
144
  collectChecks,
145
+ collectFileChecks,
134
146
  normalizeForGenericChecks,
135
147
  additionalWrites: [hooksWrite],
136
148
  bundledHookScripts: ['marker-core.mjs', 'vocabulary.mjs', 'cursor-otlp.mjs'],
@@ -140,4 +152,3 @@ export const cursor = {
140
152
  script: 'cursor-otlp.mjs',
141
153
  },
142
154
  };
143
- //# sourceMappingURL=cursor.js.map
@@ -15,4 +15,3 @@ export const adapters = {
15
15
  [cursorEnterprise.name]: cursorEnterprise,
16
16
  };
17
17
  export const adapterNames = () => Object.keys(adapters).sort();
18
- //# sourceMappingURL=index.js.map
@@ -1,2 +1 @@
1
1
  export {};
2
- //# sourceMappingURL=types.js.map
package/dist/api/index.js CHANGED
@@ -1,2 +1 @@
1
1
  export {};
2
- //# sourceMappingURL=index.js.map
@@ -1,2 +1 @@
1
1
  export {};
2
- //# sourceMappingURL=types.gen.js.map
package/dist/cli.js CHANGED
@@ -2,4 +2,3 @@
2
2
  import { main } from './main.js';
3
3
  const code = await main(process.argv);
4
4
  process.exit(code);
5
- //# sourceMappingURL=cli.js.map