@modootoday/pmcp 0.17.4 → 0.18.2

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 (272) 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/CHANGELOG.md +152 -0
  6. package/CONTRIBUTING.md +71 -0
  7. package/README.md +98 -201
  8. package/SECURITY.md +17 -1
  9. package/dist/apply-JUTGS5WZ.js +242 -0
  10. package/dist/{attachment-tU5FZrgZ.d.ts → attachment-D84OGI6n.d.ts} +1 -1
  11. package/dist/available-DBSIVVJ6.js +73 -0
  12. package/dist/broadcast-CBMVOV3G.js +18 -0
  13. package/dist/chunk-26WLNWDG.js +93 -0
  14. package/dist/chunk-2FIV63WC.js +252 -0
  15. package/dist/chunk-2P4Z2NUX.js +28 -0
  16. package/dist/chunk-34DECPVC.js +22 -0
  17. package/dist/chunk-3FCFAQDG.js +42 -0
  18. package/dist/chunk-3IDXEV5E.js +1934 -0
  19. package/dist/chunk-3PW4FI7U.js +32 -0
  20. package/dist/chunk-3Y3HDMHA.js +108 -0
  21. package/dist/chunk-47O3X4VS.js +113 -0
  22. package/dist/chunk-4NDEP7HU.js +26 -0
  23. package/dist/chunk-5OMOPUE6.js +39 -0
  24. package/dist/chunk-5QQWS4US.js +53 -0
  25. package/dist/chunk-5ZABTVSW.js +48 -0
  26. package/dist/chunk-65KAQSJP.js +7 -0
  27. package/dist/chunk-6STKGOCW.js +27 -0
  28. package/dist/chunk-6WXMJOMI.js +9 -0
  29. package/dist/chunk-73AKO4UL.js +24 -0
  30. package/dist/chunk-7DLZC73N.js +29 -0
  31. package/dist/chunk-7GBYECSK.js +72 -0
  32. package/dist/chunk-7HFIGCSL.js +419 -0
  33. package/dist/chunk-7TD53M7L.js +13 -0
  34. package/dist/chunk-7UCZAN4J.js +778 -0
  35. package/dist/chunk-A4PKLESO.js +112 -0
  36. package/dist/chunk-A7VF7A35.js +1025 -0
  37. package/dist/chunk-ABTJQ4QV.js +74 -0
  38. package/dist/chunk-AJ4VXM2U.js +349 -0
  39. package/dist/chunk-BBTBJCFA.js +380 -0
  40. package/dist/chunk-BU65MNVU.js +13 -0
  41. package/dist/chunk-C4NHQGHL.js +142 -0
  42. package/dist/chunk-CJTKR6K6.js +1213 -0
  43. package/dist/chunk-D77IRGHO.js +1246 -0
  44. package/dist/chunk-DCU2EXQV.js +78 -0
  45. package/dist/chunk-DMZHQZ7P.js +104 -0
  46. package/dist/chunk-DZ2MRTYT.js +135 -0
  47. package/dist/chunk-E2YOZ2FF.js +207 -0
  48. package/dist/chunk-E3DQB5LS.js +48 -0
  49. package/dist/chunk-EATCUWGG.js +66 -0
  50. package/dist/chunk-EAWPJHJ7.js +155 -0
  51. package/dist/chunk-EIDIVIAD.js +33 -0
  52. package/dist/chunk-F5QYZK7E.js +396 -0
  53. package/dist/chunk-F5XMGOOX.js +28 -0
  54. package/dist/chunk-FENOGX3U.js +31 -0
  55. package/dist/chunk-GZHHEHKY.js +44 -0
  56. package/dist/chunk-HDMBVLCZ.js +53 -0
  57. package/dist/chunk-HQOB7OQS.js +81 -0
  58. package/dist/chunk-I2ZP2PSA.js +211 -0
  59. package/dist/chunk-IG33DXLT.js +151 -0
  60. package/dist/chunk-IJBSOWHK.js +86 -0
  61. package/dist/chunk-INT7QLEU.js +114 -0
  62. package/dist/chunk-J7UYNJCR.js +9 -0
  63. package/dist/chunk-JEL35P7S.js +53 -0
  64. package/dist/chunk-JGJ4INEN.js +32 -0
  65. package/dist/chunk-JS5RTH4I.js +84 -0
  66. package/dist/chunk-JWRZDYB5.js +59 -0
  67. package/dist/chunk-KMXRRSKT.js +660 -0
  68. package/dist/chunk-LBXO4VPG.js +73 -0
  69. package/dist/chunk-LLBPVZXM.js +67 -0
  70. package/dist/chunk-LLT5FQBE.js +57 -0
  71. package/dist/chunk-LMT3PPXJ.js +17 -0
  72. package/dist/chunk-LMUBBIE2.js +83 -0
  73. package/dist/chunk-LTZH5E3G.js +479 -0
  74. package/dist/chunk-LW4TG7EL.js +39 -0
  75. package/dist/chunk-MPSQXSC6.js +346 -0
  76. package/dist/chunk-MVFH26QT.js +97 -0
  77. package/dist/chunk-NLEXKE7U.js +67 -0
  78. package/dist/chunk-NQPURJT5.js +44 -0
  79. package/dist/chunk-NRBQK6UX.js +105 -0
  80. package/dist/chunk-OEH47H6A.js +48 -0
  81. package/dist/chunk-OG7QR2DP.js +75 -0
  82. package/dist/chunk-OPYFEHKG.js +52 -0
  83. package/dist/chunk-P4N7DBD5.js +83 -0
  84. package/dist/chunk-PAX3QXX2.js +140 -0
  85. package/dist/chunk-PKODFR5F.js +102 -0
  86. package/dist/chunk-PMJG2CXF.js +122 -0
  87. package/dist/chunk-Q5H3L6Y4.js +23 -0
  88. package/dist/chunk-QEF7EK3T.js +28 -0
  89. package/dist/chunk-QEW4J3IZ.js +74 -0
  90. package/dist/chunk-QPL7E2HW.js +464 -0
  91. package/dist/chunk-R2GPCZUX.js +22 -0
  92. package/dist/chunk-R5MT42JS.js +284 -0
  93. package/dist/chunk-RMATE45Z.js +197 -0
  94. package/dist/chunk-RPQOBHVU.js +87 -0
  95. package/dist/chunk-S3PIAMXV.js +230 -0
  96. package/dist/chunk-T3LKX23M.js +168 -0
  97. package/dist/chunk-T6GOWHK6.js +30 -0
  98. package/dist/chunk-TIA4SPU2.js +10 -0
  99. package/dist/chunk-TNCZ6444.js +57 -0
  100. package/dist/chunk-TVL5RTE6.js +269 -0
  101. package/dist/chunk-TXQ7L33K.js +45 -0
  102. package/dist/chunk-UPQTAHUK.js +189 -0
  103. package/dist/chunk-V4NPDK6X.js +14 -0
  104. package/dist/chunk-VJFEN6DJ.js +38 -0
  105. package/dist/chunk-VMHUEOT5.js +643 -0
  106. package/dist/chunk-VRPMYPZU.js +4985 -0
  107. package/dist/chunk-WIW772I3.js +25 -0
  108. package/dist/chunk-XELAZAIM.js +136 -0
  109. package/dist/chunk-XNML2KIC.js +23 -0
  110. package/dist/chunk-XP2U3LO3.js +30 -0
  111. package/dist/chunk-YGOWIJPE.js +51 -0
  112. package/dist/chunk-YIXDHQYE.js +11 -0
  113. package/dist/chunk-YSAWTGNA.js +117 -0
  114. package/dist/claude-U2JC2DNQ.js +77 -0
  115. package/dist/cli-MI4ZCAZ3.js +41 -0
  116. package/dist/cli-ZN7ZVDEZ.js +46 -0
  117. package/dist/cli.js +144 -16197
  118. package/dist/completion-ILSRB3LW.js +142 -0
  119. package/dist/config-DnpLL2kT.d.ts +46 -0
  120. package/dist/{service-qpCsOXkQ.d.ts → core-C1LPjxK6.d.ts} +2 -6
  121. package/dist/diagnostics-XKXVVQWH.js +93 -0
  122. package/dist/doctor-O2E63YGO.js +538 -0
  123. package/dist/entry-X6CSYQRQ.js +305 -0
  124. package/dist/exec-mcp-2PMWBPD7.js +365 -0
  125. package/dist/harness-L2KSI2ZB.js +177 -0
  126. package/dist/harness-egress-bridge.js +4 -4
  127. package/dist/harness-launch-gate.js +47 -940
  128. package/dist/harness-pane-runner.js +13 -80
  129. package/dist/harness-worker.js +21 -2703
  130. package/dist/hook-body.js +5222 -0
  131. package/dist/hook-spec-C5fWTSCH.d.ts +100 -0
  132. package/dist/hook.js +26 -0
  133. package/dist/hooks-BHTA44X7.js +21 -0
  134. package/dist/host-UIZAXXQH.js +22 -0
  135. package/dist/host-UWK754BW.js +210 -0
  136. package/dist/host-run-BI2OTZDZ.js +307 -0
  137. package/dist/http.d.ts +5 -42
  138. package/dist/http.js +21 -2234
  139. package/dist/import-mcp-GPKJI7DI.js +400 -0
  140. package/dist/index.d.ts +146 -168
  141. package/dist/index.js +133 -4948
  142. package/dist/init-3C2Y7BNJ.js +14 -0
  143. package/dist/install-GG7HHZK2.js +796 -0
  144. package/dist/invoke-44CJRVMK.js +23 -0
  145. package/dist/list-MCP2FXUF.js +68 -0
  146. package/dist/list-WL6L4J5H.js +65 -0
  147. package/dist/load-BEUBABtB.d.ts +21 -0
  148. package/dist/logout-F5EJ5MOU.js +44 -0
  149. package/dist/logs-TBUA4UWU.js +107 -0
  150. package/dist/mailbox/index.d.ts +10 -5
  151. package/dist/mailbox/index.js +53 -1572
  152. package/dist/mailbox-BMTZOSZ7.js +285 -0
  153. package/dist/mailbox-GDJ7BWQN.js +189 -0
  154. package/dist/mainline-KAD2ERLP.js +639 -0
  155. package/dist/marketplace-G4VQET5W.js +191 -0
  156. package/dist/mcp-235QZN2A.js +15 -0
  157. package/dist/mcp-FJ2UQ4RH.js +193 -0
  158. package/dist/models-ISU4DCMA.js +32 -0
  159. package/dist/opencode-CN7JLQYO.js +60 -0
  160. package/dist/pause-7LILUVGL.js +18 -0
  161. package/dist/preview-DT7DWG5F.js +91 -0
  162. package/dist/project/hook-adapter.d.ts +5 -2
  163. package/dist/project/hook-adapter.js +41 -27
  164. package/dist/project-5YV5CUEG.js +70 -0
  165. package/dist/pty-XTJ4MIWK.js +94 -0
  166. package/dist/recovery-U6QB3PMT.js +100 -0
  167. package/dist/reindex-Y27QJFDB.js +22 -0
  168. package/dist/resume-26VFAAMH.js +18 -0
  169. package/dist/run-3AXTZSR7.js +126 -0
  170. package/dist/run-3SOVRQIA.js +19 -0
  171. package/dist/serve-DQMKTFIV.js +104 -0
  172. package/dist/session-XM2CR425.js +159 -0
  173. package/dist/setup-DTKZLZUT.js +18 -0
  174. package/dist/start-login-YTZV6KMF.js +416 -0
  175. package/dist/status-A2OUTNGK.js +9 -0
  176. package/dist/status-H2VAHIDV.js +10 -0
  177. package/dist/status-MROQ7WR7.js +43 -0
  178. package/dist/status-RO55QPKV.js +55 -0
  179. package/dist/status-UME2L33L.js +286 -0
  180. package/dist/stdio.d.ts +3 -13
  181. package/dist/stdio.js +16 -3186
  182. package/dist/sweep-35LGQTTO.js +18 -0
  183. package/dist/test-AGZOJLRZ.js +561 -0
  184. package/dist/tools-gpHNq9Dh.d.ts +328 -0
  185. package/dist/tui-G5LLWCSV.js +153 -0
  186. package/dist/unbroadcast-5QNGAJR2.js +18 -0
  187. package/dist/validate-IU52H2IC.js +46 -0
  188. package/dist/worker-QZ5T6LJD.js +80 -0
  189. package/dist/worktree-create-PZSRB7PH.js +89 -0
  190. package/dist/worktree-list-JYB6VXLW.js +51 -0
  191. package/dist/worktree-sync-UF5CXPWV.js +30 -0
  192. package/docs/authoring.md +82 -0
  193. package/docs/browser-and-desktop.md +46 -0
  194. package/docs/commands.md +325 -0
  195. package/docs/compare.md +35 -0
  196. package/docs/compatibility.md +55 -0
  197. package/docs/embeddings.md +1 -1
  198. package/docs/getting-started.md +105 -0
  199. package/docs/git-workflow.md +60 -0
  200. package/docs/glossary.md +31 -0
  201. package/docs/hooks/capabilities/antigravity.json +199 -0
  202. package/docs/hooks/capabilities/claude.json +179 -0
  203. package/docs/hooks/capabilities/codex.json +179 -0
  204. package/docs/hooks/capabilities/gemini.json +196 -0
  205. package/docs/hooks/capabilities/grok.json +192 -0
  206. package/docs/hooks/capabilities/opencode.json +184 -0
  207. package/docs/hooks.md +264 -0
  208. package/docs/install.md +72 -0
  209. package/docs/library-skills.md +132 -0
  210. package/docs/mailbox.md +16 -5
  211. package/docs/project-configuration.md +540 -58
  212. package/docs/sessions.md +64 -0
  213. package/docs/skills.md +4 -45
  214. package/docs/terminal-harness.md +92 -44
  215. package/docs/terminal-workspace.md +81 -169
  216. package/gemini-extension.json +2 -2
  217. package/mcp.json +1 -1
  218. package/package.json +16 -2
  219. package/plugin.json +2 -2
  220. package/plugins/pmcp/.claude-plugin/plugin.json +4 -2
  221. package/plugins/pmcp/.mcp.json +1 -1
  222. package/plugins/pmcp/gemini-extension.json +2 -2
  223. package/plugins/pmcp/mcp.json +1 -1
  224. package/plugins/pmcp/mod/commands.ts +72 -0
  225. package/plugins/pmcp/mod/contract.d.ts +39 -0
  226. package/plugins/pmcp/mod/draw.tsx +216 -0
  227. package/plugins/pmcp/mod/guard.ts +42 -0
  228. package/plugins/pmcp/mod/hooks.json +4 -0
  229. package/plugins/pmcp/mod/host.ts +46 -0
  230. package/plugins/pmcp/mod/model.ts +144 -0
  231. package/plugins/pmcp/mod/reader/index.ts +18 -0
  232. package/plugins/pmcp/mod/reader/read.ts +76 -0
  233. package/plugins/pmcp/mod/reader/settings.ts +54 -0
  234. package/plugins/pmcp/mod/reader/types.ts +38 -0
  235. package/plugins/pmcp/mod/register.tsx +73 -0
  236. package/plugins/pmcp/mod/sessions/format.ts +91 -0
  237. package/plugins/pmcp/mod/sessions/types.ts +162 -0
  238. package/plugins/pmcp/mod/snapshot.ts +75 -0
  239. package/plugins/pmcp/mod/spinner.tsx +30 -0
  240. package/plugins/pmcp/mod/state.ts +28 -0
  241. package/plugins/pmcp/plugin.json +2 -2
  242. package/plugins/pmcp/skills/agent-assets-migrate/SKILL.md +96 -0
  243. package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +101 -0
  244. package/plugins/pmcp/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
  245. package/plugins/pmcp/skills/package-skill-catalog/SKILL.md +51 -15
  246. package/plugins/pmcp/skills/pmcp-browser/SKILL.md +27 -0
  247. package/plugins/pmcp/skills/pmcp-desktop/SKILL.md +25 -0
  248. package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +153 -0
  249. package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +96 -0
  250. package/plugins/pmcp/skills/skill-package-scaffold/SKILL.md +89 -0
  251. package/schema/catalog-v1.json +187 -0
  252. package/schema/library.json +196 -0
  253. package/schema/marketplace-manifest.json +144 -0
  254. package/schema/plugin-manifest.json +59 -0
  255. package/schema/skill-frontmatter.json +170 -0
  256. package/schema/skill-metadata-core.json +131 -0
  257. package/skills/agent-assets-migrate/SKILL.md +96 -0
  258. package/skills/headless-agents-ci-scaffold/SKILL.md +101 -0
  259. package/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
  260. package/skills/package-skill-catalog/SKILL.md +51 -15
  261. package/skills/pmcp-browser/SKILL.md +27 -0
  262. package/skills/pmcp-desktop/SKILL.md +25 -0
  263. package/skills/pmcp-project-init/SKILL.md +153 -0
  264. package/skills/pmcp-sessions-and-git/SKILL.md +96 -0
  265. package/skills/skill-package-scaffold/SKILL.md +89 -0
  266. package/dist/config-BkSpjUG6.d.ts +0 -50
  267. package/dist/embed-DRROSD3F.d.ts +0 -53
  268. package/dist/hook-spec-CSJJySsH.d.ts +0 -11
  269. package/dist/server-VWSY3Shw.d.ts +0 -543
  270. package/dist/tui-worker.js +0 -6549
  271. package/docs/manual-library-skills.md +0 -74
  272. /package/dist/{tui-worker.d.ts → hook.d.ts} +0 -0
@@ -0,0 +1,35 @@
1
+ # How it compares
2
+
3
+ [Back to the overview](../README.md)
4
+
5
+ An agent that gets a library wrong usually gets it wrong the same way: it writes an API that was true two majors ago. Several things address that, and they are not interchangeable.
6
+
7
+ | Approach | Where the text comes from | What checks it |
8
+ | --------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
9
+ | The library's own docs site | Its maintainers | Nothing, for your version. A docs site describes latest; your lockfile does not say latest. |
10
+ | A rules file you wrote | You, once | Nothing, and it ages silently |
11
+ | Letting the agent search | Whatever ranked well today | Nothing. It cannot tell a current answer from a popular old one |
12
+ | A skill the package ships | Its maintainers | They do, and it is versioned with the package. This is the best case and it is free — pmcp reads these without an account. |
13
+ | A skill from this catalog | Us | Executing its examples against the version it names, before publishing |
14
+
15
+ ## When a shipped skill is the better answer
16
+
17
+ If the packages you depend on already ship a `SKILL.md`, use those. They come from the people who wrote the library, they update when it updates, and pmcp serves them to your agent for free. Nothing in the catalog beats a maintainer documenting their own work.
18
+
19
+ Run `npx -y @modootoday/pmcp list` to see which of your dependencies already do. If that covers you, you are done, and you should not pay us.
20
+
21
+ ## When the docs site is the better answer
22
+
23
+ You are reading, not delegating. A person deciding how to model a schema wants the whole document, its rationale and its edge cases. A skill is shaped for an agent that needs the right answer to one question in the middle of a task.
24
+
25
+ ## Where we think this earns its price
26
+
27
+ The catalog is for the packages nobody documented for an agent, where the failure is not "I could not find the docs" but "I found docs for a different version and they looked right".
28
+
29
+ The concrete claim is narrow: every skill here had its examples run against the version it names, on a date it states, and it was not published if any of them failed. Writing the first one caught three confident claims about a migration that were false in the current release. They were plausible, and a reader would have had no way to check.
30
+
31
+ ## What this is not
32
+
33
+ - Not a security product. We publish what a package did in our sandbox, which is a record of one run, not a judgement that anything is safe.
34
+ - Not a replacement for reading. It answers an agent's question in the middle of work.
35
+ - Not exhaustive. A skill covers the mistakes worth stopping, and says at the end what it does not cover.
@@ -0,0 +1,55 @@
1
+ # Compatibility
2
+
3
+ [Back to the overview](../README.md)
4
+
5
+ What runs where. Other pages link here instead of repeating requirements.
6
+
7
+ ## Platforms
8
+
9
+ | Part | Linux | macOS | Windows |
10
+ | -------------------------------------- | ------------------------------------------------ | -------------------------------- | ------------- |
11
+ | CLI, MCP server, `pmcp project`, hooks | yes | yes | not qualified |
12
+ | `pmcp tui` and harness groups | x64 and arm64, glibc 2.35 or later, user systemd | x64 and arm64, sessions uncapped | not supported |
13
+ | `pmcp harness host up` and `host unit` | user systemd manager required | refused | not supported |
14
+ | pmcp-browser and pmcp-desktop | x64 and arm64, glibc 2.35 or later | not shipped | not shipped |
15
+
16
+ All of them need Node.js 22 or later, or Bun 1.3 or later. npm installs pmcp-pty, pmcp-tui and
17
+ (on Linux) the two plugin binaries through a platform package, `@modootoday/pmcp-<os>-<cpu>`.
18
+ `PMCP_PTY_BIN` and `PMCP_TUI_BIN` point at other builds. On Linux a user systemd manager caps
19
+ each native session's memory; macOS runs sessions without that cap. The macOS binaries are
20
+ unsigned; installed through npm they run as they are, since npm sets no quarantine flag.
21
+
22
+ ## Native runtimes
23
+
24
+ | Runtime | `[targets] tools` | `pmcp tui` and harness id | `[[host.sessions]] runtime` |
25
+ | ----------------- | ----------------- | ------------------------- | --------------------------- |
26
+ | Claude Code | `claude` | `claude-code` | `claude` |
27
+ | Codex | `codex` | `codex-cli` | `codex` |
28
+ | Gemini CLI | `gemini` | `gemini-cli` | `gemini` |
29
+ | Grok Build | `grok` | `grok-cli` | `grok` |
30
+ | Antigravity (agy) | `antigravity` | `antigravity` | `agy` |
31
+ | OpenCode | `opencode` | not available | `opencode` |
32
+
33
+ Which hook features each runtime supports, as measured, is in
34
+ [Runtime support](hooks.md#runtime-support). Provider login, folder trust and
35
+ tool approvals stay in each runtime; pmcp never answers login, auth, trust or hook-review
36
+ prompts.
37
+
38
+ ## Installation and packaging
39
+
40
+ | Surface | Current qualification |
41
+ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
42
+ | CLI and MCP on Linux amd64 | Published 0.15.0 passed clean Docker installation with npm on Debian/Alpine and Bun/pnpm on Debian; 60 installation and failure contracts |
43
+ | Optional terminal workspace | Linux pmcp-pty checks and a native Claude main with a Gemini worker (control, input, wake turns, recovery); other runtimes measured on tmux in 0.17 |
44
+ | Public skill installation | npm, Bun and pnpm 10.17.1; confirmation required, scripts disabled |
45
+ | Native plugin export | Claude, Codex, Gemini, Grok and agy formats; export does not install or activate a vendor plugin |
46
+ | pnpm workspace installation | Selects the member, preserves root dependencies and updates the shared lockfile |
47
+ | Yarn skill installation | Refused without changing project files; Yarn PnP is not supported |
48
+ | Docker profile for the harness | Codex 0.161.0 login and main/worker responses through the profile's proxy; other vendors and token refresh not measured |
49
+ | OpenCode user-only skills | OpenCode 1.18.33: `invocation = "user"` hides the skill from the model and keeps the `/<name>` command, measured with isolated CLI calls and scripted responses, no model call |
50
+
51
+ Provider authentication, native children and vendor behavior have separate
52
+ qualification scopes. An installed executable or exported manifest is not proof
53
+ that every native feature works. The packed-package check, run before a
54
+ release, covers actual archive installation, CLI startup, MCP and SQLite; isolated projects
55
+ on a host are distinct from Docker and OS qualification.
@@ -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) |
@@ -0,0 +1,199 @@
1
+ {
2
+ "runtime": "antigravity",
3
+ "version": "1.3.3",
4
+ "measuredAt": "2026-10-20T00:50:00Z",
5
+ "configuration": {
6
+ "hooks": ".agents/hooks.json in the workspace customization root (also the global customization root, and plugins/<name>/hooks.json). Top-level keys are hook names, each with optional enabled and per-event arrays.",
7
+ "trust": "none: project hooks ran in a fresh, never-opened directory with no trust prompt, interactive or headless",
8
+ "headless": "agy -p '<prompt>' --output-format json [--print-timeout <d>]. Tools needing the command permission are auto-denied in headless mode unless permissions.allow (user settings.json) allows them or --dangerously-skip-permissions is passed; a PreToolUse allow does not grant that permission.",
9
+ "mcp": "documented: mcp_config.json in a customization root (.agents/) or plugins/<name>/mcp_config.json; pmcp already projects .agents/plugins/pmcp-mcp. Not exercised in this run."
10
+ },
11
+ "events": {
12
+ "session_start": {
13
+ "native": "PreInvocation (invocationNum 0, initialNumSteps 1)",
14
+ "fires": true,
15
+ "notes": "no such event; PreInvocation with invocationNum 0 is the first hook of a run"
16
+ },
17
+ "prompt": {
18
+ "native": "PreInvocation",
19
+ "fires": true,
20
+ "fields": [
21
+ "conversationId",
22
+ "workspacePaths",
23
+ "transcriptPath",
24
+ "artifactDirectoryPath",
25
+ "modelName",
26
+ "invocationNum",
27
+ "initialNumSteps"
28
+ ],
29
+ "notes": "fires before every model call, not once per prompt; no prompt text in the payload"
30
+ },
31
+ "before_tool": {
32
+ "native": "PreToolUse",
33
+ "fires": true,
34
+ "fields": [
35
+ "conversationId",
36
+ "workspacePaths",
37
+ "transcriptPath",
38
+ "artifactDirectoryPath",
39
+ "modelName",
40
+ "stepIdx",
41
+ "toolCall"
42
+ ]
43
+ },
44
+ "after_tool": {
45
+ "native": "PostToolUse",
46
+ "fires": true,
47
+ "fields": [
48
+ "conversationId",
49
+ "workspacePaths",
50
+ "transcriptPath",
51
+ "artifactDirectoryPath",
52
+ "modelName",
53
+ "stepIdx",
54
+ "toolCall",
55
+ "error"
56
+ ],
57
+ "notes": "fires only for calls that ran; not for a hook-denied call; no tool output in the payload"
58
+ },
59
+ "after_model": {
60
+ "native": "PostInvocation",
61
+ "fires": true,
62
+ "fields": ["same as PreInvocation"]
63
+ },
64
+ "stop": {
65
+ "native": "Stop",
66
+ "fires": true,
67
+ "fields": [
68
+ "conversationId",
69
+ "workspacePaths",
70
+ "transcriptPath",
71
+ "artifactDirectoryPath",
72
+ "modelName",
73
+ "executionNum",
74
+ "terminationReason",
75
+ "error",
76
+ "fullyIdle"
77
+ ]
78
+ },
79
+ "session_end": {
80
+ "native": null,
81
+ "fires": false,
82
+ "notes": "no such event"
83
+ },
84
+ "notification": {
85
+ "native": null,
86
+ "fires": false,
87
+ "notes": "no such event"
88
+ }
89
+ },
90
+ "tools": {
91
+ "shell": {
92
+ "tool_name": "run_command",
93
+ "input": "toolCall.args.CommandLine, toolCall.args.Cwd (also WaitMsBeforeAsync, toolAction, toolSummary)"
94
+ },
95
+ "edit": {
96
+ "tool_name": "write_to_file (create)",
97
+ "input": "toolCall.args.TargetFile, CodeContent, Overwrite, Description"
98
+ }
99
+ },
100
+ "outputs": {
101
+ "deny": {
102
+ "event": "before_tool",
103
+ "support": "measured",
104
+ "shape": "{decision: deny, reason}; the step fails with 'tool call denied by pre-tool hook: <reason>' and the model reads the reason. Holds under --dangerously-skip-permissions."
105
+ },
106
+ "missing_decision": {
107
+ "support": "measured",
108
+ "notes": "A PreToolUse result without decision (for example {}) denies the call with an empty reason and stops that hook's handler chain. Run 1 lost every tool call this way: a recorder returning {} ran before the probe."
109
+ },
110
+ "allow": {
111
+ "support": "measured",
112
+ "notes": "decision allow lets the hook chain pass but does not grant the headless command permission (run 2: auto-denied, run ended with no output)"
113
+ },
114
+ "context": {
115
+ "support": "measured",
116
+ "delivered": ["session_start", "prompt", "stop"],
117
+ "shape": "PreInvocation/PostInvocation return injectSteps [{ephemeralMessage}] (also userMessage, toolCall); transcript step EPHEMERAL_MESSAGE, source SYSTEM_SDK",
118
+ "not_delivered": ["before_tool reason on allow"],
119
+ "native_delivered": [
120
+ "prompt (PreInvocation)",
121
+ "after_model (PostInvocation)",
122
+ "stop"
123
+ ],
124
+ "deferred": {
125
+ "before_tool": "stop (continue at executionNum 0); V2 antigravity-context-before-599fce53"
126
+ }
127
+ },
128
+ "stop_context": {
129
+ "support": "measured",
130
+ "notes": "Stop {decision: continue, reason} re-enters the loop and injects the reason as a SYSTEM_MESSAGE; executionNum counts re-entries (0, then 1). An unconditional continue would loop; policies must continue only when executionNum is 0. In the smoke run a continue left print mode waiting until --print-timeout."
131
+ },
132
+ "ask": {
133
+ "support": "documented",
134
+ "notes": "decision ask / force_ask prompt the user; headless cannot prompt"
135
+ }
136
+ },
137
+ "fields_absent": [
138
+ "session_id (conversationId instead)",
139
+ "cwd (workspacePaths and toolCall.args.Cwd instead)",
140
+ "hook_event_name (the event is known only from the configured key)",
141
+ "agent_type",
142
+ "prompt text"
143
+ ],
144
+ "timeouts": "handler timeout in seconds, default 30",
145
+ "trust": "none for workspace .agents/hooks.json",
146
+ "live": {
147
+ "version": "1.4.2",
148
+ "measuredAt": "2026-10-20T04:07:39.189Z",
149
+ "implementationCommits": ["cfcdf5a", "35f3c77"],
150
+ "deny": {
151
+ "support": "measured",
152
+ "scenarios": [
153
+ "antigravity-heredoc-bb1ebeb1",
154
+ "antigravity-stage-all-cd3d679e",
155
+ "antigravity-pause-521c0215",
156
+ "antigravity-lease-59a85a08"
157
+ ]
158
+ },
159
+ "context": {
160
+ "support": "measured",
161
+ "scenarios": {
162
+ "context-start": "antigravity-context-start-1cc194a9",
163
+ "context-prompt": "antigravity-context-prompt-fad83dcf",
164
+ "context-before": "antigravity-context-before-599fce53",
165
+ "broadcast": "antigravity-broadcast-152964dc"
166
+ },
167
+ "notes": "pause, broadcast and shared_checkout notices reached the model; held context arrived at the next delivering event"
168
+ },
169
+ "workflow": {
170
+ "support": "measured",
171
+ "scenarios": [
172
+ "antigravity-worktree-create-2205cf0e",
173
+ "antigravity-worktree-sync-3aa5f8a5",
174
+ "antigravity-deliver-b1048684",
175
+ "antigravity-deliver-race-ece6d671",
176
+ "antigravity-git-sync-1c9dc319"
177
+ ]
178
+ },
179
+ "cost": [
180
+ {
181
+ "event": "before_tool",
182
+ "addedMs": 22.7
183
+ },
184
+ {
185
+ "event": "prompt",
186
+ "addedMs": 19.1
187
+ }
188
+ ],
189
+ "turns": {
190
+ "support": "measured",
191
+ "finding": "agy 1.4.2 resets invocationNum for a later prompt in one conversation: 2 PreInvocation calls were dispatched at invocationNum 0, one per turn, so prompt policies run on every turn."
192
+ },
193
+ "scenarios": {
194
+ "passed": 13,
195
+ "failed": []
196
+ }
197
+ },
198
+ "binary": "agy"
199
+ }