@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 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 | `SessionStart` hook, its output as `additionalContext` | `config.toml` in Codex's home (`~/.codex/`, or `$CODEX_HOME`) |
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-session-briefing --host=codex` from its own `config.toml`; gets `{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": …}}` — never plain text, which Codex parses as JSON when it starts with `[`. Recognised by the `--host=codex` the installer writes, else by a Codex rollout transcript (`…/sessions/YYYY/MM/DD/rollout-….jsonl`) |
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: conventions at session start
391
+ ## Codex and GitHub Copilot: the core hooks (since 0.105.0)
390
392
 
391
- Codex has hooks (learn.chatgpt.com/docs/hooks). Since **0.100.0** `install`
392
- adds, where Codex is installed (or with `--client codex`):
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-session-briefing --host=codex"
402
- timeout = 10
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
- - **What.** The same block the Claude Code session-start hook prints —
407
- `[maind] Session briefing …`, project conventions first —, as
408
- `hookSpecificOutput.additionalContext`. `additionalContextLimit` lifts Codex's
409
- default (~2,500 tokens; above it Codex replaces the text by a file and a
410
- preview) for this one handler.
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. The report row says so.
413
- - **Append-only.** Every other key, table and hook stays; `[features] hooks =
414
- false` (or the old `codex_hooks = false`) is your "no" and is reported, never
415
- flipped. The file goes through the same parse/stringify as the MCP entry —
416
- keys and values stay, comments do not. A handler already there, in
417
- `config.toml` or `hooks.json`, counts as wired.
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 Codex's hooks, the rule files — for the clients installed here) and stops
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