@maind-dev/mcp-bridge 0.93.0 → 0.95.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
@@ -105,39 +105,52 @@ again unless you re-pair).
105
105
  |---|---|---|
106
106
  | Claude Code (project) | `<project>/.mcp.json` | always |
107
107
  | Claude Code (user) | `~/.claude.json` | always |
108
- | Claude Desktop | `claude_desktop_config.json` (per-OS path) | always |
108
+ | Claude Desktop | `claude_desktop_config.json` (per-OS path) | Claude Desktop is installed, or `--client claude-desktop` |
109
109
  | Cursor | `~/.cursor/mcp.json` | Cursor is installed, or `--client cursor` |
110
110
  | Devin Desktop (formerly Windsurf) | Devin's own `mcp_config.json` — `~/.config/devin/` on macOS and Linux (`$XDG_CONFIG_HOME/devin/` when set), `%APPDATA%\devin\` on Windows; the Devin CLI reads it too | Devin Desktop is installed, or `--client windsurf` (alias `--client devin`) |
111
111
  | Devin Desktop, legacy file | `~/.codeium/windsurf/mcp_config.json` — Devin imports it; an existing `maind` entry is kept current, the file is never created and never gets an entry | Devin Desktop is installed and the entry is already there |
112
112
  | GitHub Copilot (VS Code) | user-profile `mcp.json` (per-OS path, `servers` shape) | VS Code is installed, or `--client copilot` |
113
113
  | Cline | `~/.cline/data/settings/cline_mcp_settings.json` — one file for Cline in every editor, its CLI and Cline Desktop | Cline is installed, or `--client cline` |
114
114
  | Continue | `~/.continue/mcpServers/maind.json` — a file of its own; `config.yaml` is never touched | Continue is installed, or `--client continue` |
115
- | Codex CLI | `~/.codex/config.toml` | always, unless `--skip-codex` |
116
-
117
- A client that is not installed gets no file of ours (since **0.85.0** for Cursor
118
- and Windsurf, **0.83.0** for VS Code, **0.87.0** for Cline and Continue).
119
- Windsurf became Devin Desktop on 2026-06-02; since **0.92.0** the bridge writes
120
- Devin's own file — the family id stays `windsurf` in every config it writes.
121
- "Installed" means a trace only the client leaves, never a file or directory the
122
- bridge writes itself (since **0.87.0** — bridges up to 0.84.0 wrote
123
- `~/.cursor/mcp.json` and `~/.codeium/windsurf/mcp_config.json` on every
124
- machine):
115
+ | Codex CLI | `config.toml` in Codex's home — `~/.codex/`, or `$CODEX_HOME` when set (absolute paths only); the Codex IDE extension and the ChatGPT desktop app share it | Codex is installed, or `--client codex`; `--skip-codex` leaves an installed Codex out |
116
+
117
+ Only Claude Code's two files are written on every machine. A client that is not
118
+ installed gets no file of ours (since **0.85.0** for Cursor and Windsurf,
119
+ **0.83.0** for VS Code, **0.87.0** for Cline and Continue, **0.95.0** for Claude
120
+ Desktop and Codex). Windsurf became Devin Desktop on 2026-06-02; since
121
+ **0.92.0** the bridge writes Devin's own file — the family id stays `windsurf`
122
+ in every config it writes. "Installed" means a trace only the client leaves,
123
+ never a file or directory the bridge writes itself (since **0.87.0** — bridges
124
+ up to 0.84.0 wrote `~/.cursor/mcp.json` and
125
+ `~/.codeium/windsurf/mcp_config.json` on every machine, bridges up to 0.94.0
126
+ Claude Desktop's and Codex's files):
125
127
 
126
128
  | Client | Counts as installed when |
127
129
  |---|---|
130
+ | Claude Desktop | its app data (`~/Library/Application Support/Claude`, `%APPDATA%\Claude`, `~/.config/Claude`) holds more than `claude_desktop_config.json`; on macOS also `/Applications/Claude.app` or `~/Applications/Claude.app`; on Windows also `%LOCALAPPDATA%\AnthropicClaude` (the .exe install) or `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc` (the MSIX install) |
128
131
  | Cursor | its app data (`~/Library/Application Support/Cursor`, `%APPDATA%\Cursor`, `~/.config/Cursor`) holds more than `User/`, or `~/.cursor` holds more than `mcp.json` / `hooks.json` |
129
132
  | Devin Desktop (formerly Windsurf) | its app data (`~/Library/Application Support/Devin`, `%APPDATA%\Devin`, `~/.config/Devin`) holds more than `User/` (and, on Windows, where it is the same directory as `%APPDATA%\devin`, more than our `mcp_config.json`), `~/.devin` exists, Devin's config dir holds more than `mcp_config.json`, Windsurf's app data (`…/Windsurf`) holds more than `User/`, or `~/.codeium/windsurf` holds more than `mcp_config.json` |
130
133
  | VS Code | its app data (`…/Code`) holds more than `User/` |
131
- | Cline | `~/.cline/data` holds more than `settings/`, or an editor (Code, Code - Insiders, Cursor, VSCodium, Windsurf, Devin, AgentComposer) has Cline's `User/globalStorage/saoudrizwan.claude-dev` |
132
- | Continue | `~/.continue` holds more than `mcpServers/` |
134
+ | Cline | `~/.cline/data` holds more than `settings/`, an editor (Code, Code - Insiders, Cursor, VSCodium, Windsurf, Devin, AgentComposer) has Cline's `User/globalStorage/saoudrizwan.claude-dev`, or Cline's extension folder (`saoudrizwan.claude-dev-<version>`) is in an editor's extensions dir — see below |
135
+ | Continue | `~/.continue` holds more than `mcpServers/`, or Continue's extension folder (`continue.continue-<version>`) is in an editor's extensions dir — see below |
136
+ | Codex | its home (`$CODEX_HOME`, else `~/.codex`) holds more than `config.toml` — Codex keeps `auth.json`, `sessions/`, `history.jsonl`, … there; with `CODEX_HOME` set, a `~/.codex` beyond `config.toml` counts too |
137
+
138
+ An agent that ships as an editor extension counts as installed once its folder
139
+ is there, before it ever ran (since **0.95.0**): the editors' per-user
140
+ extensions dirs (`~/.vscode`, `~/.vscode-insiders`, `~/.cursor`, `~/.vscode-oss`,
141
+ `~/.windsurf`, `~/.devin`, `~/.agentcomposer`, each `/extensions`), the builtins
142
+ of the app bundle the bridge itself runs from (`<App>.app/Contents/Resources/app/extensions`),
143
+ and on macOS AgentComposer's builtins at `/Applications` or `~/Applications` —
144
+ AgentComposer ships Cline and Continue built in, and on its first start
145
+ neither has data of its own yet.
133
146
 
134
147
  The report shows a skipped client as `skipped` with the reason (e.g. `Cursor
135
148
  not found (no Cursor app data, nothing of Cursor's in ~/.cursor)`); when a
136
149
  leftover file sits there, the row says so. The exit code stays 0.
137
150
  Naming the family with `--client` is the explicit request that overrides the
138
- probe. `CLINE_DIR`, `CLINE_DATA_DIR`, `CLINE_MCP_SETTINGS_PATH` and
139
- `CONTINUE_GLOBAL_DIR` move the Cline and Continue files the way the clients
140
- resolve them (absolute paths only).
151
+ probe. `CLINE_DIR`, `CLINE_DATA_DIR`, `CLINE_MCP_SETTINGS_PATH`,
152
+ `CONTINUE_GLOBAL_DIR` and `CODEX_HOME` move the Cline, Continue and Codex files
153
+ the way the clients resolve them (absolute paths only).
141
154
 
142
155
  ### Leftover configs: `doctor --remove-phantoms`
143
156
 
@@ -146,7 +159,9 @@ as a **phantom** — nothing reads it. `doctor --remove-phantoms` lists what it
146
159
  would do and changes nothing; `doctor --remove-phantoms --yes` applies the same
147
160
  list. A file that holds only maind's entry is deleted; a file with anything
148
161
  else in it (other servers, other keys, comments) loses only maind's entry,
149
- every other byte stays.
162
+ every other byte stays. Codex's `config.toml` follows the same rules: only
163
+ `[mcp_servers.maind]` and its sub-tables are cut out, and an entry that is not
164
+ in tables of its own is listed for removal by hand, never touched.
150
165
 
151
166
  ### Claude Code hook subcommands
152
167
 
@@ -158,6 +173,7 @@ here; the standalone `maind-hook` binary they came from is retired (ADR-245).
158
173
 
159
174
  | Subcommand | Hook event | Effect |
160
175
  |---|---|---|
176
+ | `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
177
  | `on-session-start` | `SessionStart` | Open a tracked session for the flat Tier-3 metrics |
162
178
  | `on-session-briefing` | `SessionStart` | Add the session briefing and the project conventions to the session context (see below; never blocks) |
163
179
  | `on-tool-use` | `PreToolUse` | Count tool calls; warn on stderr when token usage crosses your handoff thresholds (ADR-039) |
@@ -203,7 +219,8 @@ count what arrived. The index itself is built once by `codebase_index` (or
203
219
  says when a wired context hook has no index or no SQLite backend to read it.
204
220
  Under Cursor, which also runs the hooks in `~/.claude/settings.json`, both
205
221
  print nothing (same detection as the session-start hook); a Cursor equivalent
206
- is follow-up work.
222
+ is follow-up work. Devin Local gets the prompt context in its documented shape
223
+ and the read context not at all (see "Other hosts").
207
224
 
208
225
  ## Claude Code: conventions at session start
209
226
 
@@ -235,7 +252,8 @@ path and a 2,000-character preview.
235
252
  (its third-party import, on by default) but expects JSON there, and every
236
253
  extra session-start command slows a race in which Cursor drops injected
237
254
  context. Under Cursor (`CURSOR_VERSION` set, or `cursor_version` in the
238
- payload) this hook and `guard-inject` print nothing.
255
+ payload) this hook and `guard-inject` print nothing. Devin Local gets the
256
+ block as SessionStart `additionalContext` — see "Other hosts".
239
257
  - **Existing installs.** `install` is append-only, so updating the bridge does
240
258
  not wire the hook. `on-session-start` says so once per session, with the
241
259
  exact command — `<bridge> install --hooks-only` —, and `doctor` reports the
@@ -279,6 +297,41 @@ conversation's initial system context" (cursor.com/docs/hooks). Since
279
297
  block below is the reliable channel in Cursor. We claim nothing for Cursor
280
298
  until the scan says `measured_*`.
281
299
 
300
+ ## Other hosts: Cursor and Devin Local run these hooks too
301
+
302
+ The hooks `install` writes into `~/.claude/settings.json` are not only Claude
303
+ Code's. Cursor imports them (Settings → Agents → Third-Party Imports, on by
304
+ default) and maps `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
305
+ `PostToolUse` and `Stop` onto its own events. Devin Local (Devin Desktop's
306
+ agent) loads them while `read_config_from.claude` is on, which is the default.
307
+ Neither reads stdout the way Claude Code does. Since **0.94.0** every hook
308
+ asks which host runs it: `cursor_version` in the payload, a transcript under
309
+ `~/.claude/projects/`, `CURSOR_VERSION`, `DEVIN_PROJECT_DIR`, in that order —
310
+ the payload first, because a hook inherits its parent's environment. It then
311
+ prints what that host can take:
312
+
313
+ | Host | What it gets |
314
+ |---|---|
315
+ | Claude Code (or a host we cannot identify) | Exactly what it got before — plain text at session start, `hookSpecificOutput` JSON elsewhere |
316
+ | 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) |
317
+ | 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 |
318
+
319
+ Whether the context reaches the model in Devin Local is **not measured**. To
320
+ keep every hook silent there, set `MAIND_DEVIN_HOOK_OUTPUT=off`, or
321
+ `"devin_hook_output": false` in the bridge's `config.json`. The guard pack
322
+ (`guard install`) judges only in Claude Code: what it relies on — the briefing
323
+ stamp, maind consultations, Claude Code's tool names — cannot be observed
324
+ elsewhere, so it neither warns nor blocks there.
325
+
326
+ **The reminder hook.** Before 0.94.0 the SessionStart reminder was the shell
327
+ command `cat ~/.claude/maind-session-start-reminder.md`, plain text for every
328
+ host. It is now the subcommand `on-session-reminder`. `install` and
329
+ `install --hooks-only` replace a `cat` entry in the form an earlier install
330
+ wrote in place, after asking — the one entry they rewrite. A command of your
331
+ own on that file stays as it is and is named with its replacement. `doctor`
332
+ reports an old `cat` (`hook-hosts`, a warning when Cursor is installed), and
333
+ the session-start line names the command while Cursor is installed.
334
+
282
335
  ## AGENTS.md readers: conventions via AGENTS.md
283
336
 
284
337
  Measured on 2026-09-30 over 76 Codex rollouts: the MCP `instructions` never
@@ -393,6 +446,7 @@ Rarely useful outside maind's own development environments:
393
446
  | `MAIND_FUNCTIONS_ORIGIN` | maind's Supabase Edge Functions URL | Device-flow base URL |
394
447
  | `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) |
395
448
  | `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) |
449
+ | `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") |
396
450
  | `XDG_CONFIG_HOME` | `~/.config` (Linux/BSD) | Parent of the `maind/` config dir |
397
451
 
398
452
  ## License