@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 +78 -2
- package/build/index.js +270 -256
- package/build/meta.json +1 -1
- package/package.json +1 -1
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
|