@maind-dev/mcp-bridge 0.103.0 → 0.105.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 +119 -22
- package/build/index.js +358 -320
- package/build/meta.json +1 -1
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -96,6 +96,7 @@ again unless you re-pair).
|
|
|
96
96
|
| `npx -y @maind-dev/mcp-bridge install --team` | The same, plus — deliberately — the conventions block in the repository's `AGENTS.md` and the project `.mcp.json` |
|
|
97
97
|
| `maind-mcp-bridge install --hooks-only` | Only the user-level channels — adds what an existing install is missing (no pairing, no MCP configs) |
|
|
98
98
|
| `maind-mcp-bridge refresh-rules` | Refresh the user-level rule files with the conventions of a repository (`--project-root <dir>`, `--force`, `--json`; see below) |
|
|
99
|
+
| `maind-mcp-bridge activity [on\|off\|status]` | Opt-in: Claude Code sessions report their agent activity to the work object they are bound to (see "Agent activity from Claude Code sessions") |
|
|
99
100
|
| `npx -y @maind-dev/mcp-bridge --reauth` | Drop the cached key and re-run the device flow |
|
|
100
101
|
| `npx -y @maind-dev/mcp-bridge doctor` | Offline self-diagnosis with fix commands (`--json`; `--remove-phantoms`, `--migrate-repo-blocks`, `--remove-duplicate-hooks`, `--remove-duplicate-mcp`, each `[--yes]`, see below) |
|
|
101
102
|
| `npx -y @maind-dev/mcp-bridge --version` | Print the bridge version |
|
|
@@ -170,15 +171,15 @@ names it:
|
|
|
170
171
|
| Client | Channel | Where |
|
|
171
172
|
|---|---|---|
|
|
172
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` |
|
|
173
|
-
| 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`) |
|
|
174
175
|
| Devin Desktop | Claude Code's hooks (it loads `~/.claude/settings.json`) | — no own entry |
|
|
175
176
|
| Cursor | `sessionStart` hook (a race Cursor confirms can drop its context — see "The team option") | `~/.cursor/hooks.json` |
|
|
176
|
-
| 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` |
|
|
177
178
|
| Cline | global rule (always active without frontmatter) | `<Documents>/Cline/Rules/maind.md` |
|
|
178
179
|
| Continue | global rule, `alwaysApply: true` | `~/.continue/rules/maind.md` (or `$CONTINUE_GLOBAL_DIR/rules/`) |
|
|
179
180
|
| Claude Desktop | the MCP `instructions` only | — |
|
|
180
181
|
|
|
181
|
-
`--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),
|
|
182
183
|
`--no-rules` every rule file. `--no-preamble` is accepted for old scripts and
|
|
183
184
|
does nothing. `install --hooks-only` sets up the channels an existing install is
|
|
184
185
|
missing. Blocks an earlier install wrote into a repository stay effective until
|
|
@@ -368,7 +369,8 @@ prints what that host can take:
|
|
|
368
369
|
| Claude Code (or a host we cannot identify) | Exactly what it got before — plain text at session start, `hookSpecificOutput` JSON elsewhere |
|
|
369
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`) |
|
|
370
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 |
|
|
371
|
-
| 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` |
|
|
372
374
|
|
|
373
375
|
Whether the context reaches the model in Devin Local is **not measured**. To
|
|
374
376
|
keep every hook silent there, set `MAIND_DEVIN_HOOK_OUTPUT=off`, or
|
|
@@ -386,35 +388,97 @@ own on that file stays as it is and is named with its replacement. `doctor`
|
|
|
386
388
|
reports an old `cat` (`hook-hosts`, a warning when Cursor is installed), and
|
|
387
389
|
the session-start line names the command while Cursor is installed.
|
|
388
390
|
|
|
389
|
-
## Codex:
|
|
391
|
+
## Codex and GitHub Copilot: the core hooks (since 0.105.0)
|
|
390
392
|
|
|
391
|
-
Codex
|
|
392
|
-
|
|
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.
|
|
393
399
|
|
|
394
400
|
```toml
|
|
401
|
+
# ~/.codex/config.toml (an excerpt)
|
|
395
402
|
[features]
|
|
396
403
|
hooks = true
|
|
397
404
|
|
|
398
405
|
[[hooks.SessionStart]]
|
|
399
406
|
[[hooks.SessionStart.hooks]]
|
|
400
407
|
type = "command"
|
|
401
|
-
command = "<bridge> on-
|
|
402
|
-
timeout =
|
|
408
|
+
command = "<bridge> on-hook --host=codex on-session-reminder on-session-start on-session-briefing"
|
|
409
|
+
timeout = 20
|
|
403
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
|
|
404
418
|
```
|
|
405
419
|
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
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
|
+
}
|
|
430
|
+
```
|
|
431
|
+
|
|
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.
|
|
411
451
|
- **Trust.** Codex runs a new hook only after you trust it: open `/hooks` in
|
|
412
|
-
Codex once.
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
`
|
|
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`.
|
|
418
482
|
|
|
419
483
|
## User-level rule files: Copilot, Cline, Continue
|
|
420
484
|
|
|
@@ -482,8 +546,9 @@ SessionStart hook names the migration once per repository.
|
|
|
482
546
|
- `doctor --migrate-repo-blocks` lists the blocks and the user-level channels
|
|
483
547
|
that carry the same content, and changes nothing.
|
|
484
548
|
- `doctor --migrate-repo-blocks --yes` sets those channels up first (Claude
|
|
485
|
-
Code's reminder and briefing hooks unless the plugin carries them, Cursor's
|
|
486
|
-
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
|
|
487
552
|
without removing anything if one fails; then it removes exactly the listed
|
|
488
553
|
blocks. Only lines between maind markers go (and the blank line the installer
|
|
489
554
|
put before them); every other byte stays, with its own line endings. A file
|
|
@@ -532,6 +597,37 @@ What `doctor` reports (`claude-plugin`), and how to clean it up:
|
|
|
532
597
|
| A `maind` server still in `~/.claude.json` | warning | `doctor --remove-duplicate-mcp [--yes]` removes exactly that entry; the rest of the file stays byte for byte. Run it with Claude Code closed: Claude Code rewrites the file while it runs. |
|
|
533
598
|
| The bridge's own hooks still in `settings.json` | note | `doctor --remove-duplicate-hooks [--yes]` removes exactly those entries, so the plugin's copies, which update with it, take over. Nothing runs twice in the meantime. The guard pack and your own hooks stay. |
|
|
534
599
|
|
|
600
|
+
## Agent activity from Claude Code sessions (since 0.104.0)
|
|
601
|
+
|
|
602
|
+
Opt-in. With `maind-mcp-bridge activity on`, a Claude Code session that is bound
|
|
603
|
+
to exactly one work object reports what its agent does to that object's activity
|
|
604
|
+
panel in MAIND — the same view a `maind run` shows:
|
|
605
|
+
|
|
606
|
+
- the todo list as the plan (step status; step text only with the text opt-in),
|
|
607
|
+
- actions as counts per category (`read`, `edit`, `run`, `test`, `search`, `git`,
|
|
608
|
+
`web`, `other`) — never paths, commands, file contents or tool output,
|
|
609
|
+
- questions to you (`AskUserQuestion`), shown as "waiting for you",
|
|
610
|
+
- the answer at the end of each turn — only when your organization stores agent
|
|
611
|
+
text (`agent_activity_text = on`); without it, the agent's words never leave
|
|
612
|
+
the machine.
|
|
613
|
+
|
|
614
|
+
**Which object.** The object of the session's branch (`branch.<name>.maindObject`,
|
|
615
|
+
set by `maind object bind`) when the session is bound to it; otherwise the
|
|
616
|
+
session's only bound object (a take binds too); otherwise nothing is reported.
|
|
617
|
+
`maind-mcp-bridge activity status` shows the switch and, per live session in the
|
|
618
|
+
current repository, the object it reports to.
|
|
619
|
+
|
|
620
|
+
**How.** The bridge reads the session's transcript
|
|
621
|
+
(`~/.claude/projects/…/<session>.jsonl`) from the moment reporting starts — no
|
|
622
|
+
history — and sends batches every few seconds over the session's own MCP
|
|
623
|
+
connection. Everything is fail-open: a slow or unreachable server never delays
|
|
624
|
+
the session. Claude Code's permission prompts are not in the transcript, so they
|
|
625
|
+
are not reported.
|
|
626
|
+
|
|
627
|
+
Switch it off with `maind-mcp-bridge activity off`, per session with
|
|
628
|
+
`MAIND_AGENT_ACTIVITY=off`. `install` asks once (default No); `--agent-activity`
|
|
629
|
+
enables it without asking.
|
|
630
|
+
|
|
535
631
|
## Where things live
|
|
536
632
|
|
|
537
633
|
| Path | Purpose |
|
|
@@ -584,6 +680,7 @@ Rarely useful outside maind's own development environments:
|
|
|
584
680
|
| `MAIND_NO_RULES_REFRESH` | unset | Set to `1` to stop every refresh of the user-level rule files — at session start and `refresh-rules` |
|
|
585
681
|
| `MAIND_CLAUDE_PLUGIN` | unset | Set by the Claude Code plugin's launcher to the plugin's version for every bridge it starts; the bridge then counts its Claude Code hooks as the plugin's (see "Claude Code plugin `maind`"). Not for setting by hand |
|
|
586
682
|
| `MAIND_DEBUG` | unset | Set to `1` for one diagnostic stderr line on the otherwise silent team-block skip (no `AGENTS.md` with a team block inside the repository) |
|
|
683
|
+
| `MAIND_AGENT_ACTIVITY` | unset | `on`/`off` overrides `activity on\|off` for one session (see "Agent activity from Claude Code sessions") |
|
|
587
684
|
| `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") |
|
|
588
685
|
| `XDG_CONFIG_HOME` | `~/.config` (Linux/BSD) | Parent of the `maind/` config dir |
|
|
589
686
|
|