@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
@@ -1,8 +1,8 @@
1
1
  import {
2
2
  change
3
- } from "./chunk-RK4PYD7L.js";
4
- import "./chunk-SG5TPMKH.js";
5
- import "./chunk-Z4HRRXRF.js";
3
+ } from "./chunk-LBXO4VPG.js";
4
+ import "./chunk-26WLNWDG.js";
5
+ import "./chunk-LTZH5E3G.js";
6
6
  import "./chunk-C4NHQGHL.js";
7
7
  import "./chunk-A4PKLESO.js";
8
8
  import "./chunk-OEH47H6A.js";
@@ -15,4 +15,4 @@ var run = (context) => change(context, "unbroadcast");
15
15
  export {
16
16
  run
17
17
  };
18
- //# sourceMappingURL=unbroadcast-KPUEFLZD.js.map
18
+ //# sourceMappingURL=unbroadcast-5QNGAJR2.js.map
@@ -1,20 +1,20 @@
1
1
  import {
2
2
  catalogOptionsFrom
3
- } from "./chunk-5QQWS4US.js";
3
+ } from "./chunk-HEBCQTOD.js";
4
4
  import {
5
5
  configFrom
6
6
  } from "./chunk-7DLZC73N.js";
7
7
  import {
8
8
  validateCatalog,
9
9
  validateSkillDir
10
- } from "./chunk-NZS5CD72.js";
10
+ } from "./chunk-HEWZ6INU.js";
11
11
  import "./chunk-73AKO4UL.js";
12
12
  import {
13
13
  validateSpec
14
14
  } from "./chunk-INT7QLEU.js";
15
15
  import "./chunk-JEL35P7S.js";
16
16
  import "./chunk-A4PKLESO.js";
17
- import "./chunk-KMXRRSKT.js";
17
+ import "./chunk-4CRRLDDS.js";
18
18
  import "./chunk-YSAWTGNA.js";
19
19
  import "./chunk-QPL7E2HW.js";
20
20
  import "./chunk-PMJG2CXF.js";
@@ -43,4 +43,4 @@ var validateCommand = {
43
43
  export {
44
44
  validateCommand
45
45
  };
46
- //# sourceMappingURL=validate-5GZ5YWNA.js.map
46
+ //# sourceMappingURL=validate-AVM2VHMM.js.map
@@ -1,24 +1,24 @@
1
1
  import {
2
2
  invoke
3
- } from "./chunk-ELAGZ635.js";
3
+ } from "./chunk-7PTG42QU.js";
4
4
  import {
5
5
  readStartup,
6
6
  startupFile,
7
7
  startupSettings
8
8
  } from "./chunk-PAX3QXX2.js";
9
9
  import "./chunk-DZ2MRTYT.js";
10
- import "./chunk-EJBZGIDK.js";
11
- import "./chunk-MWFOUBFC.js";
10
+ import "./chunk-6BN35BHI.js";
11
+ import "./chunk-HFE4QDJQ.js";
12
12
  import {
13
13
  locateExecutable
14
14
  } from "./chunk-R2GPCZUX.js";
15
- import "./chunk-R4L6LJJ2.js";
15
+ import "./chunk-FX3LTTMB.js";
16
16
  import "./chunk-34DECPVC.js";
17
- import "./chunk-4VCC2NXE.js";
18
- import "./chunk-665TA55Z.js";
17
+ import "./chunk-2RTRY45B.js";
18
+ import "./chunk-TAOOPXBV.js";
19
19
  import "./chunk-OEH47H6A.js";
20
20
  import "./chunk-IJBSOWHK.js";
21
- import "./chunk-E7OOHLQR.js";
21
+ import "./chunk-AF2IBMWN.js";
22
22
  import "./chunk-QPL7E2HW.js";
23
23
  import "./chunk-PMJG2CXF.js";
24
24
  import {
@@ -77,4 +77,4 @@ async function startWorkspaceWorker(request, runtime, memoryMb) {
77
77
  export {
78
78
  startWorkspaceWorker
79
79
  };
80
- //# sourceMappingURL=worker-RQ575EJL.js.map
80
+ //# sourceMappingURL=worker-3VS6RQEL.js.map
@@ -0,0 +1,82 @@
1
+ # Shipping a skill in your package
2
+
3
+ [Back to the overview](../README.md)
4
+
5
+ Three things have to be true: the file is somewhere the walk reaches, its frontmatter carries a `description`, and the tarball actually contains it.
6
+
7
+ ## Where the file goes
8
+
9
+ Any of these, and the walk does not care which. They are the conventions different agents settled on, and one directory read sees them all:
10
+
11
+ ```text
12
+ <package>/skills/<slug>/SKILL.md
13
+ <package>/.agent/skills/<slug>/SKILL.md
14
+ <package>/.claude/skills/<slug>/SKILL.md
15
+ <package>/.gemini/skills/<slug>/SKILL.md
16
+ <package>/.codex/skills/<slug>/SKILL.md
17
+ ```
18
+
19
+ The path is not what makes it a skill; the file is. Each installed package is walked to a depth of three, and any `SKILL.md` found is a skill, so a convention nobody has invented yet works too.
20
+
21
+ ### Where it must not go
22
+
23
+ The walk skips directories that cannot hold a package's own skill and are expensive or misleading to enter. A `SKILL.md` under any of these is invisible:
24
+
25
+ | Kind | Directories |
26
+ | -------------------------- | ------------------------------------------------------------------------------------------- |
27
+ | build output | `dist`, `build`, `out`, `lib`, `es`, `esm`, `cjs`, `umd` |
28
+ | sources and types | `src`, `types`, `typings`, `bin` |
29
+ | test corpora | `test`, `tests`, `__tests__`, `fixtures`, `__fixtures__`, `example`, `examples`, `coverage` |
30
+ | nested installs and caches | `node_modules`, `.git`, `.turbo`, `.cache` |
31
+
32
+ The common mistake is authoring the skill in `src/` and letting the build copy it to `dist/`. Both ends of that are skipped. Keep the file at a path that ships as written.
33
+
34
+ ## The frontmatter
35
+
36
+ ```markdown
37
+ ---
38
+ name: release-runbook
39
+ description: A deploy went out but the container still runs the old bundle, and rebuilding does not change it.
40
+ ---
41
+
42
+ # Releasing
43
+
44
+ …
45
+ ```
46
+
47
+ Two fields are read. `name` becomes the slug, and the skill is addressed as `<package>/<slug>`; leave it out and the directory holding the file names it, or the package itself does when the file sits at the package root.
48
+
49
+ `description` is the only text that [`skill_find`](getting-started.md) ranks. A skill without one is skipped rather than listed: ranking could never surface it, so listing it would spend a session's tokens on an entry that cannot answer.
50
+
51
+ The reader is not a YAML parser. It takes flat scalars on their own line, strips one pair of surrounding quotes, and ignores anything nested. That is the honest limit rather than a partial YAML, and it means a description folded over several lines is not read as you intended.
52
+
53
+ ## Write the description as a symptom
54
+
55
+ A reader arrives with a problem, not with your vocabulary. They will not type your package's name, because not knowing it is why they are asking. Descriptions that name the symptom are the ones a sentence can reach.
56
+
57
+ | Instead of | Write |
58
+ | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
59
+ | `Utilities for distributed locks, leases and fencing tokens.` | `A job ran twice because two workers took the same lock, or a lock outlived the worker holding it.` |
60
+ | `Deployment helpers and image build configuration.` | `A deploy went out but the container still runs the old bundle, and rebuilding does not change it.` |
61
+
62
+ Both halves of the lexical score reward this. It compares the words of the question against the words of the description, and a feature list shares its words with every other feature list in the catalog.
63
+
64
+ Name the failure, the surprise, and the thing the reader already tried. One or two sentences. It is read by whoever is choosing between five candidates, so it is a filter, not a summary of the body.
65
+
66
+ ## Ship the file
67
+
68
+ ```json
69
+ {
70
+ "files": ["dist", "skills", "README.md"]
71
+ }
72
+ ```
73
+
74
+ A `SKILL.md` outside the manifest's `files` array is not in the tarball, and therefore not in anyone's `node_modules`. This fails quietly: your repository has the skill, your tests find it, and no consumer ever sees it.
75
+
76
+ Check by installing your own tarball into an empty project and running `npx -y @modootoday/pmcp list` there. If the name is not in that output, no agent will find it either.
77
+
78
+ ## The body
79
+
80
+ Everything after the closing `---` is the body, and `skill_call` returns it whole. It is read on its own, by someone who has seen only the description, so it should not depend on the rest of your documentation site to make sense.
81
+
82
+ **Two skills can share a name only once.** The catalog is keyed by `<package>/<slug>` and the first root wins, so a nested copy of your package is ignored in favour of the one the project actually resolved.
@@ -0,0 +1,46 @@
1
+ # Browser and desktop for agents
2
+
3
+ [Back to the overview](../README.md)
4
+
5
+ pmcp-browser and pmcp-desktop give agents a browser and a desktop on a Linux server, as MCP
6
+ servers. What they may reach is set in `[host]` of the [pmcp.toml reference](project-configuration.md#sessions-pmcp-pty-hosts).
7
+
8
+ Claude Code and Codex offer browser and computer use only through their
9
+ desktop apps, not on a Linux server. Two MCP servers built from this
10
+ repository cover that ground for every runtime pmcp projects to:
11
+
12
+ - `pmcp-browser` (`crates/pmcp-plugin-browser-use`): an isolated Chromium,
13
+ headless, with a fresh profile per launch. It reaches public http(s) sites
14
+ only: every request goes through its own proxy, which refuses loopback,
15
+ private, link-local, metadata and CGNAT addresses and every port but 80 and 443. Local schemes such as `file:` are blocked in the page.
16
+ - `pmcp-desktop` (`crates/pmcp-plugin-computer-use`): an Xvfb desktop driven
17
+ through screenshots and XTEST input, for any X11 app.
18
+
19
+ Each runs in its own memory-capped systemd scope (2G and 512M by default),
20
+ and `pmcp-browser` allows two at a time on the host. Both have `doctor`
21
+ (read-only, with the exact fix) and `setup --plan`; root steps are printed,
22
+ never run. Both ship in the Linux platform package npm installs with PMCP
23
+ (glibc 2.35 or later), which does not put them on PATH. Declare them like
24
+ any MCP server with the bare name as `command`; `pmcp project` resolves it to
25
+ the installed binary, so pmcp.toml names no host path:
26
+
27
+ ```toml
28
+ [mcp.pmcp-browser]
29
+ command = "pmcp-browser"
30
+ args = ["serve", "--approved", "<the directory pmcp harness host status reports>"]
31
+
32
+ [mcp.pmcp-desktop]
33
+ command = "pmcp-desktop"
34
+ args = ["serve", "--geometry", "1440x900x24"]
35
+ ```
36
+
37
+ `pmcp doctor` reports where each resolved, or why not (no platform
38
+ package for this host, as on macOS); an unresolved name runs from PATH. An
39
+ absolute `command`, such as your own build, is kept as written.
40
+
41
+ The names avoid Claude Code's built-in `computer-use`. `--approved` is
42
+ optional: without it the browser is public-only and the desktop launches
43
+ nothing. `[host.browser] allow_private` and `[[host.desktop.launch]]` come
44
+ into force only through `pmcp harness host approve`. Running the browser
45
+ headed on the desktop's display also needs the managed Chromium policy that
46
+ `pmcp-browser setup --plan` prints for you to install.
@@ -0,0 +1,325 @@
1
+ # Command reference
2
+
3
+ [Back to the overview](../README.md)
4
+
5
+ Every pmcp command with its flags, behaviour and exit codes. `pmcp <command> --help` prints
6
+ the same usage from the command itself.
7
+
8
+ ## The invocation a host uses
9
+
10
+ - `pmcp` opens a workspace on a supported terminal; a piped launch runs the MCP server on
11
+ stdio.
12
+ - `pmcp --root ./node_modules`: a leading option with no command is still a server, because
13
+ hosts pass options without one.
14
+
15
+ An unrecognised command does not fall through to a server the caller did not ask for. Only an empty argument list, or one that begins with an option, takes that path.
16
+
17
+ ## status
18
+
19
+ ```sh
20
+ pmcp status [--config <file>] [--json]
21
+ ```
22
+
23
+ Show enabled features and their TOML or auto source, projection drift, live sessions, pause, leases, unseen broadcasts, worktree ahead/behind counts, shared MCP credential presence, and logged errors from the last hour. Reads do not acknowledge broadcasts, refresh credentials, prune logs, fetch or move git refs. Projection uses the same check as `project --check`. Exit 0, or 2 when projection or worktree ahead/behind drift exists. Missing or invalid input follows the normal usage/failure exit contract. Human output is a compact summary on stderr; JSON retains the full details.
24
+
25
+ ## init
26
+
27
+ ```sh
28
+ pmcp init [--preset solo|multi-session] [--force]
29
+ ```
30
+
31
+ Create `pmcp.toml` in the current directory. Solo enables Claude/Codex targets, the stage-all and heredoc guards, and detected git settings. Multi-session adds registry, pause and broadcast; in git it also enables worktree commands and shared-checkout warnings. Git remote and mainline come from the same detection used by the git workflow. No gate, installation command, MCP credential or provider is invented. Both presets are parsed and compiled before writing. Existing files require `--force`. Output explains each choice; projection remains a separate explicit operation. Exit 0 on creation, 2 for a bad preset or refused overwrite, 1 for a write failure.
32
+
33
+ ## hooks
34
+
35
+ ```sh
36
+ pmcp hooks list [--runtime claude|codex] [--config <file>] [--json]
37
+ pmcp hooks test --runtime claude|codex --event before_tool --command "git add -A" [--json]
38
+ pmcp hooks test --runtime claude --event before_tool --path fixture.txt --session-state state.json
39
+ ```
40
+
41
+ List compiled policies per runtime and neutral event, including mode and source table. Test constructs a synthetic payload in that runtime's recorded shape, normalizes it, runs policy selection and composition, lowers unsupported asks, and renders the native response. The event accepts a neutral name or a supported native name. Choose at most one of `--command`, `--path` and `--tool`; these selectors require a tool event. Tool accepts a native name or shell, edit, read or other, subject to that runtime's tool vocabulary. No native runtime or model call is needed.
42
+
43
+ Session state is isolated in a temporary directory, then removed. Commands and patches are classified, never executed. External custom guards, validators, Stop projection subprocesses and worktree synchronization are explicitly marked skipped. Their simulated context reports this limitation; the command does not claim a full live result. Exit 0 means the simulation completed, even when the rendered decision denies; invalid input exits 2. Per-policy timings and reasons precede the rendered output in human mode.
44
+
45
+ `--session-state` accepts a JSON object with optional `records` (session records with valid 8–64 character IDs), `pause` (by, reason, since), `leases` (name to pid, subject, since, optional cwd), and `broadcast` (id, by, text, since). Pause and broadcast may be null. Existing liveness and unseen-broadcast rules apply. This file and the real session store remain unchanged.
46
+
47
+ ## Read command JSON schemas
48
+
49
+ These opt-in snapshots write one JSON object and a newline to stdout, with `version: 1`. No color or human summary is mixed into stdout. Errors remain on stderr. Without the flag, existing human output is retained, including MCP status's original unversioned object and logs' JSONL stream. Schemas are named in [schemas.json](https://pmcp.build/commands/schemas.json); each entry under `schemas` uses the shared root `$defs`. Consumers must allow unknown fields inside session, decision and log records. Tokens are never part of an auth status object.
50
+
51
+ | Command | Schema | Fields after version |
52
+ | -------------------------- | ----------------- | --------------------------------------------------------------------- |
53
+ | `status --json` | status | config, drift, features, projection, sessions, worktrees, mcp, errors |
54
+ | `hooks list --json` | hooks-list | policies: runtime, event, policy, mode, source |
55
+ | `hooks test --json` | hooks-test | runtime, event, payload, decision, policies, rendered |
56
+ | `sessions status --json` | sessions-status | live, pause, leases, broadcasts with unseenBy session IDs |
57
+ | `logs --json` | logs | records; filtered snapshot, incompatible with --follow and --pretty |
58
+ | `git worktree list --json` | git-worktree-list | worktrees: path, main, optional alias, branch, behind and ahead |
59
+ | `mcp status <name> --json` | mcp-status | name, present, expiresAt (UTC string or null), scopes |
60
+
61
+ Feature rows have feature, enabled and source. Projection has drift, outputs and problems. Session snapshots include only live records; broadcasts include the IDs that have not yet seen each entry. Worktree counts are omitted when the upstream cannot be compared; absence does not assert equality. Status auth rows add a redacted error when credentials are unavailable or invalid. Errors are JSONL records with valid timestamps within the last hour, excluding future rows. Hooks test observations have policy, mode, decision, durationMs, skipped, source, verdict and reason; rendered has stdout and exitCode. The final decision includes runtime lowering, while each policy row retains its configured verdict. Mutating sessions, git and MCP verbs reject `--json`.
62
+
63
+ ## serve
64
+
65
+ ```sh
66
+ pmcp serve [--config <file>] [--root <dir>] [--scope <prefix>] [embedding options]
67
+ ```
68
+
69
+ Reachable by name so it appears in help. It writes nothing to standard output: from the moment it starts, standard output is the protocol, and a diagnostic printed there corrupts the stream.
70
+
71
+ ## list
72
+
73
+ ```sh
74
+ pmcp list [--root <dir>] [--scope <prefix>] [--json]
75
+ ```
76
+
77
+ The skills discovered in `node_modules`, as two aligned columns, or as JSON for a script. This is the command that answers "would the server see anything from here".
78
+
79
+ ## marketplace
80
+
81
+ ```sh
82
+ pmcp marketplace list --json
83
+ pmcp marketplace export typescript-5 --runtime agy --output ./typescript-plugin
84
+ agy plugin install ./typescript-plugin
85
+ ```
86
+
87
+ List the bundled free plugins or export one selected native package. Choose `claude`, `codex`, `gemini`, `grok` or `agy`. An export preserves existing destinations and does not edit runtime configuration or bypass native installation consent. CLI discovery includes the built-in catalog unless `--no-builtin` or `[catalog] builtin = false` is configured.
88
+
89
+ An empty catalog is a finding rather than a success. It exits **1** and names the roots it walked, because a project that installed this and sees nothing has a misconfiguration worth an exit code.
90
+
91
+ ## index
92
+
93
+ ```sh
94
+ pmcp index [--config <file>] [embedding options] [--local-only] [--dry-run] [--force] [--json]
95
+ ```
96
+
97
+ Encodes each description once so ranking can be semantic, and stores the vectors beside the tree they describe, so two projects never share one index. Only what changed is re-encoded; an unchanged description produces the same vector at the same cost as the first time.
98
+
99
+ Vectors written by one model are never scored against another, so `--model` is part of the key rather than a preference. Without the optional peer installed it exits **3** and tells you ranking stays lexical, which is the default and not a failure.
100
+
101
+ A partial index is reported rather than called success: it exits **1** and says how many of the catalog it covered, because ranking needs a vector for every entry and falls back to lexical without one.
102
+
103
+ ## models
104
+
105
+ ```sh
106
+ pmcp models [--json]
107
+ ```
108
+
109
+ Lists the default E5 encoder and optional EmbeddingGemma presets with their dimensions and asset revisions. It does not load an encoder or download weights. Configure `[embedding]` in `pmcp.toml` or override individual settings on the CLI.
110
+
111
+ ```sh
112
+ pmcp index --model embeddinggemma-2 --dtype q4 --dimensions 256
113
+ pmcp serve --model embeddinggemma-2 --dtype q4 --dimensions 256
114
+ ```
115
+
116
+ Shared embedding options are `--model`, `--dtype`, `--dimensions`, `--model-revision`, `--model-path`, `--model-cache`, `--query-prefix`, `--passage-prefix`, and `--pooling`. They override the corresponding configuration fields. Use `--no-config` for an independent CLI selection. Model identity includes revision, dtype, dimensions, prefixes, pooling, and projection, so incompatible vectors and query caches stay separate.
117
+
118
+ `index --local-only` refuses downloads, `--dry-run` previews work without loading a model or writing vectors, and `--force` rebuilds only the selected encoder's index. `serve` never downloads weights: it uses a complete matching local index or reports a lexical fallback. Restart after switching encoder settings.
119
+
120
+ ## mailbox
121
+
122
+ ```sh
123
+ pmcp mailbox init --config ./pmcp.toml
124
+ pmcp mailbox actor --config ./pmcp.toml --actor reviewer --actor-file /private/reviewer.actor.json
125
+ pmcp serve --config ./pmcp.toml --mailbox-actor-file /private/reviewer.actor.json --mailbox-runtime codex-cli
126
+ ```
127
+
128
+ Mailbox is disabled by default. Initialization creates a project UUID and preserves existing configuration. A launcher-bound actor enables `mailbox_send`, `mailbox_inbox`, `mailbox_read`, `mailbox_ack`, and `mailbox_sessions`. Reading records a receipt; acknowledgement requires reading first. Acknowledgement does not assert task completion.
129
+
130
+ Credentials and attachment files contain secrets and must stay outside source control. State defaults to the user's XDG state directory. Administrative `rotate`, `export`, `backup`, and `restore` operations require `--operator`. Use `pmcp mailbox --help` for inputs. The mailbox exchanges peer data; the host owns authentication, automatic runtime delivery, and enterprise policy.
131
+
132
+ ## project
133
+
134
+ ```sh
135
+ pmcp project
136
+ pmcp project --check
137
+ pmcp project import-mcp --source codex:/path/to/config.toml
138
+ ```
139
+
140
+ Generate selected runtimes' native files from `pmcp.toml`. Unmanaged entries and credential references are preserved; conflicts stop the write. `--check` reports drift without writes, and MCP import previews changes by default; `--write` applies them. [Configuration and guard examples](project-configuration.md).
141
+
142
+ Configuration files and the ownership lock are replaced atomically one file at a time. If projection is interrupted, inspect with `pmcp project --check`, then run `pmcp project` explicitly to repair drift. Projection does not start a runtime or replay terminal input. The complete set of files is not a single transaction.
143
+
144
+ ## sessions
145
+
146
+ ```sh
147
+ pmcp sessions status
148
+ pmcp sessions pause "release freeze" [--by <name>]
149
+ pmcp sessions resume
150
+ pmcp sessions broadcast "main moved; rebase before delivering" [--by <name>]
151
+ pmcp sessions unbroadcast
152
+ pmcp sessions sweep
153
+ pmcp sessions send --to <selector>... [--subject <s>] [--wake] <body>
154
+ pmcp sessions inbox
155
+ ```
156
+
157
+ Coordinate the live agent sessions of this repository and its worktrees, through the state the hooks keep for [`[sessions]`](project-configuration.md#sessions). `status` (the default verb) prints each live session, the pause, current broadcasts, held leases and undelivered edits in a shared checkout to standard output, or `no live sessions`. `pause` refuses edits and mutating commands in every other session until `resume`; `broadcast` delivers its text once to each session as context, and `unbroadcast` withdraws it. `--by` names the sender, whose own session is exempt; it defaults to `operator`. `sweep` removes records whose process is gone. `send` addresses `all`, `session:<id>`, `alias:<name>`, `role:<name>` or `worktree:<path>` through `[sessions.mailbox]`; `inbox` lists your messages. [Run several agents](sessions.md) walks through them. Exit 0, or 2 for an unknown verb, missing text or no `pmcp.toml`.
158
+
159
+ ## logs
160
+
161
+ ```sh
162
+ pmcp logs --since 10m --level warn --pretty
163
+ pmcp logs --session 4f92 --component hooks
164
+ pmcp logs --trace 7cef825e8fbd8c3f
165
+ pmcp logs --follow
166
+ ```
167
+
168
+ Read this project's JSONL logs from the state directory, or the file `[hooks] error_log` names. Filters combine: `--session` takes an id prefix, `--trace` one hook call, `--component` a component and those below it, `--level` that level and more severe, `--since` a duration (`10m`, `2h`, `3d`) or an ISO time. Records print as JSON lines unless `--pretty`; `--follow` keeps printing until interrupted. Secret values, prompt text and environment values are redacted at write time, per [`[logging]`](project-configuration.md#logging). Exit 0, or 2 for an unusable filter or no `pmcp.toml`.
169
+
170
+ ## git
171
+
172
+ ```sh
173
+ pmcp git worktree create review [--base <ref>]
174
+ pmcp git worktree list
175
+ pmcp git worktree sync
176
+ pmcp git deliver [<commit>...] [--during-pause]
177
+ pmcp git sync
178
+ ```
179
+
180
+ The git workflow configured by [`[git]`](git-workflow.md). Each subcommand needs its table; without it the command exits 1 and names the missing table.
181
+
182
+ - `worktree create <alias>` makes a linked worktree under `[git.worktrees] root` on a new branch from the upstream (or `--base`), links the configured files from the main checkout, runs `bootstrap`, and prints the path.
183
+ - `worktree list` prints alias, branch, behind/ahead and path for the main checkout and each linked worktree.
184
+ - `worktree sync` moves the current worktree onto the mainline when that loses nothing; exit 1 when it is held back.
185
+ - `deliver` fetches, replays the named commits (default: the ones the upstream lacks) onto the mainline, runs the gate in its own tree under a lock, and pushes; it replays again if the mainline moved. A delivery that touches a leased path holds that lease until it has pushed and installed, and it refuses during a pause unless `--during-pause` or `during_pause = "allow"`. Exit 0 delivered or nothing to deliver, 1 refused, gate failed or attempts exhausted, 2 fetch failed.
186
+ - `sync` moves the main checkout to the mainline, installs when a listed file changed, and follows clean submodule pins. Exit 0 moved or already equal, 1 when local work would be lost, 2 when blocked (undelivered edits) or the fetch failed.
187
+
188
+ ## completion
189
+
190
+ ```sh
191
+ pmcp completion bash > ~/.local/share/bash-completion/completions/pmcp
192
+ pmcp completion zsh > "${fpath[1]}/_pmcp"
193
+ pmcp completion fish > ~/.config/fish/completions/pmcp.fish
194
+ ```
195
+
196
+ Print a completion script for commands and global options to standard output. Exit 0, or 2 for another shell.
197
+
198
+ ## mcp
199
+
200
+ ```sh
201
+ pmcp mcp login remote [--no-wait | --code <callback-or-code>] [--port <port>] [--client-id <id>] [--bearer-env <name>]
202
+ pmcp mcp status remote
203
+ pmcp mcp logout remote
204
+ ```
205
+
206
+ Manage a shared remote MCP session for a server declared with `auth = "pmcp"`. Login prints an authorization URL and accepts a loopback callback or pasted code. Status reports presence, UTC expiry and scopes; tokens are never printed. Bearer credentials can be loaded with `--bearer-env`. Native authentication remains the default. [Shared authentication configuration](project-configuration.md#shared-remote-mcp-authentication).
207
+
208
+ ## doctor
209
+
210
+ ```sh
211
+ pmcp doctor
212
+ pmcp doctor --memory
213
+ ```
214
+
215
+ Inspect native configuration and prerequisites. The optional memory report shows enabled state and paths; it does not read memory contents or synchronize personal memory. [Doctor scope and runtime compatibility](project-configuration.md).
216
+
217
+ ## validate
218
+
219
+ ```sh
220
+ pmcp validate
221
+ ```
222
+
223
+ Validate discovered skill documents and their contracts without starting a native runtime. [Skills reference](skills.md).
224
+
225
+ ## harness
226
+
227
+ ```sh
228
+ pmcp harness doctor inspect
229
+ pmcp harness group inspect --group-file "$GROUP_FILE"
230
+ pmcp harness recovery inspect --group-file "$GROUP_FILE"
231
+ pmcp harness host approve | status | up | down | unit
232
+ pmcp harness mcp
233
+ ```
234
+
235
+ Optional local supervision of owned native main and worker sessions on pmcp-pty. Groups run on Linux (glibc 2.35 or later, with a working user systemd manager) or macOS, with Node.js 22. Start, input, stop and recovery actions are explicit CLI operations. Provider OAuth, trust and approvals remain native; MCP tools cannot invoke this execution path. [Group creation, control and recovery](terminal-harness.md).
236
+
237
+ `harness host` runs the long-running sessions listed in `[host]` of `pmcp.toml`: `approve` records your approval of the projected policy, `status` reports it, `up` starts pmcp-pty and the approved sessions, `down` stops them and `unit` prints a systemd user unit. `up` and `unit` need Linux. `harness mcp` is a stdio MCP server for one pmcp-pty socket (`PMCP_PTY_SOCKET`); its write tools exist only when the approved policy sets `mcp_write`. [The [host] table](project-configuration.md#sessions-pmcp-pty-hosts).
238
+
239
+ ## tui
240
+
241
+ ```sh
242
+ pmcp
243
+ pmcp tui plan
244
+ pmcp tui --runtime codex-cli
245
+ pmcp tui doctor
246
+ ```
247
+
248
+ Open a native main terminal, worker dock and coordination panel with defaults or an optional `[tui]` table in `pmcp.toml`. The first launch confirms the selected runtime; later launches reconnect to this project's owned workspace. The workspace starts read only; taking control and stopping a runtime require explicit actions. Opening requires an interactive terminal and the same host as the harness. [Keys, mailbox observation and cleanup](terminal-workspace.md).
249
+
250
+ ## The written skills
251
+
252
+ Local discovery, configuration and terminal supervision need no PMCP account. Configuration and supervision can change local state; native runtimes retain their own provider login requirements. [Package-specific skills](https://pmcp.build/skills/) are free to read, download and install without PMCP login. Each skill page links the original SKILL.md and a content-only archive that your package manager can install directly. The service commands below also support hosted catalogs with their own access policies.
253
+
254
+ All four take `--project <dir>`, `--api <origin>`, `--json`, and `--catalog <file>`, which reads a saved response so the command runs with no network at all.
255
+
256
+ ## available
257
+
258
+ ```sh
259
+ pmcp available [--project <dir>] [--catalog <file>] [--json]
260
+ ```
261
+
262
+ Which written skills match the dependencies this project already has. It reads your `package.json` to decide what matches and does not upload it. No account needed.
263
+
264
+ ## preview
265
+
266
+ ```sh
267
+ pmcp preview <skill-package> [--json]
268
+ ```
269
+
270
+ A skill's contents and one complete example. The sample is taken from the skill's own bytes rather than described, so it cannot drift from what you would receive. No account needed.
271
+
272
+ ## login · logout · whoami
273
+
274
+ ```sh
275
+ pmcp login [--issuer <url>]
276
+ pmcp logout
277
+ pmcp whoami [--json]
278
+ ```
279
+
280
+ `login` signs this machine in without a browser: it prints a code and a URL to open anywhere. The credential is kept outside the project, so it cannot be committed or copied into an image. `whoami` answers on stdout, so a script can read it. This optional service login is not needed to use the free package skills on pmcp.build.
281
+
282
+ [skills.modoo.today](https://skills.modoo.today) is a separate skill catalog service built on pmcp, with its own accounts and access policies; `pmcp login` and `--provider hosted` reach it. pmcp itself needs no account there.
283
+
284
+ ## install · sync
285
+
286
+ ```sh
287
+ pmcp install <skill-package>... | --all [--dry-run | --yes]
288
+ pmcp sync [--project <dir>] [--dry-run | --yes]
289
+ ```
290
+
291
+ `install` adds skill packages as dev dependencies with your own package manager, and what gets installed is checked against the digest the catalogue published — not its name and version, which any registry can claim. `sync` updates the ones already declared and removes nothing else. pmcp uses the free bundled public catalog by default and verifies immutable archives and installed resources without login. Explicit `--provider hosted` or `--api` selects a separate service's credentialed distribution, such as skills.modoo.today (see [login](#login--logout--whoami)).
292
+
293
+ Both show the project and lockfile changes and stop: `--yes` approves them, `--dry-run` prints the plan and changes nothing.
294
+
295
+ ## Options
296
+
297
+ | Option | Where | Effect |
298
+ | ------------------ | ------------------------- | --------------------------------------------------------------------------------------------- |
299
+ | `--root <dir>` | `serve`, `list`, `index` | a `node_modules` directory to walk; repeatable, and the first one wins on a duplicate package |
300
+ | `--scope <prefix>` | `serve`, `list`, `index` | only packages whose names start with this; repeatable, matched with a plain prefix test |
301
+ | `--model <id>` | `index`, `serve` | the encoder to use; rows from another model are never scored |
302
+ | `--json` | `list`, `index`, `models` | emit JSON on standard output rather than a table or a summary |
303
+ | `--help`, `-h` | anywhere | the help for that command, generated from the command itself |
304
+ | `--version` | on its own | the version, on standard output |
305
+
306
+ Options are parsed against the command's own list, so an unknown flag is an error rather than a silently ignored typo. Giving a non-repeatable option twice, or leaving off a value it needs, is the same error.
307
+
308
+ ## Exit codes
309
+
310
+ | Code | Means | For example |
311
+ | ---- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
312
+ | `0` | it did what you asked | skills listed, or the whole catalog indexed |
313
+ | `1` | it ran and found a problem | no skills under those roots, a partial index, no SQLite in this runtime to store vectors in, a refused or failed `git deliver` |
314
+ | `2` | the arguments were unusable, or a check found drift | an unknown command, an unknown option, a missing value; `project --check` drift, stale or undeclared outputs; a `git` fetch that failed or a sync blocked by undelivered edits |
315
+ | `3` | an optional dependency is missing | `index` without `@huggingface/transformers` |
316
+
317
+ The distinction between 1 and 3 is worth wiring into a script: 1 says the project is not what you expected, and 3 says the machine is missing something optional and the server still works without it.
318
+
319
+ **Data on stdout, everything else on stderr.** The JSON from `--json` and the string from `--version` go to standard output so they can be piped. Tables, help and messages go to standard error, which is what keeps a pipeline's input clean.
320
+
321
+ ## Runtime
322
+
323
+ - Node 22 or later, or Bun 1.3 or later.
324
+ - Runtime dependencies: `@modelcontextprotocol/server`, `zod`, `semver`, `smol-toml` and `yaml`. See [dependency licence notices](https://pmcp.build/licence/).
325
+ - Vector storage uses whichever SQLite the running binary already has. Neither is a dependency; without one, the server still runs and ranking falls back.
@@ -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,56 @@
1
+ # Compatibility
2
+
3
+ [Back to the overview](../README.md)
4
+
5
+ What runs where. Other pages link here instead of repeating requirements. What does not work yet
6
+ is on [Known issues](known-issues.md).
7
+
8
+ ## Platforms
9
+
10
+ | Part | Linux | macOS | Windows |
11
+ | -------------------------------------- | ------------------------------------------------ | -------------------------------- | ------------- |
12
+ | CLI, MCP server, `pmcp project`, hooks | yes | yes | not qualified |
13
+ | `pmcp tui` and harness groups | x64 and arm64, glibc 2.35 or later, user systemd | x64 and arm64, sessions uncapped | not supported |
14
+ | `pmcp harness host up` and `host unit` | user systemd manager required | refused | not supported |
15
+ | pmcp-browser and pmcp-desktop | x64 and arm64, glibc 2.35 or later | not shipped | not shipped |
16
+
17
+ All of them need Node.js 22 or later, or Bun 1.3 or later. npm installs pmcp-pty, pmcp-tui and
18
+ (on Linux) the two plugin binaries through a platform package, `@modootoday/pmcp-<os>-<cpu>`.
19
+ `PMCP_PTY_BIN` and `PMCP_TUI_BIN` point at other builds. On Linux a user systemd manager caps
20
+ each native session's memory; macOS runs sessions without that cap. The macOS binaries are
21
+ unsigned; installed through npm they run as they are, since npm sets no quarantine flag.
22
+
23
+ ## Native runtimes
24
+
25
+ | Runtime | `[targets] tools` | `pmcp tui` and harness id | `[[host.sessions]] runtime` |
26
+ | ----------------- | ----------------- | ------------------------- | --------------------------- |
27
+ | Claude Code | `claude` | `claude-code` | `claude` |
28
+ | Codex | `codex` | `codex-cli` | `codex` |
29
+ | Gemini CLI | `gemini` | `gemini-cli` | `gemini` |
30
+ | Grok Build | `grok` | `grok-cli` | `grok` |
31
+ | Antigravity (agy) | `antigravity` | `antigravity` | `agy` |
32
+ | OpenCode | `opencode` | not available | `opencode` |
33
+
34
+ Which hook features each runtime supports, as measured, is in
35
+ [Runtime support](hooks.md#runtime-support). Provider login, folder trust and
36
+ tool approvals stay in each runtime; pmcp never answers login, auth, trust or hook-review
37
+ prompts.
38
+
39
+ ## Installation and packaging
40
+
41
+ | Surface | Current qualification |
42
+ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
43
+ | 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 |
44
+ | 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 |
45
+ | Public skill installation | npm, Bun and pnpm 10.17.1; confirmation required, scripts disabled |
46
+ | Native plugin export | Claude, Codex, Gemini, Grok and agy formats; export does not install or activate a vendor plugin |
47
+ | pnpm workspace installation | Selects the member, preserves root dependencies and updates the shared lockfile |
48
+ | Yarn skill installation | Refused without changing project files; Yarn PnP is not supported |
49
+ | 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 |
50
+ | 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 |
51
+
52
+ Provider authentication, native children and vendor behavior have separate
53
+ qualification scopes. An installed executable or exported manifest is not proof
54
+ that every native feature works. The packed-package check, run before a
55
+ release, covers actual archive installation, CLI startup, MCP and SQLite; isolated projects
56
+ on a host are distinct from Docker and OS qualification.