@modootoday/pmcp 0.18.0 → 0.18.3

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.
Files changed (156) hide show
  1. package/.agents/plugins/marketplace.json +1 -1
  2. package/.claude-plugin/marketplace.json +1 -1
  3. package/.claude-plugin/plugin.json +2 -2
  4. package/.mcp.json +1 -1
  5. package/CONTRIBUTING.md +80 -0
  6. package/README.md +100 -206
  7. package/SECURITY.md +17 -1
  8. package/dist/{apply-4IGTXOCQ.js → apply-S2QI72W3.js} +13 -13
  9. package/dist/{available-DBSIVVJ6.js → available-GFMTJW4E.js} +3 -3
  10. package/dist/{broadcast-3RY3OZGY.js → broadcast-CBMVOV3G.js} +4 -4
  11. package/dist/{chunk-SG5TPMKH.js → chunk-26WLNWDG.js} +2 -2
  12. package/dist/{chunk-4VCC2NXE.js → chunk-2RTRY45B.js} +2 -2
  13. package/dist/{chunk-3NYG4SGU.js → chunk-3MEYKFFO.js} +3 -3
  14. package/dist/{chunk-KMXRRSKT.js → chunk-4CRRLDDS.js} +1 -1
  15. package/dist/{chunk-ZH6R642Z.js → chunk-4GSGT55G.js} +2 -2
  16. package/dist/{chunk-EJBZGIDK.js → chunk-6BN35BHI.js} +3 -3
  17. package/dist/{chunk-T3LKX23M.js → chunk-7B6IC3F7.js} +3 -3
  18. package/dist/{chunk-25GHX674.js → chunk-7DEYLLIE.js} +9 -9
  19. package/dist/{chunk-ELAGZ635.js → chunk-7PTG42QU.js} +5 -5
  20. package/dist/chunk-AF2IBMWN.js +7 -0
  21. package/dist/{chunk-IGYRMM62.js → chunk-CKTN6LKP.js} +2 -2
  22. package/dist/{chunk-PLX3BOOS.js → chunk-E5XVSMBR.js} +2 -2
  23. package/dist/{chunk-Q65R3XKX.js → chunk-EAWPJHJ7.js} +2 -2
  24. package/dist/{chunk-7BLPN3W6.js → chunk-F5LEGPGP.js} +2 -2
  25. package/dist/{chunk-BBTBJCFA.js → chunk-F5WBMUOT.js} +2 -2
  26. package/dist/{chunk-YMHUM7AV.js → chunk-F5XMGOOX.js} +7 -1
  27. package/dist/{chunk-R4L6LJJ2.js → chunk-FX3LTTMB.js} +2 -2
  28. package/dist/{chunk-5QQWS4US.js → chunk-HEBCQTOD.js} +2 -2
  29. package/dist/{chunk-NZS5CD72.js → chunk-HEWZ6INU.js} +21 -5
  30. package/dist/{chunk-MWFOUBFC.js → chunk-HFE4QDJQ.js} +2 -2
  31. package/dist/{chunk-N5AQ3PP7.js → chunk-HQWVGU3W.js} +5 -5
  32. package/dist/{chunk-UOCLRM7P.js → chunk-IIBB37JE.js} +22 -22
  33. package/dist/{chunk-MPSQXSC6.js → chunk-ISZOLR3D.js} +5 -3
  34. package/dist/{chunk-J6QLLQVL.js → chunk-JM2KR2WJ.js} +5 -5
  35. package/dist/{chunk-CJTKR6K6.js → chunk-JZK7ZO7K.js} +2 -2
  36. package/dist/{chunk-RK4PYD7L.js → chunk-LBXO4VPG.js} +2 -2
  37. package/dist/{chunk-BVCTKPT3.js → chunk-LMUBBIE2.js} +2 -2
  38. package/dist/{chunk-Z4HRRXRF.js → chunk-LTZH5E3G.js} +6 -5
  39. package/dist/{chunk-MM2Y43LC.js → chunk-M455QSCW.js} +3 -3
  40. package/dist/{chunk-7GBYECSK.js → chunk-NLHLA2N5.js} +3 -3
  41. package/dist/{chunk-HDMBVLCZ.js → chunk-NWOV2E26.js} +2 -2
  42. package/dist/{chunk-PWSJJXLQ.js → chunk-QK4G7FCU.js} +8 -8
  43. package/dist/{chunk-47O3X4VS.js → chunk-QRCAGKC6.js} +1 -1
  44. package/dist/{chunk-665TA55Z.js → chunk-TAOOPXBV.js} +2 -2
  45. package/dist/{chunk-JUXNIXN4.js → chunk-TZORR6GZ.js} +2 -2
  46. package/dist/{chunk-LAZQBMAU.js → chunk-WM2RF2MI.js} +3 -3
  47. package/dist/{chunk-65ZHM5RH.js → chunk-XJUNAVU2.js} +9 -9
  48. package/dist/{chunk-TNCZ6444.js → chunk-Y2XASHVY.js} +2 -2
  49. package/dist/{cli-VYCQJZ5X.js → cli-MI4ZCAZ3.js} +9 -9
  50. package/dist/{cli-ZTCBSDW4.js → cli-ZN7ZVDEZ.js} +3 -3
  51. package/dist/cli.js +4 -4
  52. package/dist/{completion-E7RRG3ZT.js → completion-GYN7PX3T.js} +3 -3
  53. package/dist/{diagnostics-XXH4FLUG.js → diagnostics-WACXQ33W.js} +6 -6
  54. package/dist/{doctor-ZIOESU3N.js → doctor-VSQ72A6X.js} +13 -13
  55. package/dist/{entry-ZNFCTDVE.js → entry-VFEZC2XB.js} +10 -10
  56. package/dist/{exec-mcp-X6372BLE.js → exec-mcp-TOQEJFK3.js} +8 -8
  57. package/dist/{harness-F2XFDYXF.js → harness-XCEWFGCG.js} +5 -5
  58. package/dist/harness-launch-gate.js +4 -4
  59. package/dist/harness-worker.js +6 -6
  60. package/dist/hook-body.js +7 -6
  61. package/dist/{hooks-FYE2L5RW.js → hooks-32AFBC3Z.js} +3 -3
  62. package/dist/{host-X6BR6X4O.js → host-72OLHUX7.js} +20 -10
  63. package/dist/{host-GRY3VAHH.js → host-TE5PNDHJ.js} +7 -7
  64. package/dist/{host-run-GCA6H6SR.js → host-run-MXCH26ZD.js} +5 -5
  65. package/dist/http.js +5 -5
  66. package/dist/{import-mcp-2TTBPVLY.js → import-mcp-QWGZSIZR.js} +6 -6
  67. package/dist/index.d.ts +1 -1
  68. package/dist/index.js +18 -18
  69. package/dist/{init-627KFXTG.js → init-5M3XWOTJ.js} +2 -2
  70. package/dist/{install-GG7HHZK2.js → install-MQ7QSJQ7.js} +3 -3
  71. package/dist/{invoke-LW22Z6ET.js → invoke-SFSN4XT7.js} +8 -8
  72. package/dist/{list-MCP2FXUF.js → list-FB6RNYYB.js} +3 -3
  73. package/dist/{list-NGMSQ5SH.js → list-FGDUU5DL.js} +8 -8
  74. package/dist/{logout-6CSHUWWE.js → logout-KM5N5GOC.js} +7 -7
  75. package/dist/{logs-SPB6AANY.js → logs-TBUA4UWU.js} +4 -4
  76. package/dist/mailbox/index.js +4 -4
  77. package/dist/{mailbox-GDJ7BWQN.js → mailbox-5DWLH4W2.js} +3 -3
  78. package/dist/{mailbox-7BV54Q4R.js → mailbox-BMTZOSZ7.js} +4 -4
  79. package/dist/{mainline-JQTTYJMI.js → mainline-KAD2ERLP.js} +2 -2
  80. package/dist/{mcp-V23HC3LB.js → mcp-FJ2UQ4RH.js} +2 -2
  81. package/dist/{mcp-2DKVU3SW.js → mcp-ND6ZQWJE.js} +2 -2
  82. package/dist/{pause-FFAYRBWI.js → pause-7LILUVGL.js} +4 -4
  83. package/dist/{project-FY62G55N.js → project-LZKQUV2W.js} +4 -4
  84. package/dist/{reindex-Y27QJFDB.js → reindex-ZULHSQWY.js} +5 -5
  85. package/dist/{resume-UU4HZIUP.js → resume-26VFAAMH.js} +4 -4
  86. package/dist/{run-HALGEJNJ.js → run-X4663F4M.js} +4 -4
  87. package/dist/{run-OGA3P7FC.js → run-YEVGHGTN.js} +7 -7
  88. package/dist/{serve-NBKT5BKY.js → serve-S7MF42SS.js} +12 -12
  89. package/dist/{start-login-UIQYQBMC.js → start-login-GKFGTE2A.js} +7 -7
  90. package/dist/{status-NOOHW5WA.js → status-FYG6XYQ6.js} +7 -7
  91. package/dist/{status-VHODZPXB.js → status-RO55QPKV.js} +4 -4
  92. package/dist/{status-XQANBVXW.js → status-XG5GRWVU.js} +11 -11
  93. package/dist/stdio.js +7 -7
  94. package/dist/{sweep-64JDCGK6.js → sweep-35LGQTTO.js} +4 -4
  95. package/dist/{test-MKAXFJOL.js → test-KFDO6ROC.js} +7 -7
  96. package/dist/{tui-MWKAXE4K.js → tui-2MP7DRIX.js} +5 -5
  97. package/dist/{unbroadcast-KPUEFLZD.js → unbroadcast-5QNGAJR2.js} +4 -4
  98. package/dist/{validate-5GZ5YWNA.js → validate-AVM2VHMM.js} +4 -4
  99. package/dist/{worker-RQ575EJL.js → worker-3VS6RQEL.js} +8 -8
  100. package/docs/authoring.md +82 -0
  101. package/docs/browser-and-desktop.md +46 -0
  102. package/docs/commands.md +325 -0
  103. package/docs/compare.md +35 -0
  104. package/docs/compatibility.md +56 -0
  105. package/docs/embeddings.md +1 -1
  106. package/docs/getting-started.md +105 -0
  107. package/docs/git-workflow.md +60 -0
  108. package/docs/glossary.md +31 -0
  109. package/docs/hooks.md +264 -0
  110. package/docs/install.md +72 -0
  111. package/docs/known-issues.md +17 -0
  112. package/docs/library-skills.md +132 -0
  113. package/docs/mailbox.md +16 -5
  114. package/docs/project-configuration.md +51 -386
  115. package/docs/sessions.md +64 -0
  116. package/docs/skills.md +4 -45
  117. package/docs/terminal-harness.md +26 -21
  118. package/docs/terminal-workspace.md +4 -13
  119. package/docs/upgrading.md +23 -0
  120. package/gemini-extension.json +2 -2
  121. package/mcp.json +1 -1
  122. package/package.json +8 -7
  123. package/plugin.json +2 -2
  124. package/plugins/pmcp/.claude-plugin/plugin.json +2 -2
  125. package/plugins/pmcp/.mcp.json +1 -1
  126. package/plugins/pmcp/gemini-extension.json +2 -2
  127. package/plugins/pmcp/mcp.json +1 -1
  128. package/plugins/pmcp/mod/sessions/types.ts +1 -1
  129. package/plugins/pmcp/plugin.json +2 -2
  130. package/plugins/pmcp/skills/agent-assets-migrate/SKILL.md +8 -8
  131. package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +12 -11
  132. package/plugins/pmcp/skills/marketplace-plugin-scaffold/SKILL.md +10 -8
  133. package/plugins/pmcp/skills/package-skill-catalog/SKILL.md +0 -4
  134. package/plugins/pmcp/skills/pmcp-browser/SKILL.md +27 -0
  135. package/plugins/pmcp/skills/pmcp-desktop/SKILL.md +25 -0
  136. package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +19 -11
  137. package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +20 -28
  138. package/plugins/pmcp/skills/skill-package-scaffold/SKILL.md +16 -15
  139. package/schema/catalog-v1.json +36 -7
  140. package/schema/library.json +40 -8
  141. package/schema/marketplace-manifest.json +19 -5
  142. package/schema/plugin-manifest.json +6 -2
  143. package/schema/skill-frontmatter.json +33 -7
  144. package/schema/skill-metadata-core.json +26 -5
  145. package/skills/agent-assets-migrate/SKILL.md +8 -8
  146. package/skills/headless-agents-ci-scaffold/SKILL.md +12 -11
  147. package/skills/marketplace-plugin-scaffold/SKILL.md +10 -8
  148. package/skills/package-skill-catalog/SKILL.md +0 -4
  149. package/skills/pmcp-browser/SKILL.md +27 -0
  150. package/skills/pmcp-desktop/SKILL.md +25 -0
  151. package/skills/pmcp-project-init/SKILL.md +19 -11
  152. package/skills/pmcp-sessions-and-git/SKILL.md +20 -28
  153. package/skills/skill-package-scaffold/SKILL.md +16 -15
  154. package/CHANGELOG.md +0 -60
  155. package/dist/chunk-E7OOHLQR.js +0 -7
  156. package/docs/manual-library-skills.md +0 -74
@@ -109,7 +109,7 @@ encoder are ready. Semantic
109
109
  ranking (the `index` command, or the HTTP handler's `semantic` option) needs
110
110
  `@huggingface/transformers` installed separately; it is not part of the default
111
111
  installation. The default encoder is `Xenova/multilingual-e5-small` (MIT, about
112
- 130 MB), so vectors indexed with the earlier English-only default are re-encoded.
112
+ 130 MB).
113
113
 
114
114
  The optional encoder also supports the ONNX Community EmbeddingGemma 300M and
115
115
  EmbeddingGemma 2 exports. It uses their projected sentence embeddings and task
@@ -0,0 +1,105 @@
1
+ # Getting started
2
+
3
+ [Back to the overview](../README.md)
4
+
5
+ Reading installed skills needs no login or model. The local MCP server reads files already on
6
+ your disk; CLI commands manage additional skill packages.
7
+
8
+ ## 1. Register the server
9
+
10
+ ```json
11
+ {
12
+ "mcpServers": {
13
+ "pmcp": { "command": "npx", "args": ["-y", "@modootoday/pmcp"] }
14
+ }
15
+ }
16
+ ```
17
+
18
+ Hosts differ about which file that goes in, and two of them will write it for you from [the install page](https://pmcp.build/install/). Nothing has to be installed first: `npx -y` fetches the package when needed.
19
+
20
+ ## 2. See what it can see
21
+
22
+ ```sh
23
+ npx -y @modootoday/pmcp list
24
+ ```
25
+
26
+ One row per skill: the name, as `<package>/<slug>`, and the one-line description that `skill_find` ranks. Do this before you ask an agent anything, because it answers the question the server cannot ask you back.
27
+
28
+ An empty catalog exits **1** rather than 0, and prints the roots it walked. That is usually one of two things: the working directory is not the project, or none of the installed packages ships a `SKILL.md` at all.
29
+
30
+ ## 3. Ask in a sentence
31
+
32
+ `skill_find` takes an `intent`: what you are trying to do, written as a sentence. Lexical search works best when its vocabulary matches the descriptions. It returns names only, ranked, and never a body.
33
+
34
+ ```text
35
+ > skill_find "a job ran twice because two workers took the same lock"
36
+ + redis-toolkit/locks
37
+ ranking lexical
38
+ > skill_call redis-toolkit/locks
39
+ the body, once
40
+ ```
41
+
42
+ A bare keyword ranks badly on purpose. Descriptions are written as symptoms, so a sentence shares vocabulary with one of them and a single noun matches many of them weakly and none of them strongly. When you want to browse rather than search, `skill_catalog` is the tool that filters.
43
+
44
+ ## 4. Read exactly one
45
+
46
+ `skill_call` takes the name `skill_find` returned and gives back that skill's body. It loads the full instructions into context, which is the whole point of the split: looking is cheap, and reading is deliberate.
47
+
48
+ An unknown name comes back as an error naming the tool to call instead, rather than as an empty result that reads like an empty catalog.
49
+
50
+ ## Where it looks
51
+
52
+ By default, the `node_modules` directories above the working directory. Two options change that, and both belong in the `args` array beside `pmcp`:
53
+
54
+ ```sh
55
+ npx -y @modootoday/pmcp list --root ./node_modules
56
+ npx -y @modootoday/pmcp list --scope @acme/
57
+ ```
58
+
59
+ `--scope` matches the start of the package name, so `@acme` also matches `@acmetools/thing`. Include the trailing slash when you mean the scope. Both options are repeatable.
60
+
61
+ When two roots hold the same package, the first one wins: a nested `node_modules` holds an older copy of something the outer root already resolved.
62
+
63
+ ## If you want semantic ranking
64
+
65
+ ```sh
66
+ npm install --save-dev @modootoday/pmcp @huggingface/transformers
67
+ npx --no-install @modootoday/pmcp models
68
+ ```
69
+
70
+ Install both packages locally so the server can resolve the optional encoder. Configure the model in a project `pmcp.toml`:
71
+
72
+ ```toml
73
+ [embedding]
74
+ enabled = true
75
+ model = "embeddinggemma-2"
76
+ dtype = "q4"
77
+ dimensions = 256
78
+ ```
79
+
80
+ ```sh
81
+ npx --no-install @modootoday/pmcp index --config ./pmcp.toml
82
+ npx --no-install @modootoday/pmcp serve --config ./pmcp.toml
83
+ ```
84
+
85
+ The default encoder remains `e5-small`. Gemma presets also support `128`, `512`, and `768` dimensions. `pmcp models --json` lists encoder presets without loading model assets. Custom compatible ONNX encoders can use a model ID and an `[embedding.encoder]` configuration.
86
+
87
+ Indexing may download weights when explicitly requested. Serving uses the matching complete local index offline; missing assets or a stale index keep ranking lexical. A model change requires reindexing and a server restart. Use `--local-only` to forbid downloads and `--dry-run` to preview indexing without loading a model.
88
+
89
+ In the host's MCP configuration, run the locally installed `node_modules/@modootoday/pmcp/dist/cli.js` with Node and an absolute `--config` path. This avoids resolving the server from a separate npx cache without its optional peer. With semantic search enabled, intents can be written in Korean or another language the selected encoder supports.
90
+
91
+ The model runtime and weights add installation and loading costs. Skip this optional step when local lexical search meets your needs.
92
+
93
+ ## Keep your native tools together
94
+
95
+ Use [one project configuration](project-configuration.md) for Claude Code, Codex, Gemini CLI, Grok Build, Antigravity and opencode. Import existing MCP entries before projecting settings; use `pmcp project --check` and `pmcp doctor` to inspect the result.
96
+
97
+ On Linux or macOS, run `pmcp` to [open a terminal workspace](terminal-workspace.md) around a native main and its workers; the [harness guide](terminal-harness.md) covers explicit groups. Login, folder trust and permission decisions stay in each runtime. An [optional local mailbox](mailbox.md) exchanges peer messages without granting execution authority.
98
+
99
+ ## What to do next
100
+
101
+ - [Ship a skill of your own](https://pmcp.build/authoring/) — the paths, the frontmatter, and how to write a description that gets found
102
+ - [The command reference](commands.md) — flags and exit codes
103
+ - [Run several agents in one repository](sessions.md) — sessions, messages and delivery
104
+ - [Compatibility](compatibility.md) — what runs on your platform and runtime
105
+ - [The licence](https://pmcp.build/licence/) — what Elastic License 2.0 permits
@@ -0,0 +1,60 @@
1
+ # Git workflow
2
+
3
+ [Back to the overview](../README.md)
4
+
5
+ Linked worktrees, one delivery path to the mainline and main checkout sync, configured by
6
+ `[git]`. [Run several agents](sessions.md) shows how it fits with sessions; the other tables
7
+ are in the [pmcp.toml reference](project-configuration.md).
8
+
9
+ | `[git]` key | Type | Default | Meaning |
10
+ | ----------- | --------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
11
+ | `enabled` | `"auto"`, true, false | `"auto"` | `auto` turns the git features on when the project is a git checkout; `false` turns all of them off. |
12
+ | `remote` | string | `origin` if present, else the first remote | |
13
+ | `mainline` | string or table | the remote's HEAD branch, else `main` | A string names the branch; a table (`[git.mainline]` with `branch`) also holds gate, deliver and sync. |
14
+
15
+ `[git.shared_checkout]` warns a session working in the main checkout of a
16
+ repository that also has linked worktrees, tracks the files it edits there,
17
+ and names leftovers not yet delivered, because they block syncing the shared main for
18
+ everyone. Keys: `enabled` (`"auto"` default, following `[git] enabled`, or a
19
+ boolean), `warn_on_session`, `track_edits`, `warn_claimants` (booleans, default
20
+ `true`). It is on in any git checkout without a table, once something else
21
+ enables the hook bundle.
22
+
23
+ `[git.worktrees]` configures the linked worktrees `pmcp git worktree` creates:
24
+
25
+ | Key | Type | Default |
26
+ | ---------------- | --------- | -------------------------- |
27
+ | `root` | string | `".claude/worktrees"` |
28
+ | `branch_prefix` | string | `"worktree-"` |
29
+ | `alias_pattern` | regex | `"^[a-z][a-z0-9-]{1,30}$"` |
30
+ | `bootstrap` | argv list | none |
31
+ | `link_from_main` | list | `[]` |
32
+
33
+ `[git.worktrees.sync]` (opt-in) keeps each linked worktree on the mainline when moving it
34
+ loses nothing: `on_session_start` (`"fetch_and_move"` default, `"move"`,
35
+ `"off"`), `between_prompts` (`"move_if_light"` default, `"off"`: move only when
36
+ no install is needed), `install_after_move` (`"off"` default, `"background"`,
37
+ `"foreground"`) and `notice_paths` (paths whose change is announced to the
38
+ session). Installs never block a session.
39
+
40
+ `[git.mainline.gate]`: `command` (argv; no gate when missing), `tree` (the
41
+ gate's worktree, default `<state dir>/gate/tree`; a relative path is relative to
42
+ the main checkout, like `state_dir`), `lock_wait_seconds`
43
+ (default `5400`).
44
+
45
+ `[git.mainline.deliver]` enables `pmcp git deliver`, which replays commits onto
46
+ the fetched mainline, runs the gate, and pushes one delivery at a time:
47
+ `attempts` (default `3`), `refuse_direct_push` (default `true`: a hook refuses
48
+ `git push` from any checkout of this repository, so the mainline moves only
49
+ through delivery), `during_pause` (`"refuse"` default or `"allow"`),
50
+ `lease_wait_seconds` (default `3600`) and `notify` (argv run after a
51
+ delivery).
52
+
53
+ `[git.mainline.sync]` enables `pmcp git sync`, which moves the main checkout to
54
+ the mainline: `install` (argv), `install_when_changed` (paths; when no
55
+ `[sessions.leases]` are declared, these become an implicit `lockfile` lease),
56
+ `keep_identical_files` and `refuse_with_unlanded` (booleans, default `true`).
57
+
58
+ `[git.submodules]`: `follow = "clean_pins"` (the default when the table is
59
+ present) moves submodules to the pinned commit when they are clean; `"off"`
60
+ leaves them. Without the table submodules are not followed.
@@ -0,0 +1,31 @@
1
+ # Glossary
2
+
3
+ [Back to the overview](../README.md)
4
+
5
+ The words pmcp's documentation and messages use, each with the page that owns it.
6
+
7
+ | Term | Meaning |
8
+ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
+ | skill | A `SKILL.md` an agent loads when its task matches: a description that decides when, and a body with the instructions. [Skills reference](skills.md) |
10
+ | catalog | The skills pmcp finds in installed packages, workspace packages and marketplaces; `skill_find` searches it. [Getting started](getting-started.md) |
11
+ | marketplace | A collection of plugins that native runtimes install; pmcp ships a free public one. [Skills reference](skills.md) |
12
+ | projection | The native files `pmcp project` writes for each tool from `pmcp.toml` and `.agents/`; `pmcp.lock` records what it owns. [pmcp.toml reference](project-configuration.md) |
13
+ | hook bundle | The guards, checks and session bookkeeping `[hooks]` compiles and every targeted runtime runs on its tool calls. [Hooks](hooks.md) |
14
+ | session | One running agent conversation in the repository, as the hooks record it. [Run several agents](sessions.md) |
15
+ | shared checkout | The repository's main checkout when linked worktrees exist; an edit left there blocks syncing it for every session. |
16
+ | linked worktree | A separate checkout `pmcp git worktree create` makes for one agent. Messages address it as `worktree:<path>`; `desk:<path>` is an older spelling that still works. [Git workflow](git-workflow.md) |
17
+ | mainline | The branch deliveries go to: `[git] mainline`, else the remote's HEAD branch, else `main`. |
18
+ | delivery | `pmcp git deliver`: replay commits onto the mainline, run the gate, push. "Being delivered" in a message means one is in progress. |
19
+ | gate | The test command a delivery must pass, `[git.mainline.gate]`. |
20
+ | lease | A hold on a file two sessions must not change at once, such as a lockfile; the listed commands wait while a delivery holds it. |
21
+ | pause | `pmcp sessions pause`: every other session's edits and mutating commands are refused until `resume`. |
22
+ | broadcast | Text every running session receives once, as context. |
23
+ | sessions mailbox | Addressed messages between the sessions of one repository, `pmcp sessions send`. [Run several agents](sessions.md) |
24
+ | local mailbox | Messages between actors that hold their own credentials, `pmcp mailbox`, across projects and hosts. [Local mailbox](mailbox.md) |
25
+ | `operator` | A name, not a role: the default sender of `pmcp sessions pause`, `broadcast` and `send` (`--by`), and a mailbox actor you may register. The docs call the person "you". |
26
+ | runtime id | How each table names a native runtime; the ids differ between tables. [Compatibility](compatibility.md#native-runtimes) |
27
+ | main and worker | In a terminal workspace or harness group, the session you mainly talk to and the ones it delegates to. [Terminal workspace](terminal-workspace.md) |
28
+ | harness group | The sessions one pmcp-pty daemon hosts for `pmcp tui` or `pmcp harness`, with a budget and a generation that changes when the group is replaced. [Native terminal control](terminal-harness.md) |
29
+ | control | Holding the lease on a hosted session so only you type into it; program input waits until you release it. |
30
+ | host (`[host]`) | The long-running sessions `pmcp harness host` runs from `pmcp.toml`, once you approve the projected policy. [Sessions pmcp-pty hosts](project-configuration.md#sessions-pmcp-pty-hosts) |
31
+ | platform package | `@modootoday/pmcp-<os>-<cpu>`, the npm package that carries the native binaries for one platform. [Compatibility](compatibility.md) |
package/docs/hooks.md ADDED
@@ -0,0 +1,264 @@
1
+ # Hooks
2
+
3
+ [Back to the overview](../README.md)
4
+
5
+ `[hooks]` in `pmcp.toml` compiles guards, checks and session bookkeeping into one hook bundle that
6
+ every targeted runtime runs on its tool calls. The other tables are in the
7
+ [pmcp.toml reference](project-configuration.md).
8
+
9
+ `pmcp project` compiles `[hooks]`, `[sessions]`, `[git]` and `[logging]` into
10
+ `.agents/pmcp-hooks/policy.json`, copies the hook beside it as `hook.mjs` (a
11
+ small loader) and `hook-body.mjs`, and registers `hook.mjs` in
12
+ `.claude/settings.json` and `.codex/hooks.json` for the events the declared
13
+ features use. Gemini, Antigravity, Grok and OpenCode are opt-in: name them in
14
+ `[hooks] targets` and pmcp registers the same hook in their files (see
15
+ [Runtime support](#runtime-support)). `pmcp.lock` pins the hash of `policy.json`; the hook refuses to
16
+ act on a policy that does not match it, so every policy change is a reviewed
17
+ projection. Codex shows changed entries under `/hooks` as needing review;
18
+ untrusted hooks do not run. Each Codex, Claude and Grok entry carries a
19
+ `statusMessage` such as `pmcp session start` or `pmcp before tool`: Codex
20
+ lists hooks under that name, and Claude and Grok show it while the hook runs.
21
+ Gemini entries keep their `name` (`pmcp-<event>`), which is part of the
22
+ identity Gemini trusts.
23
+
24
+ The hook keeps two per-user caches under `$XDG_CACHE_HOME/pmcp` (default
25
+ `~/.cache/pmcp`), never in the project: Node's compile cache for the body
26
+ (`hook-compile/`) and the last integrity verdict per `policy.json`
27
+ (`hook-verified.json`). A verdict is reused only while neither `policy.json`
28
+ nor `pmcp.lock` has been written since. Either cache can be missing or
29
+ unwritable without changing a decision; `PMCP_HOOK_COMPILE_CACHE=off` turns the
30
+ compile cache off.
31
+
32
+ Every feature is opt-in: a table that is missing turns its feature off, and a
33
+ declared table, even an empty one, turns it on. The exceptions are documented
34
+ where they apply: `[git]` features detect git (`enabled = "auto"`),
35
+ `[git.shared_checkout]` is on in any git checkout once the bundle exists, and
36
+ logging falls back to its defaults rather than to no logging. The bundle is
37
+ projected only when `[hooks]` declares guards or checks, a `[sessions.*]`
38
+ feature table is declared, `[git.shared_checkout]` or `[git.worktrees.sync]` is
39
+ declared, or `[git.mainline.deliver]` keeps `refuse_direct_push`.
40
+
41
+ ## `[hooks]`
42
+
43
+ | Key | Type | Default | Meaning |
44
+ | -------------------- | ------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
45
+ | `targets` | list | `[targets] tools` limited to `claude`, `codex` | Runtimes that receive the hook bundle: `claude`, `codex`, `gemini`, `antigravity`, `grok`, `opencode`. The last four are used only when listed here. |
46
+ | `ask_fallback` | string | `"deny"` | What an ask becomes on a runtime without ask (Codex, Gemini, Antigravity, Grok, OpenCode): `deny`, `warn`, or `refuse` to make projection fail while any guard may ask. |
47
+ | `error_log` | bool or path | `true` | `true` writes JSONL logs under the state directory's `logs/`; a project-relative path writes one file there instead; `false` turns hook logging off. |
48
+ | `emergency_off_file` | path | none | While this file exists every guard passes. `~`, `$HOME/` and absolute paths are allowed; other paths are relative to the project. |
49
+
50
+ ## `[hooks.guards.<group>.<name>]`
51
+
52
+ Each built-in guard is one table. `mode` is the only key the option-less
53
+ guards take; an unknown option is an error. Modes: `deny` and `ask` replace
54
+ the guard's verdict with that mode, `warn` turns the reason into context the
55
+ agent reads, `off` drops the guard, and `graded` keeps the guard's own split
56
+ between ask and deny.
57
+
58
+ | Table | Default mode | Modes | Refuses |
59
+ | ------------------------------------------ | ------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
60
+ | `[hooks.guards.shell.in_place_edit]` | deny | deny, ask, warn, off | `sed -i`, `perl -i`, `awk -i inplace`: edits without a diff. |
61
+ | `[hooks.guards.shell.heredoc]` | deny | deny, ask, warn, off | Heredocs and here-strings, whose body the shell expands silently. |
62
+ | `[hooks.guards.shell.stdin_interpreter]` | ask | deny, ask, warn, off | An interpreter reading its program from stdin (`python3 -`, `cat x.py \| python3`). |
63
+ | `[hooks.guards.shell.compose_teardown]` | deny | deny, ask, warn, off | `docker compose down`, and `stop`, `rm` or `kill` with no service named: they hit every service. |
64
+ | `[hooks.guards.shell.secret_exfiltration]` | graded | deny, ask, warn, off, graded | Reading a credential asks; sending one over the network, or changing a live one, denies. |
65
+ | `[hooks.guards.shell.host_approval]` | deny | deny, ask, warn, off | `host approve`, and commands or edits touching the host approvals directory. On by itself when `[host]` is declared. |
66
+ | `[hooks.guards.git.push_without_verify]` | deny | deny, ask, warn, off | `git push --no-verify`. |
67
+ | `[hooks.guards.git.forced_branch_move]` | deny | deny, ask, warn, off | Forcing a branch that is checked out in another working tree. |
68
+ | `[hooks.guards.git.gate_bypass_env]` | deny | deny, ask, warn, off | Setting a named gate-bypass variable where it takes effect, and optionally `--no-verify` on any git command. |
69
+ | `[hooks.guards.git.stage_all]` | deny | deny, ask, warn, off | `git add -A`, `git add .`, `git commit -a` and similar; stage explicit paths. |
70
+
71
+ Options:
72
+
73
+ - `[hooks.guards.shell.secret_exfiltration]`: `extra_secret_paths` (list of
74
+ case-insensitive regular expressions, default `[]`), and
75
+ `[[hooks.guards.shell.secret_exfiltration.value_commands]]` entries for a
76
+ CLI that prints or publishes secret values: `binary` (required), `read`
77
+ (verbs that print a value, so reading asks) and `publish` (verbs that change
78
+ a live value, so they deny). Built in are `.env` files, `.dev.vars`, private
79
+ keys, `.npmrc`, `.netrc`, `auth.json` and service-account files; a file whose
80
+ name merely contains "secret" or "credential" is not one, so list such files
81
+ in `extra_secret_paths`. Only a file a command reads counts: a search
82
+ pattern, a sed or awk script, a jq filter or `-e` code that mentions `.env`
83
+ does not.
84
+ - `[hooks.guards.git.gate_bypass_env]`: `names` (variable names, default `[]`)
85
+ and `no_verify` (boolean, default `true`).
86
+
87
+ A mention is not a match: commands are parsed into steps, so
88
+ `git commit -m "never git push --no-verify"` and `echo 'cat <<EOF'` pass. A
89
+ command the parser cannot read is judged by a conservative pattern instead.
90
+
91
+ ## `[[hooks.guards.custom]]`
92
+
93
+ A project script under `.agents/guards/` that decides like a built-in guard.
94
+
95
+ | Key | Type | Default | Meaning |
96
+ | ------------ | --------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
97
+ | `name` | string | required | `^[a-z0-9][a-z0-9-]*$`, unique across custom, shell and edit entries. |
98
+ | `command` | argv list | required | The first or second element is the script, which must exist inside `.agents/guards/`; its sha256 is pinned in `policy.json`. |
99
+ | `targets` | list | required | Any `[hooks] targets` runtime. A runtime in `[hooks] targets` runs it in the hook bundle; otherwise Codex, Gemini and Antigravity use the shell adapter, and Claude, Grok and OpenCode are an error. |
100
+ | `timeout_ms` | integer | `15000` | 100 to 60000. |
101
+ | `on` | string | `"before_shell"` | `before_shell` or `after_edit`. |
102
+
103
+ The script receives the JSON contract described under
104
+ [Deprecated shell guards](#deprecated-shell-guards). Custom guards have no `mode`.
105
+
106
+ ## `[hooks.checks.after_edit]` and `[hooks.checks.on_stop]`
107
+
108
+ Checks report through context and never block; a check that cannot run is
109
+ logged and stays quiet.
110
+
111
+ | Table | Key | Type | Default | Meaning |
112
+ | --------------------------- | ------------------ | --------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
113
+ | `[hooks.checks.after_edit]` | `validator_glob` | glob | required | Validator scripts inside the project; after an edit, only the validators whose directory owns an edited path run. |
114
+ | | `command` | argv list | required | Must contain `{validator}`, replaced by the validator's path. Runs directly, never through a shell. |
115
+ | | `debounce_seconds` | number | `60` | One run per validator per window. |
116
+ | | `report` | string | `"context"` | The only value. |
117
+ | `[hooks.checks.on_stop]` | `project_check` | boolean | `true` | After a turn that edited files, run `pmcp project --check` and report drift. |
118
+ | | `report` | string | `"context"` | The only value. |
119
+
120
+ The stop check runs the checkout's own pmcp (`node_modules`), else the CLI that
121
+ last projected this checkout on this machine (recorded in the state directory
122
+ as `projector.json`), and only at the version `pmcp.lock` records. A pmcp on
123
+ `PATH` is never used. When none matches, the session hears
124
+ `projecting pmcp not available` once instead of a drift report.
125
+
126
+ ## Runtime support
127
+
128
+ From the measured capability files in `docs/hooks/capabilities/` (Claude Code
129
+ 2.1.303, Codex 0.163.0, including live sessions). `pmcp doctor` prints the same
130
+ table for your project, with Codex trust.
131
+
132
+ | Feature | Claude Code | Codex |
133
+ | ---------------------------------------------------------------------------------------------- | -------------------------- | ---------------------------------------- |
134
+ | sessions registry, pause, leases, broadcast | measured | measured |
135
+ | `[sessions.roles.<name>]` | works; not live-measured | unsupported: Codex sends no `agent_type` |
136
+ | `[git.shared_checkout]`, `[git.worktrees.sync]`, `[git.mainline.deliver]` | measured | measured |
137
+ | heredoc, compose_teardown, push_without_verify, forced_branch_move, gate_bypass_env, stage_all | measured | measured |
138
+ | in_place_edit, stdin_interpreter, secret_exfiltration (ask) | ask not measured | ask lowered by `ask_fallback` |
139
+ | host_approval | works; not live-measured | works; not live-measured |
140
+ | `[hooks.checks.after_edit]` | measured | measured |
141
+ | `[hooks.checks.on_stop]` | measured, in the same turn | at the next prompt |
142
+ | `[[hooks.guards.custom]]` | not measured | not measured |
143
+ | `[ui.claude]` | Claude only | not applicable |
144
+
145
+ Codex limits that shape the projection:
146
+
147
+ - Codex has no ask. An ask becomes `ask_fallback` (`deny` by default).
148
+ - Codex sends no `agent_type`, so roles cannot apply there.
149
+ - Codex rejects context on Stop, so Stop notices are delivered at the next
150
+ prompt.
151
+ - Codex clamps a SessionEnd hook to 3 s; pmcp projects at most 3 s for it.
152
+ - Codex has no Notification event.
153
+ - Codex's own command filter rejects a fully quoted executable before any hook
154
+ runs; use the ordinary unquoted form.
155
+
156
+ Gemini CLI 0.63.0, Antigravity (`agy`) 1.4.2, Grok 1.0.62 and OpenCode 1.18.33
157
+ are opt-in `[hooks] targets`. The pmcp bundle ran live on each in the same
158
+ thirteen scenarios as Claude Code and Codex, judged from each runtime's own
159
+ transcript; the `live` block of each capability file names the runs. A context
160
+ a runtime does not deliver at an event is held and delivered at the next event
161
+ that does, and that was measured live too. On OpenCode, prompt context goes
162
+ into the system prompt, which OpenCode does not store, so its delivery is shown
163
+ by a probe rather than by the prompt scenario. agy runs prompt policies on
164
+ every turn: its counter resets per turn.
165
+
166
+ | Feature | Gemini | Antigravity | Grok | OpenCode |
167
+ | ------------------------------------------- | ---------------------------- | ----------------------------- | ---------------------------- | ---------------------------- |
168
+ | refusing a tool call (guards, pause, git) | measured deny | measured deny | measured deny | measured (thrown error) |
169
+ | context (broadcast, warnings) | start, prompt, after tool | first model call, Stop | tool events, Stop | start, prompt, after tool |
170
+ | `[sessions.registry]` | every event | tool events, first call, Stop | every event | every event |
171
+ | `[sessions.roles.<name>]` | unsupported: no `agent_type` | unsupported: no `agent_type` | unsupported: no `agent_type` | unsupported: no `agent_type` |
172
+ | ask (in_place_edit, stdin_interpreter, ...) | lowered by `ask_fallback` | lowered by `ask_fallback` | lowered by `ask_fallback` | lowered by `ask_fallback` |
173
+ | `[hooks.checks.on_stop]` | at the next delivering event | Stop continues once | in the same turn | at the next prompt |
174
+ | `[[hooks.guards.custom]]` | not measured | not measured | not measured | not measured |
175
+
176
+ Where each runtime's projection goes, and what it needs:
177
+
178
+ - Gemini: `.gemini/settings.json` `hooks`, timeouts in milliseconds. Gemini
179
+ ignores project settings in a folder the user has not trusted, and records
180
+ each new hook in `~/.gemini/trusted_hooks.json`; `pmcp doctor` reads both
181
+ and reports them, and never writes them. Trusting the folder is the user's
182
+ step in an interactive `gemini` session.
183
+ - Antigravity: one named set `pmcp` in `.agents/hooks.json`, beside the shell
184
+ adapter's `pmcp-shell`. agy denies a tool call whose hook names no decision,
185
+ so pmcp always writes one. agy has no session or prompt event: the first
186
+ model call of a conversation is the session start, the first of a later
187
+ turn the prompt. Whether that counter resets for a later prompt in an
188
+ interactive session is not measured. No trust step.
189
+ - Grok: grok also runs `.claude/settings.json` hooks, so with `claude` in
190
+ `[hooks] targets` pmcp writes only the Claude file and the hook recognises a
191
+ grok call by its payload; with Grok alone it writes `.grok/hooks/pmcp.json`.
192
+ Never both, or every check would run twice. Project hooks run only after
193
+ the user runs `/hooks-trust`; `pmcp doctor` reads
194
+ `~/.grok/trusted_folders.toml` without writing it.
195
+ - OpenCode: there are no shell hooks, so pmcp writes `.opencode/plugins/pmcp.js`,
196
+ a small plugin pinned in `pmcp.lock` that passes each call to the hook. A
197
+ refusal is thrown as an error; Stop (`session.idle`) only updates the
198
+ registry. No trust step.
199
+
200
+ `auth = "pmcp"` MCP servers project through `pmcp project exec-mcp` for every
201
+ runtime above.
202
+
203
+ ## Deprecated shell guards
204
+
205
+ Deprecated: `[[hooks.shell]]` and `[[hooks.edit]]` still work, and `pmcp project`
206
+ warns. Declare `[[hooks.guards.custom]]` instead, with `on = "before_shell"` or
207
+ `on = "after_edit"`, and list its runtimes in `[hooks] targets`: every runtime
208
+ now has a hook bundle adapter, and this separate shell adapter will be removed
209
+ in a later major release.
210
+
211
+ Declare a project-owned guard explicitly to project it into Codex, Gemini or
212
+ Antigravity's native hooks. Without a declaration, pmcp generates no hooks.
213
+
214
+ ```toml
215
+ [[hooks.shell]]
216
+ name = "shell-command-policy"
217
+ command = ["node", ".agents/guards/shell-command-policy.mjs"]
218
+ targets = ["codex", "gemini", "antigravity"]
219
+ timeout_ms = 15000
220
+ ```
221
+
222
+ The guard script must exist under .agents/guards/ and cannot resolve outside
223
+ that directory. It receives one JSON object on stdin containing runtime,
224
+ event=before_shell, command and cwd. It returns a JSON object with
225
+ decision=allow or decision=deny and an optional reason. Malformed responses,
226
+ nonzero exits and timeouts deny the shell call. The guard receives PATH and
227
+ LANG rather than the native CLI's credential environment. Non-shell tools are
228
+ outside this contract.
229
+
230
+ Run pmcp project to write lock-owned adapter and policy artifacts under
231
+ .agents/pmcp-hooks/, plus the native entries in .codex/hooks.json,
232
+ .gemini/settings.json and .agents/hooks.json. Peer entries are retained.
233
+ Edited owned hook entries refuse projection for review. Removing a declaration
234
+ removes its generated entries and artifacts while preserving peer settings.
235
+ Writes retain private backups; pmcp project --check only reports drift.
236
+
237
+ Guard, policy and adapter fingerprints bind the generated command. Changing
238
+ guard code requires reprojection and native Codex hook review. Generated files
239
+ contain no trust bypass. Grok can load Claude project hooks, so this first scope
240
+ does not generate a second Grok guard. Hooks do not force pmcp catalog use,
241
+ inject reminders or replace the runtime's execution sandbox.
242
+
243
+ ## Deprecated edit guards
244
+
245
+ Codex edit guards run after apply_patch through native PostToolUse hooks:
246
+
247
+ ```toml
248
+ [[hooks.edit]]
249
+ name = "edit-policy"
250
+ command = ["node", ".agents/guards/edit-policy.mjs"]
251
+ targets = ["codex"]
252
+ timeout_ms = 15000
253
+ ```
254
+
255
+ The guard receives runtime=codex, event=after_edit, the patch in command and cwd.
256
+ It returns the same allow/deny response as a shell guard. A denial becomes
257
+ native blocking feedback with the reason; the completed file edit remains on disk
258
+ for correction. Other tools do not invoke this guard. Edit targets currently
259
+ support Codex only, and names must be unique across shell and edit declarations.
260
+
261
+ Run pmcp project after declaring or changing the guard, then review and trust
262
+ the generated native definition in /hooks. Peer entries and shell guards are
263
+ preserved. Fingerprints and failure handling follow the shell-guard contract.
264
+ See the [native hooks documentation](https://learn.chatgpt.com/docs/hooks).
@@ -0,0 +1,72 @@
1
+ # Installation
2
+
3
+ [Back to the overview](../README.md)
4
+
5
+ Two of these write the configuration for you. The rest are a line of JSON or a command, depending on where your agent keeps its servers.
6
+
7
+ ## One click
8
+
9
+ [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=pmcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtb2Rvb3RvZGF5L3BtY3AiXX0=) [Add to VS Code](vscode://mcp/install?name=pmcp&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40modootoday%2Fpmcp%22%5D%7D)
10
+
11
+ Those two links carry the whole server definition in their payload, so the editor opens with the form already filled in.
12
+
13
+ ## As a dev dependency
14
+
15
+ ```sh
16
+ npm install --save-dev @modootoday/pmcp
17
+ ```
18
+
19
+ Installing it is optional. Every configuration below runs it through `npx -y @modootoday/pmcp`, which works with nothing installed; adding it to the project pins the version your team gets.
20
+
21
+ ## Native marketplace
22
+
23
+ The `pmcp` plugin adds the MCP bridge to Claude Code, Codex and Grok, and Gemini installs it
24
+ with `gemini extensions install https://github.com/modootoday/pmcp`. Library instructions
25
+ install the same way, one plugin per library major: see [Library skills](library-skills.md).
26
+
27
+ ## A host that spawns servers over stdio
28
+
29
+ ```json
30
+ {
31
+ "mcpServers": {
32
+ "pmcp": { "command": "npx", "args": ["-y", "@modootoday/pmcp"] }
33
+ }
34
+ }
35
+ ```
36
+
37
+ That is the shape most hosts read. The file it goes in differs by host, and the two commands below write it for you.
38
+
39
+ ## Claude Code
40
+
41
+ ```sh
42
+ claude mcp add pmcp -- npx -y @modootoday/pmcp
43
+ ```
44
+
45
+ ## VS Code, from a script
46
+
47
+ ```sh
48
+ code --add-mcp '{"name":"pmcp","command":"npx","args":["-y","@modootoday/pmcp"]}'
49
+ ```
50
+
51
+ The same thing the badge does, for setting up a workstation rather than clicking through one.
52
+
53
+ ## Options the server takes
54
+
55
+ - `--root <dir>`: a `node_modules` directory to walk, instead of discovering upwards from
56
+ the working directory; repeatable.
57
+ - `--scope <prefix>`: only packages whose names start with this; repeatable, and takes a
58
+ comma-separated list.
59
+
60
+ Both go in the `args` array beside `pmcp`. A host that passes them with no command still gets the server, because a bare spawn is what the protocol expects.
61
+
62
+ ## What arrives
63
+
64
+ - Node 22 or later, or Bun 1.3 or later.
65
+ - Runtime dependencies: `@modelcontextprotocol/server`, `zod`, `semver`, `smol-toml` and `yaml`. Their MIT, ISC and BSD-3-Clause notices are listed in the package's `NOTICE`.
66
+ - No postinstall hook, and nothing downloaded at install time. Semantic ranking needs an optional peer you install yourself.
67
+
68
+ ## Optional native workspace
69
+
70
+ Share MCP settings through the [pmcp.toml reference](project-configuration.md). The [native harness](terminal-harness.md) and [terminal workspace](terminal-workspace.md) run on Linux (glibc 2.35 or later, with a working user systemd manager) or macOS, with Node.js 22; npm installs pmcp-pty and pmcp-tui with pmcp. Run `pmcp tui doctor` to check the host. Provider credentials stay with the native tools.
71
+
72
+ **Check it before you trust it.** `npx -y @modootoday/pmcp list` prints what the server would see from this directory. The CLI includes the free catalog; `--no-builtin` restricts discovery to your own roots. [Getting started](getting-started.md) is the five-minute version.
@@ -0,0 +1,17 @@
1
+ # Known issues
2
+
3
+ [Back to the overview](../README.md)
4
+
5
+ What the current release does not do yet, and what to do instead. An entry leaves this page in
6
+ the commit that fixes it, so the fix shows in that release's notes.
7
+
8
+ - macOS binaries are unsigned. They run when installed through npm, which sets no quarantine
9
+ flag. (`scripts/platform-packages.mjs`)
10
+ - Windows is not supported: the harness, `pmcp tui` and pmcp-pty stop with
11
+ `platform_unsupported`. (`src/harness/platform.ts`)
12
+ - `pmcp harness host up` and `host unit` need Linux with a user systemd manager; on macOS
13
+ they refuse with `platform_unsupported`. Use `pmcp tui` or a harness group there.
14
+ (`src/harness/platform.ts`)
15
+ - pmcp-browser and pmcp-desktop ship for Linux only. (`scripts/platform-packages.mjs`)
16
+ - `[sessions.roles]` applies to Claude Code only; Codex and the other runtimes send no agent
17
+ type. ([Hooks](hooks.md#runtime-support))