@maind-dev/mcp-bridge 0.87.0 → 0.88.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
@@ -93,6 +93,7 @@ again unless you re-pair).
93
93
  |---|---|
94
94
  | `npx -y @maind-dev/mcp-bridge` | Run as MCP server (default; what your IDE invokes) |
95
95
  | `npx -y @maind-dev/mcp-bridge install` | One-shot setup: MCP configs, preamble files, Claude Code hooks |
96
+ | `maind-mcp-bridge install --hooks-only` | Only the Claude Code hooks — adds what an existing install is missing (no pairing, no configs, no preamble) |
96
97
  | `npx -y @maind-dev/mcp-bridge --reauth` | Drop the cached key and re-run the device flow |
97
98
  | `npx -y @maind-dev/mcp-bridge doctor` | Offline self-diagnosis with fix commands (`--json`; `--remove-phantoms [--yes]`, see below) |
98
99
  | `npx -y @maind-dev/mcp-bridge --version` | Print the bridge version |
@@ -155,6 +156,7 @@ here; the standalone `maind-hook` binary they came from is retired (ADR-245).
155
156
  | Subcommand | Hook event | Effect |
156
157
  |---|---|---|
157
158
  | `on-session-start` | `SessionStart` | Open a tracked session for the flat Tier-3 metrics |
159
+ | `on-session-briefing` | `SessionStart` | Add the session briefing and the project conventions to the session context (see below; never blocks) |
158
160
  | `on-tool-use` | `PreToolUse` | Count tool calls; warn on stderr when token usage crosses your handoff thresholds (ADR-039) |
159
161
  | `on-session-end` | `Stop` | Post session communication analytics; close and flush the tracked session |
160
162
  | `sync-config` | — | Pull your context thresholds from the server |
@@ -166,6 +168,44 @@ Everything these post is gated server-side by Tier-3 consent
166
168
  Thresholds are set at <https://app.maind.dev/settings>; run `sync-config`
167
169
  afterwards on each machine.
168
170
 
171
+ ## Claude Code: conventions at session start
172
+
173
+ Claude Code cuts the MCP `instructions` after about 2,000 characters
174
+ (measured 2026-10-04: 9 of 21 conventions visible). The channel that arrives
175
+ whole is a SessionStart hook whose output stays under Claude Code's
176
+ 10,000-character hook limit — above it, Claude Code swaps the output for a file
177
+ path and a 2,000-character preview.
178
+
179
+ - **What.** `on-session-briefing` (since **0.88.0**) prints the project
180
+ conventions first, then your top lessons, skills and memory titles, rendered
181
+ compactly under a 9,000-byte budget; what does not fit is named (`+N more —
182
+ via …`), never cut silently. It runs on `startup`, `clear` and `compact` (a
183
+ compaction summarises the earlier block away); `resume` and `fork` keep the
184
+ earlier one.
185
+ - **Where it comes from.** The same cache-first ladder as the guard: the
186
+ local cache `~/.maind/guard/briefing-cache.json` (fresh for 12 h, for the
187
+ same project), else
188
+ one fetch from mcp.maind.dev with a 3-second budget (API key, device id,
189
+ project key, client family — never paths or file contents), else the stale
190
+ cache with a note. With nothing at all, one line tells the model to call
191
+ `get_session_briefing` itself.
192
+ - **Delivery, not enforcement.** It is a core hook: `install` offers it with
193
+ its own consent, `install --full` (the dashboard's One-Click path) wires it,
194
+ and it works with the guard off. The guard pack's `guard-inject` delivers
195
+ the same block; when both are wired, `guard-inject` stays silent, so the
196
+ briefing arrives once.
197
+ - **Not in Cursor.** Cursor also runs the hooks in `~/.claude/settings.json`
198
+ (its third-party import, on by default) but expects JSON there, and every
199
+ extra session-start command slows a race in which Cursor drops injected
200
+ context. Under Cursor (`CURSOR_VERSION` set, or `cursor_version` in the
201
+ payload) this hook and `guard-inject` print nothing.
202
+ - **Existing installs.** `install` is append-only, so updating the bridge does
203
+ not wire the hook. `on-session-start` says so once per session, with the
204
+ exact command — `<bridge> install --hooks-only` —, and `doctor` reports the
205
+ channel (`session-start`). A hook you declined at the prompt is remembered
206
+ (`declined_hooks` in the bridge config) and not nagged about;
207
+ `install --hooks-only` asks again.
208
+
169
209
  ## Codex: conventions via AGENTS.md
170
210
 
171
211
  Measured on 2026-09-30 over 76 Codex rollouts: the MCP `instructions` never
@@ -224,6 +264,7 @@ appending it once and leaving it to age.
224
264
  | `device-id`-sibling file `api-key` | API key returned by approve flow (mode 0600) |
225
265
  | `~/.maind/state.json` | Hook subcommand state: tracked sessions, queued Tier-3 metrics, synced thresholds (mode 0600) |
226
266
  | `~/.maind/guard/agents-md-refresh.json` | When the Codex `AGENTS.md` conventions block was last checked, per project (path hashed; mode 0600) |
267
+ | `~/.maind/guard/briefing-cache.json` | The last session briefing + conventions, for the session-start hook and the `AGENTS.md` block (12 h; mode 0600) |
227
268
 
228
269
  To rebind the bridge to a different account: delete the directory above (or run
229
270
  `--reauth`) and restart the bridge.