@maind-dev/mcp-bridge 0.104.0 → 0.106.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 +86 -22
- package/build/index.js +350 -338
- package/build/meta.json +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -171,15 +171,15 @@ names it:
|
|
|
171
171
|
| Client | Channel | Where |
|
|
172
172
|
|---|---|---|
|
|
173
173
|
| Claude Code | hooks: session briefing with the full convention set, prompt and read context (see below); no `CLAUDE.md` block | `~/.claude/settings.json` — or the Claude Code plugin `maind` (`maind@maind`): with the plugin enabled, `install` writes no hooks there and no server into `~/.claude.json` |
|
|
174
|
-
| Codex |
|
|
174
|
+
| Codex | hooks, one entry per event: session briefing, prompt context, edit guards, turn end (see "Codex and GitHub Copilot") | `config.toml` in Codex's home (`~/.codex/`, or `$CODEX_HOME`) |
|
|
175
175
|
| Devin Desktop | Claude Code's hooks (it loads `~/.claude/settings.json`) | — no own entry |
|
|
176
176
|
| Cursor | `sessionStart` hook (a race Cursor confirms can drop its context — see "The team option") | `~/.cursor/hooks.json` |
|
|
177
|
-
| GitHub Copilot (VS Code) | user instructions, `applyTo: "**"` | `~/.copilot/instructions/maind.instructions.md` |
|
|
177
|
+
| GitHub Copilot (VS Code, Copilot CLI) | hooks, one entry per event (see "Codex and GitHub Copilot"); user instructions, `applyTo: "**"` | `~/.copilot/hooks/maind.json`; `~/.copilot/instructions/maind.instructions.md` |
|
|
178
178
|
| Cline | global rule (always active without frontmatter) | `<Documents>/Cline/Rules/maind.md` |
|
|
179
179
|
| Continue | global rule, `alwaysApply: true` | `~/.continue/rules/maind.md` (or `$CONTINUE_GLOBAL_DIR/rules/`) |
|
|
180
180
|
| Claude Desktop | the MCP `instructions` only | — |
|
|
181
181
|
|
|
182
|
-
`--no-hook` leaves out every hook (Claude Code's, Cursor's, Codex's),
|
|
182
|
+
`--no-hook` leaves out every hook (Claude Code's, Cursor's, Codex's, Copilot's),
|
|
183
183
|
`--no-rules` every rule file. `--no-preamble` is accepted for old scripts and
|
|
184
184
|
does nothing. `install --hooks-only` sets up the channels an existing install is
|
|
185
185
|
missing. Blocks an earlier install wrote into a repository stay effective until
|
|
@@ -369,7 +369,8 @@ prints what that host can take:
|
|
|
369
369
|
| Claude Code (or a host we cannot identify) | Exactly what it got before — plain text at session start, `hookSpecificOutput` JSON elsewhere |
|
|
370
370
|
| 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 — carries the briefing there, and with the team option `AGENTS.md`) |
|
|
371
371
|
| 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 |
|
|
372
|
-
| Codex (since 0.100.0) | Runs `on-
|
|
372
|
+
| Codex (since 0.100.0; every core hook since 0.105.0) | Runs `on-hook --host=codex …` from its own `config.toml`; gets exactly Claude Code's JSON shapes — `hookSpecificOutput.additionalContext`, the PreToolUse deny — and nothing more, because Codex rejects an output with an unknown field. Session-start text as JSON too: Codex parses plain text that starts with `[` as JSON. Recognised by the `--host=codex` the installer writes, else by a Codex rollout transcript (`…/sessions/YYYY/MM/DD/rollout-….jsonl`) |
|
|
373
|
+
| GitHub Copilot (since 0.105.0) | Runs `on-hook --host=copilot …` from `~/.copilot/hooks/maind.json`, in VS Code's agent and in the Copilot CLI. Every answer carries its context twice — in `hookSpecificOutput` (VS Code reads only that) and as a top-level `additionalContext` (the Copilot CLI reads that for SessionStart, prompts and PostToolUse) — so each reads it once. Recognised by `--host=copilot`, else by VS Code's transcript path (`…/GitHub.copilot-chat/transcripts/…`), `COPILOT_PROJECT_DIR`, or an ISO `timestamp` with `hook_event_name` |
|
|
373
374
|
|
|
374
375
|
Whether the context reaches the model in Devin Local is **not measured**. To
|
|
375
376
|
keep every hook silent there, set `MAIND_DEVIN_HOOK_OUTPUT=off`, or
|
|
@@ -387,35 +388,97 @@ own on that file stays as it is and is named with its replacement. `doctor`
|
|
|
387
388
|
reports an old `cat` (`hook-hosts`, a warning when Cursor is installed), and
|
|
388
389
|
the session-start line names the command while Cursor is installed.
|
|
389
390
|
|
|
390
|
-
## Codex:
|
|
391
|
+
## Codex and GitHub Copilot: the core hooks (since 0.105.0)
|
|
391
392
|
|
|
392
|
-
Codex
|
|
393
|
-
|
|
393
|
+
Codex (learn.chatgpt.com/docs/hooks) and GitHub Copilot — VS Code's agent and
|
|
394
|
+
the Copilot CLI, which both read `~/.copilot/hooks/*.json` — run hook commands
|
|
395
|
+
on the events Claude Code has, with Claude Code's snake_case payload. So
|
|
396
|
+
`install` gives them the core hooks, where Codex or Copilot is installed (or
|
|
397
|
+
with `--client codex` / `--client copilot`): **one entry per event**, carrying
|
|
398
|
+
the hooks you agreed to — consent is still asked per hook.
|
|
394
399
|
|
|
395
400
|
```toml
|
|
401
|
+
# ~/.codex/config.toml (an excerpt)
|
|
396
402
|
[features]
|
|
397
403
|
hooks = true
|
|
398
404
|
|
|
399
405
|
[[hooks.SessionStart]]
|
|
400
406
|
[[hooks.SessionStart.hooks]]
|
|
401
407
|
type = "command"
|
|
402
|
-
command = "<bridge> on-
|
|
403
|
-
timeout =
|
|
408
|
+
command = "<bridge> on-hook --host=codex on-session-reminder on-session-start on-session-briefing"
|
|
409
|
+
timeout = 20
|
|
404
410
|
additionalContextLimit = 4000
|
|
411
|
+
|
|
412
|
+
[[hooks.PostToolUse]]
|
|
413
|
+
matcher = "apply_patch"
|
|
414
|
+
[[hooks.PostToolUse.hooks]]
|
|
415
|
+
type = "command"
|
|
416
|
+
command = "<bridge> on-hook --host=codex on-write-health"
|
|
417
|
+
timeout = 10
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
```json
|
|
421
|
+
// ~/.copilot/hooks/maind.json (an excerpt)
|
|
422
|
+
{
|
|
423
|
+
"version": 1,
|
|
424
|
+
"hooks": {
|
|
425
|
+
"PreToolUse": [
|
|
426
|
+
{ "type": "command", "command": "<bridge> on-hook --host=copilot on-tool-use on-file-write on-file-edit on-repo-health on-read-context || true", "timeout": 30 }
|
|
427
|
+
]
|
|
428
|
+
}
|
|
429
|
+
}
|
|
405
430
|
```
|
|
406
431
|
|
|
407
|
-
- **
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
432
|
+
- **One entry per event, not per hook.** VS Code's agent ignores matchers and
|
|
433
|
+
runs an event's commands one after another; six bridge processes before and
|
|
434
|
+
after every tool call would cost a third of a second per call. Codex asks
|
|
435
|
+
you to trust each new entry once (`/hooks`). `on-hook` reads the payload
|
|
436
|
+
once and runs the named hooks in one process; a hook that fails costs only
|
|
437
|
+
its own answer.
|
|
438
|
+
- **Matchers** only where every hook of the entry is about files: Codex
|
|
439
|
+
`apply_patch` (its exact tool name; `Edit` and `Write` are aliases), Copilot
|
|
440
|
+
`Edit|Write` / `Read` in the Copilot CLI's Claude names. VS Code ignores
|
|
441
|
+
them — every file hook reads the call itself.
|
|
442
|
+
- **File acts in each host's vocabulary.** Codex edits through `apply_patch`
|
|
443
|
+
with the patch text in `tool_input.command`; the hooks read only its
|
|
444
|
+
file-header lines (`*** Add File:` is a new file, `*** Update File:` an
|
|
445
|
+
edit). VS Code: `create_file`, `replace_string_in_file`,
|
|
446
|
+
`multi_replace_string_in_file`, `insert_edit_into_file`, `apply_patch`,
|
|
447
|
+
`read_file` with `filePath`. The Copilot CLI: Claude's names with `path`.
|
|
448
|
+
- **Fail-open.** Every Copilot command ends in `|| true` (PowerShell:
|
|
449
|
+
`; exit 0`): in the Copilot CLI a PreToolUse command that exits non-zero
|
|
450
|
+
denies the tool call, and a moved bridge must not do that.
|
|
412
451
|
- **Trust.** Codex runs a new hook only after you trust it: open `/hooks` in
|
|
413
|
-
Codex once.
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
`
|
|
452
|
+
Codex once. VS Code needs `chat.useHooks` (on by default; an organisation
|
|
453
|
+
can turn it off with the `ChatHooks` policy); the Copilot CLI reads the file
|
|
454
|
+
at its next start.
|
|
455
|
+
- **Append-only, idempotent per hook.** Every other key, table and hook stays
|
|
456
|
+
— in `config.toml` byte for byte (comments and layout included), in
|
|
457
|
+
`maind.json` every entry that is not ours. A hook whose subcommand a command
|
|
458
|
+
of its event already carries — in `config.toml` or `hooks.json`, in any file
|
|
459
|
+
in `~/.copilot/hooks` — counts as wired; the `on-session-briefing
|
|
460
|
+
--host=codex` entry of 0.100–0.104 included, so an upgrade adds the rest
|
|
461
|
+
beside it. `[features] hooks = false` is your "no" and is reported, never
|
|
462
|
+
flipped.
|
|
463
|
+
- **Once, not twice.** VS Code runs Claude Code's hooks from
|
|
464
|
+
`~/.claude/settings.json` too when you turn on `chat.useClaudeHooks` (off by
|
|
465
|
+
default). A hook that finds itself there, without `--host=copilot`, stands
|
|
466
|
+
down for every hook `maind.json` already runs.
|
|
467
|
+
|
|
468
|
+
What does not exist there is not wired — the report names it as a `gap(…)`
|
|
469
|
+
row, and `doctor` lists it:
|
|
470
|
+
|
|
471
|
+
| Hook | Codex | Copilot |
|
|
472
|
+
|---|---|---|
|
|
473
|
+
| `on-read-context` | **not wired** — Codex has no file-read tool; it reads through the shell (`Bash`) | VS Code `read_file`, the CLI `view` |
|
|
474
|
+
| `on-prompt-context` | yes | VS Code yes; the Copilot CLI documents command-hook output on a prompt as dropped |
|
|
475
|
+
| `on-file-write`, `on-file-edit`, `on-repo-health`, `on-write-health` | edits through `apply_patch`; a file a shell command writes passes no file hook | yes |
|
|
476
|
+
| `on-tool-use` | counts calls; the token advisory reads Claude Code transcripts only | the same |
|
|
477
|
+
| `on-session-end` | closes the turn's counters, sends the Tier-3 metrics; analytics and cost slices come from `maind sessions backfill`, not from the hook | closes the counters, sends the metrics; Copilot's transcripts are not analysed |
|
|
478
|
+
| The guard pack | stands down outside Claude Code | the same |
|
|
479
|
+
|
|
480
|
+
`doctor --remove-phantoms` takes out of `config.toml` exactly what `install`
|
|
481
|
+
put in — every maind handler, of any event, and a marked `[features] hooks`.
|
|
419
482
|
|
|
420
483
|
## User-level rule files: Copilot, Cline, Continue
|
|
421
484
|
|
|
@@ -483,8 +546,9 @@ SessionStart hook names the migration once per repository.
|
|
|
483
546
|
- `doctor --migrate-repo-blocks` lists the blocks and the user-level channels
|
|
484
547
|
that carry the same content, and changes nothing.
|
|
485
548
|
- `doctor --migrate-repo-blocks --yes` sets those channels up first (Claude
|
|
486
|
-
Code's reminder and briefing hooks unless the plugin carries them, Cursor's
|
|
487
|
-
and
|
|
549
|
+
Code's reminder and briefing hooks unless the plugin carries them, Cursor's,
|
|
550
|
+
Codex's and Copilot's hooks, the rule files — for the clients installed
|
|
551
|
+
here) and stops
|
|
488
552
|
without removing anything if one fails; then it removes exactly the listed
|
|
489
553
|
blocks. Only lines between maind markers go (and the blank line the installer
|
|
490
554
|
put before them); every other byte stays, with its own line endings. A file
|