@maind-dev/mcp-bridge 0.92.0 → 0.94.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.
package/README.md CHANGED
@@ -158,6 +158,7 @@ here; the standalone `maind-hook` binary they came from is retired (ADR-245).
158
158
 
159
159
  | Subcommand | Hook event | Effect |
160
160
  |---|---|---|
161
+ | `on-session-reminder` | `SessionStart` | Add `~/.claude/maind-session-start-reminder.md` (the consultation triggers) to the session context — what the `cat` hook before 0.94.0 printed, but only to a host that can take it (see "Other hosts") |
161
162
  | `on-session-start` | `SessionStart` | Open a tracked session for the flat Tier-3 metrics |
162
163
  | `on-session-briefing` | `SessionStart` | Add the session briefing and the project conventions to the session context (see below; never blocks) |
163
164
  | `on-tool-use` | `PreToolUse` | Count tool calls; warn on stderr when token usage crosses your handoff thresholds (ADR-039) |
@@ -203,7 +204,8 @@ count what arrived. The index itself is built once by `codebase_index` (or
203
204
  says when a wired context hook has no index or no SQLite backend to read it.
204
205
  Under Cursor, which also runs the hooks in `~/.claude/settings.json`, both
205
206
  print nothing (same detection as the session-start hook); a Cursor equivalent
206
- is follow-up work.
207
+ is follow-up work. Devin Local gets the prompt context in its documented shape
208
+ and the read context not at all (see "Other hosts").
207
209
 
208
210
  ## Claude Code: conventions at session start
209
211
 
@@ -235,7 +237,8 @@ path and a 2,000-character preview.
235
237
  (its third-party import, on by default) but expects JSON there, and every
236
238
  extra session-start command slows a race in which Cursor drops injected
237
239
  context. Under Cursor (`CURSOR_VERSION` set, or `cursor_version` in the
238
- payload) this hook and `guard-inject` print nothing.
240
+ payload) this hook and `guard-inject` print nothing. Devin Local gets the
241
+ block as SessionStart `additionalContext` — see "Other hosts".
239
242
  - **Existing installs.** `install` is append-only, so updating the bridge does
240
243
  not wire the hook. `on-session-start` says so once per session, with the
241
244
  exact command — `<bridge> install --hooks-only` —, and `doctor` reports the
@@ -243,6 +246,77 @@ path and a 2,000-character preview.
243
246
  (`declined_hooks` in the bridge config) and not nagged about;
244
247
  `install --hooks-only` asks again.
245
248
 
249
+ ## Cursor: conventions at session start
250
+
251
+ Cursor documents hooks in `~/.cursor/hooks.json`, and its `sessionStart` hook
252
+ may return `additional_context` — "Additional context to add to the
253
+ conversation's initial system context" (cursor.com/docs/hooks). Since
254
+ **0.93.0**:
255
+
256
+ - **What.** `on-cursor-session-start` returns the same block the Claude Code
257
+ session-start delivery prints — project conventions first, then lessons,
258
+ skills and memory titles, under a 9,000-byte budget — as
259
+ `{"additional_context": …}`. Its stdout is always one JSON object (`{}` when
260
+ there is nothing to say), because Cursor parses it. The repository comes from
261
+ `CURSOR_PROJECT_DIR` or the payload's `workspace_roots` (user hooks run with
262
+ cwd `~/.cursor/`).
263
+ - **Where.** `install` appends one entry under `hooks.sessionStart` in
264
+ `~/.cursor/hooks.json` (creating the file with `version: 1` if needed): own
265
+ consent, append-only — foreign hooks, events and keys are left as they are,
266
+ and a file in another shape is reported, never rewritten —, idempotent,
267
+ `--dry-run` aware.
268
+ - **Only where Cursor is installed** — the same evidence the Cursor MCP target
269
+ uses (`cursorInstalled`, since 0.87.0): Cursor's app-data directory holding
270
+ more than `User`, or a `~/.cursor` holding anything besides the files the
271
+ bridge writes there (`mcp.json`, `hooks.json`). A `~/.cursor/mcp.json` alone
272
+ does not count — older bridges created it on machines without Cursor.
273
+ `--client cursor` overrides the probe.
274
+ - **Existing installs.** `install --hooks-only` offers the Cursor hook too,
275
+ where Cursor is installed — no full install needed. Cursor reloads
276
+ `~/.cursor/hooks.json` by itself.
277
+ - **Measured, not assumed.** Each delivery is noted with its
278
+ `transcript_path` in `~/.maind/cursor/deliveries.jsonl` (local only), and
279
+ `maind sessions scan-conventions --client cursor` checks the transcripts
280
+ against it. Cursor staff confirm a race in which `additional_context` can be
281
+ dropped, and `sessionStart` does not run again on resume — the `AGENTS.md`
282
+ block below is the reliable channel in Cursor. We claim nothing for Cursor
283
+ until the scan says `measured_*`.
284
+
285
+ ## Other hosts: Cursor and Devin Local run these hooks too
286
+
287
+ The hooks `install` writes into `~/.claude/settings.json` are not only Claude
288
+ Code's. Cursor imports them (Settings → Agents → Third-Party Imports, on by
289
+ default) and maps `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
290
+ `PostToolUse` and `Stop` onto its own events. Devin Local (Devin Desktop's
291
+ agent) loads them while `read_config_from.claude` is on, which is the default.
292
+ Neither reads stdout the way Claude Code does. Since **0.94.0** every hook
293
+ asks which host runs it: `cursor_version` in the payload, a transcript under
294
+ `~/.claude/projects/`, `CURSOR_VERSION`, `DEVIN_PROJECT_DIR`, in that order —
295
+ the payload first, because a hook inherits its parent's environment. It then
296
+ prints what that host can take:
297
+
298
+ | Host | What it gets |
299
+ |---|---|
300
+ | Claude Code (or a host we cannot identify) | Exactly what it got before — plain text at session start, `hookSpecificOutput` JSON elsewhere |
301
+ | Cursor | One JSON object in Cursor's own shape, or nothing — never plain text. A refused `Write` is `permission: "deny"` with the reason for you and the agent; session-start text and context stay out (Cursor's own `sessionStart` hook — see above — and `AGENTS.md` carry the briefing there) |
302
+ | Devin Local | Claude Code's JSON where Devin documents it: `additionalContext` at `SessionStart`, `UserPromptSubmit` and `PostToolUse`, `decision: "block"` for a refusal. Nothing at `PreToolUse`, never plain text |
303
+
304
+ Whether the context reaches the model in Devin Local is **not measured**. To
305
+ keep every hook silent there, set `MAIND_DEVIN_HOOK_OUTPUT=off`, or
306
+ `"devin_hook_output": false` in the bridge's `config.json`. The guard pack
307
+ (`guard install`) judges only in Claude Code: what it relies on — the briefing
308
+ stamp, maind consultations, Claude Code's tool names — cannot be observed
309
+ elsewhere, so it neither warns nor blocks there.
310
+
311
+ **The reminder hook.** Before 0.94.0 the SessionStart reminder was the shell
312
+ command `cat ~/.claude/maind-session-start-reminder.md`, plain text for every
313
+ host. It is now the subcommand `on-session-reminder`. `install` and
314
+ `install --hooks-only` replace a `cat` entry in the form an earlier install
315
+ wrote in place, after asking — the one entry they rewrite. A command of your
316
+ own on that file stays as it is and is named with its replacement. `doctor`
317
+ reports an old `cat` (`hook-hosts`, a warning when Cursor is installed), and
318
+ the session-start line names the command while Cursor is installed.
319
+
246
320
  ## AGENTS.md readers: conventions via AGENTS.md
247
321
 
248
322
  Measured on 2026-09-30 over 76 Codex rollouts: the MCP `instructions` never
@@ -321,6 +395,7 @@ either.
321
395
  | `~/.maind/guard/agents-md-refresh.json` | When the `AGENTS.md` conventions block was last checked, per project (path hashed; mode 0600) |
322
396
  | `~/.maind/guard/briefing-cache.json` | The last session briefing + conventions, for the session-start hook and the `AGENTS.md` block (12 h; mode 0600) |
323
397
  | `~/.maind/context/<session>/` | Once-per-session markers of the context hooks: one empty file per delivered item, named by a hash; swept after 7 days |
398
+ | `~/.maind/cursor/deliveries.jsonl` | What the Cursor sessionStart hook delivered: conversation id, transcript path, size (local, pruned; mode 0600) |
324
399
 
325
400
  To rebind the bridge to a different account: delete the directory above (or run
326
401
  `--reauth`) and restart the bridge.
@@ -356,6 +431,7 @@ Rarely useful outside maind's own development environments:
356
431
  | `MAIND_FUNCTIONS_ORIGIN` | maind's Supabase Edge Functions URL | Device-flow base URL |
357
432
  | `MAIND_NO_AGENTS_MD_REFRESH` | unset | Set to `1` to stop the bridge from refreshing the conventions block in `AGENTS.md` for Codex sessions (see above) |
358
433
  | `MAIND_DEBUG` | unset | Set to `1` for one diagnostic stderr line on the otherwise silent AGENTS.md skip (no file with the header inside the repository) |
434
+ | `MAIND_DEVIN_HOOK_OUTPUT` | `on` | `off` keeps every hook silent when Devin Local runs it (same as `"devin_hook_output": false` in `config.json`; see "Other hosts") |
359
435
  | `XDG_CONFIG_HOME` | `~/.config` (Linux/BSD) | Parent of the `maind/` config dir |
360
436
 
361
437
  ## License