@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.
- package/.agents/plugins/marketplace.json +1 -1
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +2 -2
- package/.mcp.json +1 -1
- package/CHANGELOG.md +152 -0
- package/CONTRIBUTING.md +71 -0
- package/README.md +98 -201
- package/SECURITY.md +17 -1
- package/dist/apply-JUTGS5WZ.js +242 -0
- package/dist/{attachment-tU5FZrgZ.d.ts → attachment-D84OGI6n.d.ts} +1 -1
- package/dist/available-DBSIVVJ6.js +73 -0
- package/dist/broadcast-CBMVOV3G.js +18 -0
- package/dist/chunk-26WLNWDG.js +93 -0
- package/dist/chunk-2FIV63WC.js +252 -0
- package/dist/chunk-2P4Z2NUX.js +28 -0
- package/dist/chunk-34DECPVC.js +22 -0
- package/dist/chunk-3FCFAQDG.js +42 -0
- package/dist/chunk-3IDXEV5E.js +1934 -0
- package/dist/chunk-3PW4FI7U.js +32 -0
- package/dist/chunk-3Y3HDMHA.js +108 -0
- package/dist/chunk-47O3X4VS.js +113 -0
- package/dist/chunk-4NDEP7HU.js +26 -0
- package/dist/chunk-5OMOPUE6.js +39 -0
- package/dist/chunk-5QQWS4US.js +53 -0
- package/dist/chunk-5ZABTVSW.js +48 -0
- package/dist/chunk-65KAQSJP.js +7 -0
- package/dist/chunk-6STKGOCW.js +27 -0
- package/dist/chunk-6WXMJOMI.js +9 -0
- package/dist/chunk-73AKO4UL.js +24 -0
- package/dist/chunk-7DLZC73N.js +29 -0
- package/dist/chunk-7GBYECSK.js +72 -0
- package/dist/chunk-7HFIGCSL.js +419 -0
- package/dist/chunk-7TD53M7L.js +13 -0
- package/dist/chunk-7UCZAN4J.js +778 -0
- package/dist/chunk-A4PKLESO.js +112 -0
- package/dist/chunk-A7VF7A35.js +1025 -0
- package/dist/chunk-ABTJQ4QV.js +74 -0
- package/dist/chunk-AJ4VXM2U.js +349 -0
- package/dist/chunk-BBTBJCFA.js +380 -0
- package/dist/chunk-BU65MNVU.js +13 -0
- package/dist/chunk-C4NHQGHL.js +142 -0
- package/dist/chunk-CJTKR6K6.js +1213 -0
- package/dist/chunk-D77IRGHO.js +1246 -0
- package/dist/chunk-DCU2EXQV.js +78 -0
- package/dist/chunk-DMZHQZ7P.js +104 -0
- package/dist/chunk-DZ2MRTYT.js +135 -0
- package/dist/chunk-E2YOZ2FF.js +207 -0
- package/dist/chunk-E3DQB5LS.js +48 -0
- package/dist/chunk-EATCUWGG.js +66 -0
- package/dist/chunk-EAWPJHJ7.js +155 -0
- package/dist/chunk-EIDIVIAD.js +33 -0
- package/dist/chunk-F5QYZK7E.js +396 -0
- package/dist/chunk-F5XMGOOX.js +28 -0
- package/dist/chunk-FENOGX3U.js +31 -0
- package/dist/chunk-GZHHEHKY.js +44 -0
- package/dist/chunk-HDMBVLCZ.js +53 -0
- package/dist/chunk-HQOB7OQS.js +81 -0
- package/dist/chunk-I2ZP2PSA.js +211 -0
- package/dist/chunk-IG33DXLT.js +151 -0
- package/dist/chunk-IJBSOWHK.js +86 -0
- package/dist/chunk-INT7QLEU.js +114 -0
- package/dist/chunk-J7UYNJCR.js +9 -0
- package/dist/chunk-JEL35P7S.js +53 -0
- package/dist/chunk-JGJ4INEN.js +32 -0
- package/dist/chunk-JS5RTH4I.js +84 -0
- package/dist/chunk-JWRZDYB5.js +59 -0
- package/dist/chunk-KMXRRSKT.js +660 -0
- package/dist/chunk-LBXO4VPG.js +73 -0
- package/dist/chunk-LLBPVZXM.js +67 -0
- package/dist/chunk-LLT5FQBE.js +57 -0
- package/dist/chunk-LMT3PPXJ.js +17 -0
- package/dist/chunk-LMUBBIE2.js +83 -0
- package/dist/chunk-LTZH5E3G.js +479 -0
- package/dist/chunk-LW4TG7EL.js +39 -0
- package/dist/chunk-MPSQXSC6.js +346 -0
- package/dist/chunk-MVFH26QT.js +97 -0
- package/dist/chunk-NLEXKE7U.js +67 -0
- package/dist/chunk-NQPURJT5.js +44 -0
- package/dist/chunk-NRBQK6UX.js +105 -0
- package/dist/chunk-OEH47H6A.js +48 -0
- package/dist/chunk-OG7QR2DP.js +75 -0
- package/dist/chunk-OPYFEHKG.js +52 -0
- package/dist/chunk-P4N7DBD5.js +83 -0
- package/dist/chunk-PAX3QXX2.js +140 -0
- package/dist/chunk-PKODFR5F.js +102 -0
- package/dist/chunk-PMJG2CXF.js +122 -0
- package/dist/chunk-Q5H3L6Y4.js +23 -0
- package/dist/chunk-QEF7EK3T.js +28 -0
- package/dist/chunk-QEW4J3IZ.js +74 -0
- package/dist/chunk-QPL7E2HW.js +464 -0
- package/dist/chunk-R2GPCZUX.js +22 -0
- package/dist/chunk-R5MT42JS.js +284 -0
- package/dist/chunk-RMATE45Z.js +197 -0
- package/dist/chunk-RPQOBHVU.js +87 -0
- package/dist/chunk-S3PIAMXV.js +230 -0
- package/dist/chunk-T3LKX23M.js +168 -0
- package/dist/chunk-T6GOWHK6.js +30 -0
- package/dist/chunk-TIA4SPU2.js +10 -0
- package/dist/chunk-TNCZ6444.js +57 -0
- package/dist/chunk-TVL5RTE6.js +269 -0
- package/dist/chunk-TXQ7L33K.js +45 -0
- package/dist/chunk-UPQTAHUK.js +189 -0
- package/dist/chunk-V4NPDK6X.js +14 -0
- package/dist/chunk-VJFEN6DJ.js +38 -0
- package/dist/chunk-VMHUEOT5.js +643 -0
- package/dist/chunk-VRPMYPZU.js +4985 -0
- package/dist/chunk-WIW772I3.js +25 -0
- package/dist/chunk-XELAZAIM.js +136 -0
- package/dist/chunk-XNML2KIC.js +23 -0
- package/dist/chunk-XP2U3LO3.js +30 -0
- package/dist/chunk-YGOWIJPE.js +51 -0
- package/dist/chunk-YIXDHQYE.js +11 -0
- package/dist/chunk-YSAWTGNA.js +117 -0
- package/dist/claude-U2JC2DNQ.js +77 -0
- package/dist/cli-MI4ZCAZ3.js +41 -0
- package/dist/cli-ZN7ZVDEZ.js +46 -0
- package/dist/cli.js +144 -16197
- package/dist/completion-ILSRB3LW.js +142 -0
- package/dist/config-DnpLL2kT.d.ts +46 -0
- package/dist/{service-qpCsOXkQ.d.ts → core-C1LPjxK6.d.ts} +2 -6
- package/dist/diagnostics-XKXVVQWH.js +93 -0
- package/dist/doctor-O2E63YGO.js +538 -0
- package/dist/entry-X6CSYQRQ.js +305 -0
- package/dist/exec-mcp-2PMWBPD7.js +365 -0
- package/dist/harness-L2KSI2ZB.js +177 -0
- package/dist/harness-egress-bridge.js +4 -4
- package/dist/harness-launch-gate.js +47 -940
- package/dist/harness-pane-runner.js +13 -80
- package/dist/harness-worker.js +21 -2703
- package/dist/hook-body.js +5222 -0
- package/dist/hook-spec-C5fWTSCH.d.ts +100 -0
- package/dist/hook.js +26 -0
- package/dist/hooks-BHTA44X7.js +21 -0
- package/dist/host-UIZAXXQH.js +22 -0
- package/dist/host-UWK754BW.js +210 -0
- package/dist/host-run-BI2OTZDZ.js +307 -0
- package/dist/http.d.ts +5 -42
- package/dist/http.js +21 -2234
- package/dist/import-mcp-GPKJI7DI.js +400 -0
- package/dist/index.d.ts +146 -168
- package/dist/index.js +133 -4948
- package/dist/init-3C2Y7BNJ.js +14 -0
- package/dist/install-GG7HHZK2.js +796 -0
- package/dist/invoke-44CJRVMK.js +23 -0
- package/dist/list-MCP2FXUF.js +68 -0
- package/dist/list-WL6L4J5H.js +65 -0
- package/dist/load-BEUBABtB.d.ts +21 -0
- package/dist/logout-F5EJ5MOU.js +44 -0
- package/dist/logs-TBUA4UWU.js +107 -0
- package/dist/mailbox/index.d.ts +10 -5
- package/dist/mailbox/index.js +53 -1572
- package/dist/mailbox-BMTZOSZ7.js +285 -0
- package/dist/mailbox-GDJ7BWQN.js +189 -0
- package/dist/mainline-KAD2ERLP.js +639 -0
- package/dist/marketplace-G4VQET5W.js +191 -0
- package/dist/mcp-235QZN2A.js +15 -0
- package/dist/mcp-FJ2UQ4RH.js +193 -0
- package/dist/models-ISU4DCMA.js +32 -0
- package/dist/opencode-CN7JLQYO.js +60 -0
- package/dist/pause-7LILUVGL.js +18 -0
- package/dist/preview-DT7DWG5F.js +91 -0
- package/dist/project/hook-adapter.d.ts +5 -2
- package/dist/project/hook-adapter.js +41 -27
- package/dist/project-5YV5CUEG.js +70 -0
- package/dist/pty-XTJ4MIWK.js +94 -0
- package/dist/recovery-U6QB3PMT.js +100 -0
- package/dist/reindex-Y27QJFDB.js +22 -0
- package/dist/resume-26VFAAMH.js +18 -0
- package/dist/run-3AXTZSR7.js +126 -0
- package/dist/run-3SOVRQIA.js +19 -0
- package/dist/serve-DQMKTFIV.js +104 -0
- package/dist/session-XM2CR425.js +159 -0
- package/dist/setup-DTKZLZUT.js +18 -0
- package/dist/start-login-YTZV6KMF.js +416 -0
- package/dist/status-A2OUTNGK.js +9 -0
- package/dist/status-H2VAHIDV.js +10 -0
- package/dist/status-MROQ7WR7.js +43 -0
- package/dist/status-RO55QPKV.js +55 -0
- package/dist/status-UME2L33L.js +286 -0
- package/dist/stdio.d.ts +3 -13
- package/dist/stdio.js +16 -3186
- package/dist/sweep-35LGQTTO.js +18 -0
- package/dist/test-AGZOJLRZ.js +561 -0
- package/dist/tools-gpHNq9Dh.d.ts +328 -0
- package/dist/tui-G5LLWCSV.js +153 -0
- package/dist/unbroadcast-5QNGAJR2.js +18 -0
- package/dist/validate-IU52H2IC.js +46 -0
- package/dist/worker-QZ5T6LJD.js +80 -0
- package/dist/worktree-create-PZSRB7PH.js +89 -0
- package/dist/worktree-list-JYB6VXLW.js +51 -0
- package/dist/worktree-sync-UF5CXPWV.js +30 -0
- package/docs/authoring.md +82 -0
- package/docs/browser-and-desktop.md +46 -0
- package/docs/commands.md +325 -0
- package/docs/compare.md +35 -0
- package/docs/compatibility.md +55 -0
- package/docs/embeddings.md +1 -1
- package/docs/getting-started.md +105 -0
- package/docs/git-workflow.md +60 -0
- package/docs/glossary.md +31 -0
- package/docs/hooks/capabilities/antigravity.json +199 -0
- package/docs/hooks/capabilities/claude.json +179 -0
- package/docs/hooks/capabilities/codex.json +179 -0
- package/docs/hooks/capabilities/gemini.json +196 -0
- package/docs/hooks/capabilities/grok.json +192 -0
- package/docs/hooks/capabilities/opencode.json +184 -0
- package/docs/hooks.md +264 -0
- package/docs/install.md +72 -0
- package/docs/library-skills.md +132 -0
- package/docs/mailbox.md +16 -5
- package/docs/project-configuration.md +540 -58
- package/docs/sessions.md +64 -0
- package/docs/skills.md +4 -45
- package/docs/terminal-harness.md +92 -44
- package/docs/terminal-workspace.md +81 -169
- package/gemini-extension.json +2 -2
- package/mcp.json +1 -1
- package/package.json +16 -2
- package/plugin.json +2 -2
- package/plugins/pmcp/.claude-plugin/plugin.json +4 -2
- package/plugins/pmcp/.mcp.json +1 -1
- package/plugins/pmcp/gemini-extension.json +2 -2
- package/plugins/pmcp/mcp.json +1 -1
- package/plugins/pmcp/mod/commands.ts +72 -0
- package/plugins/pmcp/mod/contract.d.ts +39 -0
- package/plugins/pmcp/mod/draw.tsx +216 -0
- package/plugins/pmcp/mod/guard.ts +42 -0
- package/plugins/pmcp/mod/hooks.json +4 -0
- package/plugins/pmcp/mod/host.ts +46 -0
- package/plugins/pmcp/mod/model.ts +144 -0
- package/plugins/pmcp/mod/reader/index.ts +18 -0
- package/plugins/pmcp/mod/reader/read.ts +76 -0
- package/plugins/pmcp/mod/reader/settings.ts +54 -0
- package/plugins/pmcp/mod/reader/types.ts +38 -0
- package/plugins/pmcp/mod/register.tsx +73 -0
- package/plugins/pmcp/mod/sessions/format.ts +91 -0
- package/plugins/pmcp/mod/sessions/types.ts +162 -0
- package/plugins/pmcp/mod/snapshot.ts +75 -0
- package/plugins/pmcp/mod/spinner.tsx +30 -0
- package/plugins/pmcp/mod/state.ts +28 -0
- package/plugins/pmcp/plugin.json +2 -2
- package/plugins/pmcp/skills/agent-assets-migrate/SKILL.md +96 -0
- package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +101 -0
- package/plugins/pmcp/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
- package/plugins/pmcp/skills/package-skill-catalog/SKILL.md +51 -15
- package/plugins/pmcp/skills/pmcp-browser/SKILL.md +27 -0
- package/plugins/pmcp/skills/pmcp-desktop/SKILL.md +25 -0
- package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +153 -0
- package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +96 -0
- package/plugins/pmcp/skills/skill-package-scaffold/SKILL.md +89 -0
- package/schema/catalog-v1.json +187 -0
- package/schema/library.json +196 -0
- package/schema/marketplace-manifest.json +144 -0
- package/schema/plugin-manifest.json +59 -0
- package/schema/skill-frontmatter.json +170 -0
- package/schema/skill-metadata-core.json +131 -0
- package/skills/agent-assets-migrate/SKILL.md +96 -0
- package/skills/headless-agents-ci-scaffold/SKILL.md +101 -0
- package/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
- package/skills/package-skill-catalog/SKILL.md +51 -15
- package/skills/pmcp-browser/SKILL.md +27 -0
- package/skills/pmcp-desktop/SKILL.md +25 -0
- package/skills/pmcp-project-init/SKILL.md +153 -0
- package/skills/pmcp-sessions-and-git/SKILL.md +96 -0
- package/skills/skill-package-scaffold/SKILL.md +89 -0
- package/dist/config-BkSpjUG6.d.ts +0 -50
- package/dist/embed-DRROSD3F.d.ts +0 -53
- package/dist/hook-spec-CSJJySsH.d.ts +0 -11
- package/dist/server-VWSY3Shw.d.ts +0 -543
- package/dist/tui-worker.js +0 -6549
- package/docs/manual-library-skills.md +0 -74
- /package/dist/{tui-worker.d.ts → hook.d.ts} +0 -0
|
@@ -1,7 +1,11 @@
|
|
|
1
|
-
#
|
|
1
|
+
# pmcp.toml reference
|
|
2
2
|
|
|
3
3
|
[Back to the overview](../README.md)
|
|
4
4
|
|
|
5
|
+
Every table `pmcp.toml` accepts, with its keys and defaults. Task guides cover the larger
|
|
6
|
+
parts: [Hooks](hooks.md), [Run several agents](sessions.md), [Git workflow](git-workflow.md),
|
|
7
|
+
[Browser and desktop](browser-and-desktop.md) and [Library skills](library-skills.md).
|
|
8
|
+
|
|
5
9
|
## Project config
|
|
6
10
|
|
|
7
11
|
A `pmcp.toml` at or above the working directory sets the catalog once, so a
|
|
@@ -16,8 +20,80 @@ marketplaces = ["vendor/marketplace"]
|
|
|
16
20
|
|
|
17
21
|
Paths resolve against the file's directory. Keys are `roots`, `scopes`,
|
|
18
22
|
`workspaces`, `packages` and `marketplaces`, each a list mirroring the flag of
|
|
19
|
-
the same meaning
|
|
23
|
+
the same meaning, and `builtin` (boolean, default on) for the bundled free
|
|
24
|
+
marketplace; an unknown key is an error. A flag replaces the file's list
|
|
20
25
|
of its kind. `--config <file>` names another file and `--no-config` ignores it.
|
|
26
|
+
The nearest `pmcp.toml` is found by walking up from the working directory,
|
|
27
|
+
stopping at the directory that holds `.git`.
|
|
28
|
+
|
|
29
|
+
`[catalog.validation]` makes `pmcp validate` stricter than the Agent Skills
|
|
30
|
+
specification. Without it, only the specification is checked.
|
|
31
|
+
|
|
32
|
+
```toml
|
|
33
|
+
[catalog.validation]
|
|
34
|
+
profile = "catalog-v1" # or "library"
|
|
35
|
+
deny_list = "private-terms.txt"
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
| Key | Type | Default | Meaning |
|
|
39
|
+
| ----------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
40
|
+
| `profile` | string | none | `catalog-v1`: the marketplace catalog rules (metadata, tier, trigger wording, ASCII in the open tier, locales); the marketplace's tier applies, else the skill's own `metadata.tier`, else `open`. `library`: the manual library skill metadata schema. |
|
|
41
|
+
| `deny_list` | path | none | A file of terms, one per line (`#` starts a comment), that no file of a skill may contain, compared without case. Relative to `pmcp.toml`. A finding names the list line, never the term. A missing file is an error. |
|
|
42
|
+
|
|
43
|
+
Both apply to named skill directories and, with no directory named, to every
|
|
44
|
+
skill the catalog reaches.
|
|
45
|
+
|
|
46
|
+
## Table index
|
|
47
|
+
|
|
48
|
+
Every table pmcp reads, and where it is described. An unknown key inside one
|
|
49
|
+
of these tables is an error unless noted; an unknown top-level table is
|
|
50
|
+
ignored.
|
|
51
|
+
|
|
52
|
+
| Table | Section |
|
|
53
|
+
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
|
|
54
|
+
| `[catalog]`, `[catalog.validation]` | [Project config](#project-config) |
|
|
55
|
+
| `[embedding]`, `[embedding.encoder]` | [Embedding models](embeddings.md) |
|
|
56
|
+
| `[marketplaces.<name>]` | [Marketplaces](#marketplaces) |
|
|
57
|
+
| `[targets]`, `[skills.<name>]`, `[agents.<name>.<tool>]`, `[rules.packages]` | [Native files for each agent tool](#native-files-for-each-agent-tool) |
|
|
58
|
+
| `[mcp.<alias>]` | [Unified project MCP configuration](#unified-project-mcp-configuration) |
|
|
59
|
+
| `[hooks]`, `[hooks.guards.*]`, `[[hooks.guards.custom]]`, `[hooks.checks.*]` | [Hooks](hooks.md) |
|
|
60
|
+
| `[[hooks.shell]]`, `[[hooks.edit]]` | [Deprecated shell guards](hooks.md#deprecated-shell-guards) |
|
|
61
|
+
| `[sessions]`, `[sessions.registry]`, `[sessions.pause]`, `[sessions.broadcast]`, `[sessions.mailbox]`, `[sessions.leases.<name>]`, `[sessions.roles.<name>]` | [Sessions](#sessions) |
|
|
62
|
+
| `[git]`, `[git.shared_checkout]`, `[git.worktrees]`, `[git.worktrees.sync]`, `[git.mainline]`, `[git.mainline.gate]`, `[git.mainline.deliver]`, `[git.mainline.sync]`, `[git.submodules]` | [Git workflow](git-workflow.md) |
|
|
63
|
+
| `[logging]`, `[logging.components]` | [Logging](#logging) |
|
|
64
|
+
| `[permissions.claude]` | [Claude permission rules](#claude-permission-rules) |
|
|
65
|
+
| `[ui.claude]` | [Claude session panes](#claude-session-panes) |
|
|
66
|
+
| `[tui]`, `[mailbox]` | [Terminal workspace](terminal-workspace.md) |
|
|
67
|
+
| `[host]`, `[[host.sessions]]`, `[[host.answers]]`, `[host.browser]`, `[host.desktop]`, `[[host.desktop.launch]]` | [Sessions pmcp-pty hosts](#sessions-pmcp-pty-hosts) |
|
|
68
|
+
|
|
69
|
+
## Marketplaces
|
|
70
|
+
|
|
71
|
+
`[marketplaces.<name>]` declares a plugin marketplace once for catalog search
|
|
72
|
+
and for each agent tool:
|
|
73
|
+
|
|
74
|
+
```toml
|
|
75
|
+
[marketplaces.team]
|
|
76
|
+
source = { path = "packages/marketplace" } # or { github = "owner/repo", ref = "main" } or { builtin = true }
|
|
77
|
+
catalog = true # searchable, like [catalog] marketplaces
|
|
78
|
+
[marketplaces.team.plugins]
|
|
79
|
+
review = { targets = ["claude", "codex"] }
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`pmcp project` writes `extraKnownMarketplaces` and `enabledPlugins` in
|
|
83
|
+
`.claude/settings.json`, and `[marketplaces.<name>]` and
|
|
84
|
+
`[plugins."<plugin>@<name>"]` in the pmcp block of `.codex/config.toml`. Local
|
|
85
|
+
sources are written as absolute paths. Codex reads the project file only in a
|
|
86
|
+
trusted project and installs plugins into user state, so `pmcp doctor` prints
|
|
87
|
+
`codex plugin add <plugin>@<name>` for each declared plugin Codex has not
|
|
88
|
+
installed and reports enabled plugins the file does not declare.
|
|
89
|
+
`[catalog] marketplaces` remains an alias.
|
|
90
|
+
|
|
91
|
+
A marketplace name and each plugin name match `^[a-z0-9][a-z0-9-]*$`. `source`
|
|
92
|
+
is required and holds exactly one of `path` (resolved against the toml
|
|
93
|
+
directory), `github` (`owner/repo`, with an optional `ref`) or `builtin = true`.
|
|
94
|
+
`catalog = true` needs a path or builtin source. Each plugin's `targets` is
|
|
95
|
+
required and lists `claude` and/or `codex`. Without the table no marketplace is
|
|
96
|
+
declared.
|
|
21
97
|
|
|
22
98
|
## Native files for each agent tool
|
|
23
99
|
|
|
@@ -34,10 +110,10 @@ described in [OpenCode project support](#opencode-project-support).
|
|
|
34
110
|
tools = ["claude", "codex", "gemini", "grok", "antigravity"]
|
|
35
111
|
|
|
36
112
|
[skills.deploy]
|
|
37
|
-
invocation = "user"
|
|
113
|
+
invocation = "user" # the person starts it; the model is not offered it
|
|
38
114
|
|
|
39
115
|
[agents.reviewer.claude]
|
|
40
|
-
tools = "Read, Grep"
|
|
116
|
+
tools = "Read, Grep" # fields one tool reads stay out of agent.md
|
|
41
117
|
|
|
42
118
|
[rules]
|
|
43
119
|
root = "AGENTS.md"
|
|
@@ -55,6 +131,13 @@ pmcp project remove <name>
|
|
|
55
131
|
pmcp doctor # ask each installed tool what it loads
|
|
56
132
|
```
|
|
57
133
|
|
|
134
|
+
| Table | Keys |
|
|
135
|
+
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
136
|
+
| `[targets]` | `tools`: list of `claude`, `codex`, `gemini`, `grok`, `antigravity`, `opencode`. Missing means nothing is projected. |
|
|
137
|
+
| `[skills.<name>]` | `invocation`: `"any"` (default) or `"user"`. |
|
|
138
|
+
| `[agents.<name>.<tool>]` | Any keys, merged over the agent's frontmatter; Claude keeps `name`, `description`, `tools`, `model`, `effort`, Gemini keeps `name`, `description`. |
|
|
139
|
+
| `[rules.packages]` | `file` (required): the file name each package keeps its rules in; every tracked `<package>/<file>` is linked as `.claude/rules/<dir>/<name>.md`. `dir` (default `"pkg"`, not `"pmcp"`). `strip` (default `[]`): leading path segments dropped when deriving `<name>`. Written only for Claude. |
|
|
140
|
+
|
|
58
141
|
Rules go to `.claude/rules/<dir>/`, never the top level, because Grok Build
|
|
59
142
|
loads top-level `.claude/rules/*.md` in every session regardless of `paths:`.
|
|
60
143
|
A server that names `${PROJECT_ROOT}` is launched through `sh`, which finds
|
|
@@ -64,14 +147,130 @@ overwritten. `doctor` calls no model: it reads `claude mcp list`,
|
|
|
64
147
|
`codex mcp list`, `gemini skills list`, `gemini mcp list` and
|
|
65
148
|
`grok inspect --json`, and skips a tool that is not installed.
|
|
66
149
|
|
|
67
|
-
##
|
|
150
|
+
## Sessions pmcp-pty hosts
|
|
68
151
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
152
|
+
`[host]` names the sessions pmcp-pty runs for this project and the few dialog
|
|
153
|
+
answers you allow it to give. `pmcp project` writes them to
|
|
154
|
+
`.agents/pmcp-pty/host.json` (the sessions) and `.agents/pmcp-pty/policy.json`
|
|
155
|
+
(answers, `mcp_write`, roots), pinned in `pmcp.lock` like every output, and
|
|
156
|
+
`pmcp doctor` reports whether they match. pmcp.toml is writable by agents, so
|
|
157
|
+
neither file takes effect by being projected: pmcp-pty loads only a copy you
|
|
158
|
+
approved. Running the host (`pmcp harness host up`) needs Linux with a
|
|
159
|
+
user systemd manager; on macOS it refuses, and `pmcp tui` or a harness group is
|
|
160
|
+
the way to run sessions there.
|
|
161
|
+
|
|
162
|
+
```toml
|
|
163
|
+
[host]
|
|
164
|
+
roots = ["."] # every session cwd must be under one of these
|
|
165
|
+
mcp_write = false # pty_turn and pty_lease over pmcp harness mcp
|
|
166
|
+
|
|
167
|
+
[[host.sessions]]
|
|
168
|
+
name = "lead" # lowercase, digits and -; unique
|
|
169
|
+
runtime = "claude" # claude, codex, gemini, agy, grok or opencode
|
|
170
|
+
cwd = "." # inside the project
|
|
171
|
+
argv = ["claude"] # default: the runtime's name
|
|
172
|
+
labels = { task = "review" }
|
|
173
|
+
restart = "on-exit" # or "no" (default); max_restarts defaults to 3
|
|
174
|
+
|
|
175
|
+
[[host.answers]]
|
|
176
|
+
runtime = "gemini"
|
|
177
|
+
dialog = "tool-approval" # the dialog name pmcp-pty's profile reports
|
|
178
|
+
options = ["Allow once"] # option keys or labels
|
|
179
|
+
|
|
180
|
+
[host.browser]
|
|
181
|
+
allow_private = ["localhost:5173"] # host:port or host:*; pmcp-browser is public-only without it
|
|
182
|
+
|
|
183
|
+
[[host.desktop.launch]]
|
|
184
|
+
name = "terminal" # what pmcp-desktop's launch tool takes
|
|
185
|
+
argv = ["xterm"] # never a browser
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
Login and authentication (`auth-*`), folder and workspace trust and hook
|
|
189
|
+
review dialogs are never answered: a `[[host.answers]]` entry naming one is a
|
|
190
|
+
configuration error, and pmcp-pty refuses them whatever a policy says. Paths
|
|
191
|
+
stay project-relative, so the projected files hold no host path.
|
|
192
|
+
`[host.browser]` and `[[host.desktop.launch]]` widen
|
|
193
|
+
[pmcp-browser and pmcp-desktop](browser-and-desktop.md) and act only
|
|
194
|
+
from the approved copy too; a launch entry that starts a browser is an error.
|
|
195
|
+
|
|
196
|
+
### Approving the host policy
|
|
197
|
+
|
|
198
|
+
Run `pmcp harness host approve` in your own terminal after `pmcp project`. It
|
|
199
|
+
prints the sessions, the answer rules, `mcp_write` and one sha256 over both
|
|
200
|
+
projected files, and approves only when you type the first 8 hex digits of
|
|
201
|
+
that hash. The approved copy goes to
|
|
202
|
+
`$XDG_STATE_HOME/pmcp/host-approvals/<project id>/` (directory 0700, files
|
|
203
|
+
0600; the `[sessions] state_dir` override does not apply), and
|
|
204
|
+
`pmcp-pty daemon --host <that directory>` loads only that copy, after checking
|
|
205
|
+
it still matches its own approval. A later projection that differs is
|
|
206
|
+
reported by `pmcp doctor` and `pmcp harness host status`, and the approved
|
|
207
|
+
copy stays in force until you approve again.
|
|
208
|
+
|
|
209
|
+
`approve` refuses without an interactive terminal, when `PMCP_PTY_*` or a
|
|
210
|
+
coding agent's session variables are set, and when an ancestor process is a
|
|
211
|
+
coding agent or pmcp-pty. With `[host]` declared, the `shell.host_approval`
|
|
212
|
+
guard (deny by default; set `[hooks.guards.shell] host_approval` to change it)
|
|
213
|
+
blocks agents' commands that run `host approve` or touch the approvals
|
|
214
|
+
directory, and their edits there.
|
|
215
|
+
|
|
216
|
+
These checks run as your own user, like the agents themselves. They stop an
|
|
217
|
+
accident and an agent that was told to approve; they are not a security
|
|
218
|
+
boundary, since any process running as you can write the approvals directory
|
|
219
|
+
directly. A real boundary needs the approvals stored under a different user or
|
|
220
|
+
owned by root.
|
|
221
|
+
|
|
222
|
+
## Browser and desktop for agents
|
|
223
|
+
|
|
224
|
+
pmcp-browser and pmcp-desktop, and how to declare them: [Browser and desktop](browser-and-desktop.md).
|
|
225
|
+
|
|
226
|
+
## Claude permission rules
|
|
227
|
+
|
|
228
|
+
`[permissions.claude]` declares Claude Code permission rules. `pmcp project`
|
|
229
|
+
adds them to `permissions.allow`, `permissions.ask` and `permissions.deny` in
|
|
230
|
+
`.claude/settings.json` when `claude` is in `[targets] tools`:
|
|
231
|
+
|
|
232
|
+
```toml
|
|
233
|
+
[permissions.claude]
|
|
234
|
+
ask = ["Read(.env)", "Read(**/*.bak.*)", "Bash(git push:*)", "Bash(git stash:*)"]
|
|
235
|
+
deny = ["WebFetch(domain:internal.example)"]
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
| Table | Keys |
|
|
239
|
+
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
240
|
+
| `[permissions.claude]` | `allow`, `ask`, `deny`: lists of native Claude rules, kept verbatim. Repeats within a list are dropped; one rule in two lists is an error. No other key. |
|
|
241
|
+
|
|
242
|
+
Each rule is a Claude permission expression: a tool name (`Bash`, `Read`,
|
|
243
|
+
`Edit`, `Write`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, `Agent`, `Task`,
|
|
244
|
+
`Skill` and the other built-in tools), optionally followed by a specifier in
|
|
245
|
+
parentheses, or an MCP name such as `mcp__docs` or `mcp__docs__search`.
|
|
246
|
+
`WebFetch` takes `domain:<host>`; a `Bash` prefix `:*` must end the specifier.
|
|
247
|
+
pmcp checks only this structure. It never expands globs or rewrites paths, so
|
|
248
|
+
`Read(.env)` stays `Read(.env)`.
|
|
249
|
+
|
|
250
|
+
pmcp owns only the entries it inserted, and records them in `pmcp.lock`. A rule
|
|
251
|
+
that was already in the list is borrowed: it satisfies the declaration but
|
|
252
|
+
stays unmanaged and survives when the declaration goes. Entries pmcp did not
|
|
253
|
+
write are never removed or reordered, and `defaultMode` and every other
|
|
254
|
+
setting are left alone. A missing table declares nothing; an empty list, a
|
|
255
|
+
removed list or a removed table removes the entries pmcp owns in that list.
|
|
256
|
+
|
|
257
|
+
`pmcp project --check` reports `drift` for a declared rule that is missing and
|
|
258
|
+
for an owned rule that is no longer declared. It reports `conflict` when an
|
|
259
|
+
owned entry was edited or removed by hand, or when the list is not a list of
|
|
260
|
+
strings; `pmcp project` then refuses to write until the native file is
|
|
261
|
+
reviewed. `pmcp doctor` shows how many entries each list owns and borrows, or
|
|
262
|
+
`none declared`.
|
|
263
|
+
|
|
264
|
+
A declared rule that also sits unmanaged in another list, for example a hand
|
|
265
|
+
written `deny` for a rule declared in `ask`, is an `overlap`. Claude's own
|
|
266
|
+
precedence decides it, so `--check` and `doctor` show it as a warning and
|
|
267
|
+
nothing is removed or refused. `pmcp project` also refuses to write when
|
|
268
|
+
`.claude/settings.json` changed while it was planning; run it again.
|
|
269
|
+
|
|
270
|
+
Codex is never written: its native command rules are a separate feature, and
|
|
271
|
+
the hook guards stay its enforcement.
|
|
272
|
+
|
|
273
|
+
## Unified project MCP configuration
|
|
75
274
|
|
|
76
275
|
Declare each MCP server once in pmcp.toml. The projector writes the native
|
|
77
276
|
project files for all selected runtimes. A server can narrow its targets:
|
|
@@ -101,7 +300,8 @@ timeout = 120000
|
|
|
101
300
|
url means Streamable HTTP; Gemini receives httpUrl. Legacy SSE is not imported
|
|
102
301
|
as HTTP. headers contains literal nonsecret headers, header_env maps header
|
|
103
302
|
names to environment variable names, and bearer_token_env_var references a
|
|
104
|
-
token without writing its value.
|
|
303
|
+
token without writing its value. With auth = "native" (the default), each runtime
|
|
304
|
+
retains its own OAuth session.
|
|
105
305
|
Antigravity HTTP header projection is not qualified and is rejected; explicitly
|
|
106
306
|
limit those servers to supported targets. tools maps to Gemini includeTools and
|
|
107
307
|
Codex enabled_tools; it is not a cross-runtime security boundary. Native timeout
|
|
@@ -149,6 +349,15 @@ Configuration references: [Codex](https://developers.openai.com/codex/config-ref
|
|
|
149
349
|
[Gemini CLI](https://geminicli.com/docs/tools/mcp-server/),
|
|
150
350
|
and [Grok Build](https://docs.x.ai/build/features/mcp-servers).
|
|
151
351
|
|
|
352
|
+
### Antigravity
|
|
353
|
+
|
|
354
|
+
Antigravity receives a native project plugin at `.agents/plugins/pmcp-mcp` with
|
|
355
|
+
`plugin.json` and `mcp_config.json`. Projection removes only lock-owned entries
|
|
356
|
+
from the earlier `.agents/mcp_config.json` artifact and backs up both layouts.
|
|
357
|
+
Antigravity's global mcp list does not enumerate project plugin servers;
|
|
358
|
+
validate the generated plugin with `agy plugin validate`.
|
|
359
|
+
Its HTTP entries use `serverUrl`, accepted by the installed plugin validator.
|
|
360
|
+
|
|
152
361
|
## OpenCode project support
|
|
153
362
|
|
|
154
363
|
Add opencode to targets.tools to project MCP entries into the project-root
|
|
@@ -166,9 +375,8 @@ OpenCode; explicitly limit those servers to other targets when needed.
|
|
|
166
375
|
OpenCode discovers .agents/skills directly, so PMCP creates no skill copies or
|
|
167
376
|
links. For invocation=user, projection sets permission.skill.<name> to deny:
|
|
168
377
|
the model's skill list omits that name, while the native /<name> command still
|
|
169
|
-
loads its original SKILL.md and accepts user arguments
|
|
170
|
-
|
|
171
|
-
without an external model call. It controls automatic skill selection, not
|
|
378
|
+
loads its original SKILL.md and accepts user arguments (measured: see
|
|
379
|
+
[Compatibility](compatibility.md#installation-and-packaging)). It controls automatic skill selection, not
|
|
172
380
|
arbitrary file access. Native global skill discovery remains a user preference.
|
|
173
381
|
|
|
174
382
|
pmcp doctor checks opencode debug skill and opencode mcp list without calling
|
|
@@ -181,62 +389,336 @@ See the [OpenCode MCP configuration](https://opencode.ai/docs/mcp-servers/),
|
|
|
181
389
|
[Agent Skills](https://opencode.ai/docs/skills/) and
|
|
182
390
|
[configuration precedence](https://opencode.ai/docs/config/).
|
|
183
391
|
|
|
184
|
-
##
|
|
392
|
+
## Shared remote MCP authentication
|
|
185
393
|
|
|
186
|
-
|
|
187
|
-
|
|
394
|
+
Use `auth = "pmcp"` to let Claude, Codex, Gemini, Antigravity, Grok and
|
|
395
|
+
OpenCode share one remote MCP login (only the Claude and Codex entries have run
|
|
396
|
+
live):
|
|
188
397
|
|
|
189
398
|
```toml
|
|
190
|
-
[
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
targets = ["
|
|
194
|
-
timeout_ms = 15000
|
|
399
|
+
[mcp.remote]
|
|
400
|
+
url = "https://example.com/mcp"
|
|
401
|
+
auth = "pmcp"
|
|
402
|
+
targets = ["claude", "codex"]
|
|
195
403
|
```
|
|
196
404
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
405
|
+
Run `pmcp project`, then `pmcp mcp login remote`. The projected stdio entries
|
|
406
|
+
run `pmcp project exec-mcp remote`; the proxy connects to the declared Streamable
|
|
407
|
+
HTTP endpoint. The login command prints an authorization URL without opening
|
|
408
|
+
a browser. Complete the loopback callback or paste the callback URL or code.
|
|
409
|
+
For a later completion, use `pmcp mcp login remote --no-wait`, then
|
|
410
|
+
`pmcp mcp login remote --code <callback-url-or-code>`. Issuers must support
|
|
411
|
+
PKCE S256 and dynamic client registration, or supply `--client-id` for a
|
|
412
|
+
pre-registered public client. Discovery follows the resource's OAuth metadata.
|
|
413
|
+
|
|
414
|
+
For bearer authentication, declare `bearer_token_env_var` and run login with
|
|
415
|
+
that variable set, or pass `--bearer-env <variable-name>`. The value is stored
|
|
416
|
+
privately and is never projected into runtime configuration or printed.
|
|
417
|
+
`pmcp mcp status remote` reports only credential presence, UTC expiry and scopes.
|
|
418
|
+
`pmcp mcp logout remote` clears the local credentials and requests remote
|
|
419
|
+
revocation when the issuer advertises it.
|
|
420
|
+
|
|
421
|
+
Credentials live in `$XDG_STATE_HOME/pmcp/credentials/<name>.json`, defaulting to
|
|
422
|
+
`~/.local/state/pmcp/credentials/`. Files use mode 0600 and the credential
|
|
423
|
+
directory uses mode 0700. Credentials are bound to the declared server URL.
|
|
424
|
+
Processes reread credentials under an OS lock before refreshing; refresh-token
|
|
425
|
+
rotation is stored atomically. This implementation requires the `flock` command.
|
|
426
|
+
An expired or revoked session reports an authentication error rather than
|
|
427
|
+
starting interactive login inside the MCP connection.
|
|
428
|
+
|
|
429
|
+
The CLI must be installed in the project or available as `pmcp` on PATH.
|
|
430
|
+
Codex receives environment-name references for `XDG_STATE_HOME` and any declared
|
|
431
|
+
header environment variables. `auth = "native"` preserves existing entries,
|
|
432
|
+
OAuth ownership and env_from behavior. Provider authentication remains native.
|
|
433
|
+
|
|
434
|
+
## Hooks
|
|
435
|
+
|
|
436
|
+
Guards, checks and session bookkeeping for every targeted runtime, and which runtime supports
|
|
437
|
+
what: [Hooks](hooks.md).
|
|
438
|
+
|
|
439
|
+
## Sessions
|
|
440
|
+
|
|
441
|
+
Sessions coordinate agents working in one repository and its worktrees. State
|
|
442
|
+
lives in one directory shared by every checkout of the repository.
|
|
443
|
+
|
|
444
|
+
| `[sessions]` key | Type | Default | Meaning |
|
|
445
|
+
| ---------------- | ------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
446
|
+
| `store` | string | `"files"` | The only store. |
|
|
447
|
+
| `state_dir` | path | `$XDG_STATE_HOME/pmcp/projects/<id>` (`~/.local/state/...`) | `<id>` is the first 16 hex digits of the sha256 of the git common directory. `~`, `~/` and `$HOME/` expand to the home directory and a relative path is relative to the main checkout: the directory holding `pmcp.toml`, taken in the worktree of the git common directory, so the main checkout and every linked worktree share one state. Outside git it is relative to the directory holding `pmcp.toml`. The hooks, the Claude Code session panes and the git commands resolve it the same way; so does `[git.mainline.gate] tree`. |
|
|
448
|
+
|
|
449
|
+
`store` and `state_dir` alone enable nothing; each feature has its own table:
|
|
450
|
+
|
|
451
|
+
| Table | Keys | Effect |
|
|
452
|
+
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
453
|
+
| `[sessions.registry]` | `liveness` (`"pid_heartbeat"`, the only value), `stale_minutes` (default `30`) | Records each session with its process and heartbeat; `pmcp sessions status` lists them. |
|
|
454
|
+
| `[sessions.pause]` | `mode` (`deny` default, `ask`, `warn`, `off`), `refuses` (`"mutating"`), `scripts` (regular expressions, default `[]`: a `node` script matching one also counts as mutating, e.g. your own delivery or sync script) | While `pmcp sessions pause` is in effect, edits and mutating commands are refused for every session but the one that paused; reading continues. |
|
|
455
|
+
| `[sessions.broadcast]` | `keep` (default `10`), `deliver_on` (default `["session_start", "prompt", "before_tool"]`; also `after_tool`, `stop`) | Delivers `pmcp sessions broadcast` text once to each session, as context on the listed events. |
|
|
456
|
+
| `[sessions.leases.<name>]` | `path` (string, shown in the message and used by git delivery), `blocks` (required list of argv prefixes) | While another session holds lease `<name>`, commands starting with a listed prefix are denied until its delivery finishes. |
|
|
457
|
+
| `[sessions.roles.<name>]` | `agent_type` (default `<name>`, also matches `plugin:<name>`), `allow_edits` (default `false`), `allow_commands` (list of argv prefixes, default `[]`) | A subagent of that type may edit only if allowed and run only the listed commands. Claude only. |
|
|
458
|
+
|
|
459
|
+
These tables have no `mode`, except pause. Without `[sessions.registry]` no
|
|
460
|
+
session is recorded, and `[ui.claude]` refuses to project.
|
|
461
|
+
|
|
462
|
+
### `[sessions.mailbox]`
|
|
463
|
+
|
|
464
|
+
Addressed messages between sessions, and between you and them. A missing table leaves
|
|
465
|
+
the mailbox off; a declared one, even empty, turns it on.
|
|
466
|
+
|
|
467
|
+
| Key | Type | Default | Meaning |
|
|
468
|
+
| --------------- | ------ | ------- | --------------------------------------------------------------------------- |
|
|
469
|
+
| `enabled` | bool | `true` | `false` keeps the table but turns the mailbox off. |
|
|
470
|
+
| `ttl_minutes` | number | `1440` | Default lifetime of a message; `--ttl` overrides it per message. |
|
|
471
|
+
| `max_delivered` | number | `5` | At most this many new messages are shown at once, plus a count of the rest. |
|
|
472
|
+
| `audit` | bool | `true` | Append a line per sent, delivered, acked and expired event. |
|
|
473
|
+
| `wake` | bool | `false` | Wake idle recipients on every send, as `--wake` does for one message. |
|
|
474
|
+
|
|
475
|
+
Each message is one file, `<state>/messages/<id>.json`, created atomically and
|
|
476
|
+
never rewritten: `id`, `from` (session and alias), `to`, `subject`, `body`,
|
|
477
|
+
`createdAt`, `expiresAt`, `replyTo`, `once`. `to` lists selectors: `all`,
|
|
478
|
+
`session:<id>` (a prefix of at least eight characters works), `alias:<name>`,
|
|
479
|
+
`role:<name>` (a `[sessions.roles]` name or the agent type), or `worktree:<path>`
|
|
480
|
+
(a linked worktree's path, or its directory name; `desk:<path>` is an older
|
|
481
|
+
spelling that still works). A message to `all` reaches the
|
|
482
|
+
sessions that were running when it was sent; a session the registry records
|
|
483
|
+
later does not get earlier broadcasts. Delivery and acknowledgement are
|
|
484
|
+
empty markers under `<state>/inbox/<session>/`, so a message is never edited
|
|
485
|
+
for them. `<state>/messages.jsonl` is the append-only audit.
|
|
486
|
+
|
|
487
|
+
The hooks deliver each unacknowledged message addressed to a session once,
|
|
488
|
+
through that runtime's context channel; on a runtime that does not show
|
|
489
|
+
context at an event, the notice is held for the next one that does. Later
|
|
490
|
+
events notice only messages that arrived since, with a count of earlier
|
|
491
|
+
unacknowledged ones. Delivery is recorded and never counts as an
|
|
492
|
+
acknowledgement. A message sent with `--once` says it is a one-time request,
|
|
493
|
+
so the recipient does not keep its instructions as standing rules.
|
|
204
494
|
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
495
|
+
```sh
|
|
496
|
+
pmcp sessions send --to alias:reviewer --to role:delivery --subject deploy --once "Hold the deploy until 14:00"
|
|
497
|
+
echo "longer body" | pmcp sessions send --to all -
|
|
498
|
+
pmcp sessions inbox [--session <id>] [--all] [--json]
|
|
499
|
+
pmcp sessions ack <id>... [--session <id>]
|
|
500
|
+
pmcp sessions reply <id> "Done"
|
|
501
|
+
pmcp sessions send --wake --to alias:reviewer "CI is green again"
|
|
502
|
+
pmcp sessions sweep
|
|
503
|
+
```
|
|
211
504
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
505
|
+
A recipient that is idle sees mail only at its next event. With `--wake`, or
|
|
506
|
+
`wake = true` in the table, `send` and `reply` also start a turn in each idle
|
|
507
|
+
recipient whose runtime allows it, and the woken session's hooks then deliver
|
|
508
|
+
the mail as usual; the wake itself carries only a count, the subjects and one
|
|
509
|
+
exact command to run, `pmcp sessions inbox --session <id>`. Each attempt is an
|
|
510
|
+
audit line (`woken`, with the transport and channel), and `pmcp doctor` shows
|
|
511
|
+
each live session's last wake.
|
|
512
|
+
|
|
513
|
+
- Any runtime hosted by pmcp-pty: the session-start hook records the host's
|
|
514
|
+
socket, session and instance from `PMCP_PTY_*` when the host is the
|
|
515
|
+
runtime's parent or grandparent (a runtime started from a hosted session's
|
|
516
|
+
shell inherits the variables but is not recorded). `send --wake` asks the
|
|
517
|
+
host for one short `turn`; the host picks the channel (Claude inbox, OpenCode
|
|
518
|
+
server, Codex queue, Grok leader or a guarded screen write) and its receipt
|
|
519
|
+
is in `send --json`. A refused turn, such as one behind an open dialog,
|
|
520
|
+
leaves the mail for the next event. The same hooks report each turn's start
|
|
521
|
+
and end (with the last assistant message) and permission notices to the
|
|
522
|
+
host, which ends a turn on that before trusting the screen. A hosted
|
|
523
|
+
session gets mail only on the wake turn itself (a prompt starting
|
|
524
|
+
`pmcp mail:`): as context on other prompts the notice took over turns
|
|
525
|
+
pmcp-pty sent. The two items below are for sessions pmcp-pty does not host.
|
|
526
|
+
- Claude Code: through the session's documented
|
|
527
|
+
[cross-session inbox](https://code.claude.com/docs/en/cross-session-messaging),
|
|
528
|
+
found in `~/.claude/sessions/<pid>.json`, which pmcp only reads. The target's
|
|
529
|
+
own inbound controls apply: a session in `bypassPermissions` without
|
|
530
|
+
`crossSessionInbound = "accept"` holds the wake for approval, and a wake can
|
|
531
|
+
approve nothing.
|
|
532
|
+
- OpenCode: `POST /session/<id>/prompt_async` on the server the session runs
|
|
533
|
+
on, which the generated plugin records; HTTP basic auth from
|
|
534
|
+
`OPENCODE_SERVER_PASSWORD` (user `OPENCODE_SERVER_USERNAME`, default
|
|
535
|
+
`opencode`).
|
|
536
|
+
- Codex, Gemini, Antigravity and Grok outside pmcp-pty have no supported way to
|
|
537
|
+
start a turn in a running session; their mail waits for the next event.
|
|
538
|
+
`pmcp sessions status` and `pmcp doctor` show which live sessions can be
|
|
539
|
+
woken.
|
|
540
|
+
|
|
541
|
+
`--session <id>` acts as that session and `--by <name>` as a named sender
|
|
542
|
+
outside one; the notice a session receives spells out its commands with its
|
|
543
|
+
own `--session`. Those commands, and the wake text, say `pmcp` only when the
|
|
544
|
+
`pmcp` on PATH is the CLI that projects this checkout (its own install, else
|
|
545
|
+
the one that last projected it); otherwise they name that CLI as
|
|
546
|
+
`node '<path>/dist/cli.js'`, and `pmcp doctor` warns. Without either, a command run inside a runtime acts as that
|
|
547
|
+
runtime's session: the live session whose runtime process is its nearest
|
|
548
|
+
ancestor, else the id the runtime exposes to tool commands
|
|
549
|
+
(`CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, `ANTIGRAVITY_CONVERSATION_ID`,
|
|
550
|
+
`GROK_SESSION_ID`; Gemini and OpenCode expose none). When it cannot tell, it
|
|
551
|
+
warns and acts as `operator`. `sweep` also deletes expired messages and their
|
|
552
|
+
markers.
|
|
553
|
+
|
|
554
|
+
`pmcp sessions status` and `pmcp doctor` name live sessions that should be
|
|
555
|
+
restarted to get the current hooks: one started under an older (or untracked)
|
|
556
|
+
`policy.json`, which matters when new hook events were added, and a Codex
|
|
557
|
+
session started before `.codex/hooks.json` last changed, since Codex reads its
|
|
558
|
+
hook file only when a session starts.
|
|
559
|
+
|
|
560
|
+
With the mailbox on, `pmcp sessions broadcast` also sends its text as a
|
|
561
|
+
message to `all`, and the mailbox delivers it instead of
|
|
562
|
+
`[sessions.broadcast]`; `broadcast.json` and each session's `seenBroadcast`
|
|
563
|
+
are still written, so `pmcp sessions status`, the session list and the
|
|
564
|
+
Claude Code session panes read broadcasts as before. `unbroadcast` withdraws those
|
|
565
|
+
messages too.
|
|
566
|
+
|
|
567
|
+
## Git workflow
|
|
568
|
+
|
|
569
|
+
Worktrees, delivery to the mainline and main checkout sync: [Git workflow](git-workflow.md).
|
|
570
|
+
|
|
571
|
+
## Logging
|
|
572
|
+
|
|
573
|
+
| `[logging]` key | Type | Default | Allowed |
|
|
574
|
+
| --------------- | ------ | ------------------------------------------------ | ----------------------------------------- |
|
|
575
|
+
| `level` | string | `"info"` | `error`, `warn`, `info`, `debug`, `trace` |
|
|
576
|
+
| `format` | string | `"jsonl"` | `jsonl` only |
|
|
577
|
+
| `max_file_mb` | number | `20` | greater than 0 |
|
|
578
|
+
| `keep_days` | number | `14` | greater than 0 |
|
|
579
|
+
| `redact` | list | `["secret_values", "prompt_text", "env_values"]` | any subset |
|
|
580
|
+
| `components` | table | `{}` | `<component> = "<level>"` |
|
|
581
|
+
|
|
582
|
+
The `PMCP_LOG` environment variable overrides the level. `[hooks] error_log`
|
|
583
|
+
switches hook logging on or off. Read the logs with `pmcp logs`.
|
|
584
|
+
|
|
585
|
+
## Claude session panes
|
|
586
|
+
|
|
587
|
+
`[ui.claude]` installs the session panes into Claude Code: `sessions_pane`,
|
|
588
|
+
`status_band`, `commands` and `hold_foreign_edits`, all booleans defaulting to
|
|
589
|
+
`true`. `hold_foreign_edits` asks before editing a file another live session
|
|
590
|
+
edited. It needs `[sessions.registry]`, and is written only when `claude` is
|
|
591
|
+
in `[targets] tools`. Without the table nothing is installed. `pmcp doctor`
|
|
592
|
+
shows the projected switches, or a failure until `pmcp project` writes them; it
|
|
593
|
+
cannot tell whether a running Claude Code loaded the session panes.
|
|
594
|
+
|
|
595
|
+
## A complete example
|
|
596
|
+
|
|
597
|
+
A project with two runtimes, the full guard set, sessions, the git workflow and
|
|
598
|
+
a team marketplace:
|
|
217
599
|
|
|
218
|
-
|
|
600
|
+
```toml
|
|
601
|
+
[catalog]
|
|
602
|
+
workspaces = [".", "packages/*"]
|
|
219
603
|
|
|
220
|
-
|
|
604
|
+
[targets]
|
|
605
|
+
tools = ["claude", "codex"]
|
|
221
606
|
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
607
|
+
[mcp.skills]
|
|
608
|
+
command = "node"
|
|
609
|
+
args = ["${PROJECT_ROOT}/node_modules/@modootoday/pmcp/dist/cli.js", "serve"]
|
|
610
|
+
|
|
611
|
+
[skills.deploy]
|
|
612
|
+
invocation = "user"
|
|
613
|
+
|
|
614
|
+
[agents.reviewer.claude]
|
|
615
|
+
tools = "Read, Grep, Glob"
|
|
616
|
+
model = "inherit"
|
|
617
|
+
effort = "high"
|
|
618
|
+
|
|
619
|
+
[hooks]
|
|
620
|
+
targets = ["claude", "codex"]
|
|
621
|
+
ask_fallback = "deny"
|
|
622
|
+
|
|
623
|
+
[hooks.guards.shell.in_place_edit]
|
|
624
|
+
mode = "ask"
|
|
625
|
+
|
|
626
|
+
[hooks.guards.shell.heredoc]
|
|
627
|
+
|
|
628
|
+
[hooks.guards.shell.stdin_interpreter]
|
|
629
|
+
|
|
630
|
+
[hooks.guards.shell.compose_teardown]
|
|
631
|
+
|
|
632
|
+
[hooks.guards.shell.host_approval]
|
|
633
|
+
|
|
634
|
+
[hooks.guards.shell.secret_exfiltration]
|
|
635
|
+
mode = "graded"
|
|
636
|
+
|
|
637
|
+
[[hooks.guards.shell.secret_exfiltration.value_commands]]
|
|
638
|
+
binary = "secrets-cli"
|
|
639
|
+
read = ["read", "env get"]
|
|
640
|
+
publish = ["deploy", "secret put", "secret delete"]
|
|
641
|
+
|
|
642
|
+
[hooks.guards.git.push_without_verify]
|
|
643
|
+
|
|
644
|
+
[hooks.guards.git.forced_branch_move]
|
|
645
|
+
|
|
646
|
+
[hooks.guards.git.stage_all]
|
|
647
|
+
|
|
648
|
+
[hooks.guards.git.gate_bypass_env]
|
|
649
|
+
names = ["ALLOW_DIRECT_PUSH", "SKIP_GATE"]
|
|
650
|
+
|
|
651
|
+
[[hooks.guards.custom]]
|
|
652
|
+
name = "source-formatting"
|
|
653
|
+
command = ["node", ".agents/guards/source-formatting.mjs"]
|
|
226
654
|
targets = ["codex"]
|
|
227
|
-
|
|
228
|
-
|
|
655
|
+
on = "after_edit"
|
|
656
|
+
|
|
657
|
+
[hooks.checks.after_edit]
|
|
658
|
+
validator_glob = ".agents/skills/*/scripts/validate.ts"
|
|
659
|
+
command = ["node", "{validator}"]
|
|
660
|
+
|
|
661
|
+
[hooks.checks.on_stop]
|
|
229
662
|
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
native blocking feedback with the reason; the completed file edit remains on disk
|
|
233
|
-
for correction. Other tools do not invoke this guard. Edit targets currently
|
|
234
|
-
support Codex only, and names must be unique across shell and edit declarations.
|
|
663
|
+
[sessions]
|
|
664
|
+
state_dir = ".pmcp-state"
|
|
235
665
|
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
666
|
+
[sessions.registry]
|
|
667
|
+
|
|
668
|
+
[sessions.pause]
|
|
669
|
+
|
|
670
|
+
[sessions.broadcast]
|
|
671
|
+
|
|
672
|
+
[sessions.mailbox]
|
|
673
|
+
ttl_minutes = 1440
|
|
674
|
+
max_delivered = 5
|
|
675
|
+
|
|
676
|
+
[sessions.leases.lockfile]
|
|
677
|
+
path = "package-lock.json"
|
|
678
|
+
blocks = [["npm", "install"], ["npm", "ci"], ["pmcp", "git", "deliver"]]
|
|
679
|
+
|
|
680
|
+
[sessions.roles.delivery]
|
|
681
|
+
allow_commands = [["pmcp", "git", "deliver"], ["git", "log"], ["git", "status"]]
|
|
682
|
+
|
|
683
|
+
[git]
|
|
684
|
+
remote = "origin"
|
|
685
|
+
|
|
686
|
+
[git.mainline]
|
|
687
|
+
branch = "main"
|
|
688
|
+
|
|
689
|
+
[git.mainline.gate]
|
|
690
|
+
command = ["npm", "test"]
|
|
691
|
+
|
|
692
|
+
[git.mainline.deliver]
|
|
693
|
+
|
|
694
|
+
[git.mainline.sync]
|
|
695
|
+
install = ["npm", "ci"]
|
|
696
|
+
install_when_changed = ["package-lock.json"]
|
|
697
|
+
|
|
698
|
+
[git.worktrees]
|
|
699
|
+
bootstrap = ["sh", "scripts/setup-worktree.sh"]
|
|
700
|
+
link_from_main = [".env"]
|
|
701
|
+
|
|
702
|
+
[git.worktrees.sync]
|
|
703
|
+
install_after_move = "background"
|
|
704
|
+
notice_paths = ["AGENTS.md", "pmcp.toml"]
|
|
705
|
+
|
|
706
|
+
[git.submodules]
|
|
707
|
+
|
|
708
|
+
[logging]
|
|
709
|
+
level = "warn"
|
|
710
|
+
|
|
711
|
+
[ui.claude]
|
|
712
|
+
|
|
713
|
+
[permissions.claude]
|
|
714
|
+
ask = ["Read(.env)", "Bash(git push:*)"]
|
|
715
|
+
|
|
716
|
+
[marketplaces.team]
|
|
717
|
+
source = { github = "example/team-marketplace" }
|
|
718
|
+
|
|
719
|
+
[marketplaces.team.plugins]
|
|
720
|
+
review = { targets = ["claude", "codex"] }
|
|
721
|
+
```
|
|
240
722
|
|
|
241
723
|
## Native memory metadata
|
|
242
724
|
|