@modootoday/pmcp 0.17.4 → 0.18.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/plugins/marketplace.json +1 -1
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/CHANGELOG.md +60 -0
- package/README.md +29 -24
- package/dist/apply-4IGTXOCQ.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-3RY3OZGY.js +18 -0
- package/dist/chunk-25GHX674.js +1246 -0
- package/dist/chunk-2P4Z2NUX.js +28 -0
- package/dist/chunk-34DECPVC.js +22 -0
- package/dist/chunk-3NYG4SGU.js +45 -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-4VCC2NXE.js +104 -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-65ZHM5RH.js +4985 -0
- package/dist/chunk-665TA55Z.js +419 -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-7BLPN3W6.js +31 -0
- package/dist/chunk-7DLZC73N.js +29 -0
- package/dist/chunk-7GBYECSK.js +72 -0
- package/dist/chunk-7TD53M7L.js +13 -0
- package/dist/chunk-A4PKLESO.js +112 -0
- package/dist/chunk-ABTJQ4QV.js +74 -0
- package/dist/chunk-BBTBJCFA.js +380 -0
- package/dist/chunk-BU65MNVU.js +13 -0
- package/dist/chunk-BVCTKPT3.js +83 -0
- package/dist/chunk-C4NHQGHL.js +142 -0
- package/dist/chunk-CJTKR6K6.js +1213 -0
- package/dist/chunk-DCU2EXQV.js +78 -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-E7OOHLQR.js +7 -0
- package/dist/chunk-EATCUWGG.js +66 -0
- package/dist/chunk-EIDIVIAD.js +33 -0
- package/dist/chunk-EJBZGIDK.js +1934 -0
- package/dist/chunk-ELAGZ635.js +252 -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-IGYRMM62.js +28 -0
- package/dist/chunk-IJBSOWHK.js +86 -0
- package/dist/chunk-INT7QLEU.js +114 -0
- package/dist/chunk-J6QLLQVL.js +1025 -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-JUXNIXN4.js +42 -0
- package/dist/chunk-JWRZDYB5.js +59 -0
- package/dist/chunk-KMXRRSKT.js +660 -0
- package/dist/chunk-LAZQBMAU.js +67 -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-MM2Y43LC.js +87 -0
- package/dist/chunk-MPSQXSC6.js +346 -0
- package/dist/chunk-MVFH26QT.js +97 -0
- package/dist/chunk-MWFOUBFC.js +39 -0
- package/dist/chunk-N5AQ3PP7.js +211 -0
- package/dist/chunk-NQPURJT5.js +44 -0
- package/dist/chunk-NRBQK6UX.js +105 -0
- package/dist/chunk-NZS5CD72.js +333 -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-PLX3BOOS.js +396 -0
- package/dist/chunk-PMJG2CXF.js +122 -0
- package/dist/chunk-PWSJJXLQ.js +643 -0
- package/dist/chunk-Q5H3L6Y4.js +23 -0
- package/dist/chunk-Q65R3XKX.js +155 -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-R4L6LJJ2.js +778 -0
- package/dist/chunk-R5MT42JS.js +284 -0
- package/dist/chunk-RK4PYD7L.js +73 -0
- package/dist/chunk-RMATE45Z.js +197 -0
- package/dist/chunk-S3PIAMXV.js +230 -0
- package/dist/chunk-SG5TPMKH.js +93 -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-UOCLRM7P.js +151 -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-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-YMHUM7AV.js +22 -0
- package/dist/chunk-YSAWTGNA.js +117 -0
- package/dist/chunk-Z4HRRXRF.js +478 -0
- package/dist/chunk-ZH6R642Z.js +102 -0
- package/dist/claude-U2JC2DNQ.js +77 -0
- package/dist/cli-VYCQJZ5X.js +41 -0
- package/dist/cli-ZTCBSDW4.js +46 -0
- package/dist/cli.js +144 -16197
- package/dist/completion-E7RRG3ZT.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-XXH4FLUG.js +93 -0
- package/dist/doctor-ZIOESU3N.js +538 -0
- package/dist/entry-ZNFCTDVE.js +305 -0
- package/dist/exec-mcp-X6372BLE.js +365 -0
- package/dist/harness-F2XFDYXF.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 +5221 -0
- package/dist/hook-spec-C5fWTSCH.d.ts +100 -0
- package/dist/hook.js +26 -0
- package/dist/hooks-FYE2L5RW.js +21 -0
- package/dist/host-GRY3VAHH.js +22 -0
- package/dist/host-X6BR6X4O.js +200 -0
- package/dist/host-run-GCA6H6SR.js +307 -0
- package/dist/http.d.ts +5 -42
- package/dist/http.js +21 -2234
- package/dist/import-mcp-2TTBPVLY.js +400 -0
- package/dist/index.d.ts +146 -168
- package/dist/index.js +133 -4948
- package/dist/init-627KFXTG.js +14 -0
- package/dist/install-GG7HHZK2.js +796 -0
- package/dist/invoke-LW22Z6ET.js +23 -0
- package/dist/list-MCP2FXUF.js +68 -0
- package/dist/list-NGMSQ5SH.js +65 -0
- package/dist/load-BEUBABtB.d.ts +21 -0
- package/dist/logout-6CSHUWWE.js +44 -0
- package/dist/logs-SPB6AANY.js +107 -0
- package/dist/mailbox/index.d.ts +10 -5
- package/dist/mailbox/index.js +53 -1572
- package/dist/mailbox-7BV54Q4R.js +285 -0
- package/dist/mailbox-GDJ7BWQN.js +189 -0
- package/dist/mainline-JQTTYJMI.js +639 -0
- package/dist/marketplace-G4VQET5W.js +191 -0
- package/dist/mcp-2DKVU3SW.js +15 -0
- package/dist/mcp-V23HC3LB.js +193 -0
- package/dist/models-ISU4DCMA.js +32 -0
- package/dist/opencode-CN7JLQYO.js +60 -0
- package/dist/pause-FFAYRBWI.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-FY62G55N.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-UU4HZIUP.js +18 -0
- package/dist/run-HALGEJNJ.js +19 -0
- package/dist/run-OGA3P7FC.js +126 -0
- package/dist/serve-NBKT5BKY.js +104 -0
- package/dist/session-XM2CR425.js +159 -0
- package/dist/setup-DTKZLZUT.js +18 -0
- package/dist/start-login-UIQYQBMC.js +416 -0
- package/dist/status-A2OUTNGK.js +9 -0
- package/dist/status-H2VAHIDV.js +10 -0
- package/dist/status-NOOHW5WA.js +43 -0
- package/dist/status-VHODZPXB.js +55 -0
- package/dist/status-XQANBVXW.js +286 -0
- package/dist/stdio.d.ts +3 -13
- package/dist/stdio.js +16 -3186
- package/dist/sweep-64JDCGK6.js +18 -0
- package/dist/test-MKAXFJOL.js +561 -0
- package/dist/tools-gpHNq9Dh.d.ts +328 -0
- package/dist/tui-MWKAXE4K.js +153 -0
- package/dist/unbroadcast-KPUEFLZD.js +18 -0
- package/dist/validate-5GZ5YWNA.js +46 -0
- package/dist/worker-RQ575EJL.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/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/project-configuration.md +821 -4
- package/docs/terminal-harness.md +71 -28
- package/docs/terminal-workspace.md +91 -170
- package/gemini-extension.json +1 -1
- package/package.json +13 -1
- package/plugin.json +1 -1
- package/plugins/pmcp/.claude-plugin/plugin.json +4 -2
- package/plugins/pmcp/gemini-extension.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 +1 -1
- package/plugins/pmcp/skills/agent-assets-migrate/SKILL.md +96 -0
- package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +100 -0
- package/plugins/pmcp/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
- package/plugins/pmcp/skills/package-skill-catalog/SKILL.md +51 -11
- package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +145 -0
- package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +104 -0
- package/plugins/pmcp/skills/skill-package-scaffold/SKILL.md +88 -0
- package/schema/catalog-v1.json +158 -0
- package/schema/library.json +164 -0
- package/schema/marketplace-manifest.json +130 -0
- package/schema/plugin-manifest.json +55 -0
- package/schema/skill-frontmatter.json +144 -0
- package/schema/skill-metadata-core.json +110 -0
- package/skills/agent-assets-migrate/SKILL.md +96 -0
- package/skills/headless-agents-ci-scaffold/SKILL.md +100 -0
- package/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
- package/skills/package-skill-catalog/SKILL.md +51 -11
- package/skills/pmcp-project-init/SKILL.md +145 -0
- package/skills/pmcp-sessions-and-git/SKILL.md +104 -0
- package/skills/skill-package-scaffold/SKILL.md +88 -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/dist/{tui-worker.d.ts → hook.d.ts} +0 -0
|
@@ -16,8 +16,80 @@ marketplaces = ["vendor/marketplace"]
|
|
|
16
16
|
|
|
17
17
|
Paths resolve against the file's directory. Keys are `roots`, `scopes`,
|
|
18
18
|
`workspaces`, `packages` and `marketplaces`, each a list mirroring the flag of
|
|
19
|
-
the same meaning
|
|
19
|
+
the same meaning, and `builtin` (boolean, default on) for the bundled free
|
|
20
|
+
marketplace; an unknown key is an error. A flag replaces the file's list
|
|
20
21
|
of its kind. `--config <file>` names another file and `--no-config` ignores it.
|
|
22
|
+
The nearest `pmcp.toml` is found by walking up from the working directory,
|
|
23
|
+
stopping at the directory that holds `.git`.
|
|
24
|
+
|
|
25
|
+
`[catalog.validation]` makes `pmcp validate` stricter than the Agent Skills
|
|
26
|
+
specification. Without it, only the specification is checked.
|
|
27
|
+
|
|
28
|
+
```toml
|
|
29
|
+
[catalog.validation]
|
|
30
|
+
profile = "catalog-v1" # or "library"
|
|
31
|
+
deny_list = "private-terms.txt"
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
| Key | Type | Default | Meaning |
|
|
35
|
+
| ----------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
36
|
+
| `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. |
|
|
37
|
+
| `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. |
|
|
38
|
+
|
|
39
|
+
Both apply to named skill directories and, with no directory named, to every
|
|
40
|
+
skill the catalog reaches.
|
|
41
|
+
|
|
42
|
+
## Table index
|
|
43
|
+
|
|
44
|
+
Every table pmcp reads, and where it is described. An unknown key inside one
|
|
45
|
+
of these tables is an error unless noted; an unknown top-level table is
|
|
46
|
+
ignored.
|
|
47
|
+
|
|
48
|
+
| Table | Section |
|
|
49
|
+
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
|
|
50
|
+
| `[catalog]`, `[catalog.validation]` | [Project config](#project-config) |
|
|
51
|
+
| `[embedding]`, `[embedding.encoder]` | [Embedding models](embeddings.md) |
|
|
52
|
+
| `[marketplaces.<name>]` | [Marketplaces](#marketplaces) |
|
|
53
|
+
| `[targets]`, `[skills.<name>]`, `[agents.<name>.<tool>]`, `[rules.packages]` | [Native files for each agent tool](#native-files-for-each-agent-tool) |
|
|
54
|
+
| `[mcp.<alias>]` | [Unified project MCP configuration](#unified-project-mcp-configuration) |
|
|
55
|
+
| `[hooks]`, `[hooks.guards.*]`, `[[hooks.guards.custom]]`, `[hooks.checks.*]` | [Hooks](#hooks) |
|
|
56
|
+
| `[[hooks.shell]]`, `[[hooks.edit]]` | [Operator shell guards](#operator-shell-guards) |
|
|
57
|
+
| `[sessions]`, `[sessions.registry]`, `[sessions.pause]`, `[sessions.broadcast]`, `[sessions.mailbox]`, `[sessions.leases.<name>]`, `[sessions.roles.<name>]` | [Sessions](#sessions) |
|
|
58
|
+
| `[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) |
|
|
59
|
+
| `[logging]`, `[logging.components]` | [Logging](#logging) |
|
|
60
|
+
| `[permissions.claude]` | [Claude permission rules](#claude-permission-rules) |
|
|
61
|
+
| `[ui.claude]` | [Claude session panes](#claude-session-panes) |
|
|
62
|
+
| `[tui]`, `[mailbox]` | [Terminal workspace](terminal-workspace.md) |
|
|
63
|
+
| `[host]`, `[[host.sessions]]`, `[[host.answers]]`, `[host.browser]`, `[host.desktop]`, `[[host.desktop.launch]]` | [Sessions pmcp-pty hosts](#sessions-pmcp-pty-hosts) |
|
|
64
|
+
|
|
65
|
+
## Marketplaces
|
|
66
|
+
|
|
67
|
+
`[marketplaces.<name>]` declares a plugin marketplace once for catalog search
|
|
68
|
+
and for each agent tool:
|
|
69
|
+
|
|
70
|
+
```toml
|
|
71
|
+
[marketplaces.team]
|
|
72
|
+
source = { path = "packages/marketplace" } # or { github = "owner/repo", ref = "main" } or { builtin = true }
|
|
73
|
+
catalog = true # searchable, like [catalog] marketplaces
|
|
74
|
+
[marketplaces.team.plugins]
|
|
75
|
+
review = { targets = ["claude", "codex"] }
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`pmcp project` writes `extraKnownMarketplaces` and `enabledPlugins` in
|
|
79
|
+
`.claude/settings.json`, and `[marketplaces.<name>]` and
|
|
80
|
+
`[plugins."<plugin>@<name>"]` in the pmcp block of `.codex/config.toml`. Local
|
|
81
|
+
sources are written as absolute paths. Codex reads the project file only in a
|
|
82
|
+
trusted project and installs plugins into user state, so `pmcp doctor` prints
|
|
83
|
+
`codex plugin add <plugin>@<name>` for each declared plugin Codex has not
|
|
84
|
+
installed and reports enabled plugins the file does not declare.
|
|
85
|
+
`[catalog] marketplaces` remains an alias.
|
|
86
|
+
|
|
87
|
+
A marketplace name and each plugin name match `^[a-z0-9][a-z0-9-]*$`. `source`
|
|
88
|
+
is required and holds exactly one of `path` (resolved against the toml
|
|
89
|
+
directory), `github` (`owner/repo`, with an optional `ref`) or `builtin = true`.
|
|
90
|
+
`catalog = true` needs a path or builtin source. Each plugin's `targets` is
|
|
91
|
+
required and lists `claude` and/or `codex`. Without the table no marketplace is
|
|
92
|
+
declared.
|
|
21
93
|
|
|
22
94
|
## Native files for each agent tool
|
|
23
95
|
|
|
@@ -34,10 +106,10 @@ described in [OpenCode project support](#opencode-project-support).
|
|
|
34
106
|
tools = ["claude", "codex", "gemini", "grok", "antigravity"]
|
|
35
107
|
|
|
36
108
|
[skills.deploy]
|
|
37
|
-
invocation = "user"
|
|
109
|
+
invocation = "user" # the person starts it; the model is not offered it
|
|
38
110
|
|
|
39
111
|
[agents.reviewer.claude]
|
|
40
|
-
tools = "Read, Grep"
|
|
112
|
+
tools = "Read, Grep" # fields one tool reads stay out of agent.md
|
|
41
113
|
|
|
42
114
|
[rules]
|
|
43
115
|
root = "AGENTS.md"
|
|
@@ -55,6 +127,13 @@ pmcp project remove <name>
|
|
|
55
127
|
pmcp doctor # ask each installed tool what it loads
|
|
56
128
|
```
|
|
57
129
|
|
|
130
|
+
| Table | Keys |
|
|
131
|
+
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
132
|
+
| `[targets]` | `tools`: list of `claude`, `codex`, `gemini`, `grok`, `antigravity`, `opencode`. Missing means nothing is projected. |
|
|
133
|
+
| `[skills.<name>]` | `invocation`: `"any"` (default) or `"user"`. |
|
|
134
|
+
| `[agents.<name>.<tool>]` | Any keys, merged over the agent's frontmatter; Claude keeps `name`, `description`, `tools`, `model`, `effort`, Gemini keeps `name`, `description`. |
|
|
135
|
+
| `[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. |
|
|
136
|
+
|
|
58
137
|
Rules go to `.claude/rules/<dir>/`, never the top level, because Grok Build
|
|
59
138
|
loads top-level `.claude/rules/*.md` in every session regardless of `paths:`.
|
|
60
139
|
A server that names `${PROJECT_ROOT}` is launched through `sh`, which finds
|
|
@@ -64,6 +143,165 @@ overwritten. `doctor` calls no model: it reads `claude mcp list`,
|
|
|
64
143
|
`codex mcp list`, `gemini skills list`, `gemini mcp list` and
|
|
65
144
|
`grok inspect --json`, and skips a tool that is not installed.
|
|
66
145
|
|
|
146
|
+
## Sessions pmcp-pty hosts
|
|
147
|
+
|
|
148
|
+
`[host]` names the sessions pmcp-pty runs for this project and the few dialog
|
|
149
|
+
answers the operator allows it to give. `pmcp project` writes them to
|
|
150
|
+
`.agents/pmcp-pty/host.json` (the sessions) and `.agents/pmcp-pty/policy.json`
|
|
151
|
+
(answers, `mcp_write`, roots), pinned in `pmcp.lock` like every output, and
|
|
152
|
+
`pmcp doctor` reports whether they match. pmcp.toml is writable by agents, so
|
|
153
|
+
neither file takes effect by being projected: pmcp-pty loads only a copy the
|
|
154
|
+
operator approved.
|
|
155
|
+
|
|
156
|
+
```toml
|
|
157
|
+
[host]
|
|
158
|
+
roots = ["."] # every session cwd must be under one of these
|
|
159
|
+
mcp_write = false # pty_turn and pty_lease over pmcp harness mcp
|
|
160
|
+
|
|
161
|
+
[[host.sessions]]
|
|
162
|
+
name = "lead" # lowercase, digits and -; unique
|
|
163
|
+
runtime = "claude" # claude, codex, gemini, agy, grok or opencode
|
|
164
|
+
cwd = "." # inside the project
|
|
165
|
+
argv = ["claude"] # default: the runtime's name
|
|
166
|
+
labels = { task = "review" }
|
|
167
|
+
restart = "on-exit" # or "no" (default); max_restarts defaults to 3
|
|
168
|
+
|
|
169
|
+
[[host.answers]]
|
|
170
|
+
runtime = "gemini"
|
|
171
|
+
dialog = "tool-approval" # the dialog name pmcp-pty's profile reports
|
|
172
|
+
options = ["Allow once"] # option keys or labels
|
|
173
|
+
|
|
174
|
+
[host.browser]
|
|
175
|
+
allow_private = ["localhost:5173"] # host:port or host:*; pmcp-browser is public-only without it
|
|
176
|
+
|
|
177
|
+
[[host.desktop.launch]]
|
|
178
|
+
name = "terminal" # what pmcp-desktop's launch tool takes
|
|
179
|
+
argv = ["xterm"] # never a browser
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Login and authentication (`auth-*`), folder and workspace trust and hook
|
|
183
|
+
review dialogs are never answered: a `[[host.answers]]` entry naming one is a
|
|
184
|
+
configuration error, and pmcp-pty refuses them whatever a policy says. Paths
|
|
185
|
+
stay project-relative, so the projected files hold no host path.
|
|
186
|
+
`[host.browser]` and `[[host.desktop.launch]]` widen
|
|
187
|
+
[pmcp-browser and pmcp-desktop](#browser-and-desktop-for-agents) and act only
|
|
188
|
+
from the approved copy too; a launch entry that starts a browser is an error.
|
|
189
|
+
|
|
190
|
+
### Approving the host policy
|
|
191
|
+
|
|
192
|
+
Run `pmcp harness host approve` in your own terminal after `pmcp project`. It
|
|
193
|
+
prints the sessions, the answer rules, `mcp_write` and one sha256 over both
|
|
194
|
+
projected files, and approves only when you type the first 8 hex digits of
|
|
195
|
+
that hash. The approved copy goes to
|
|
196
|
+
`$XDG_STATE_HOME/pmcp/host-approvals/<project id>/` (directory 0700, files
|
|
197
|
+
0600; the `[sessions] state_dir` override does not apply), and
|
|
198
|
+
`pmcp-pty daemon --host <that directory>` loads only that copy, after checking
|
|
199
|
+
it still matches its own approval. A later projection that differs is
|
|
200
|
+
reported by `pmcp doctor` and `pmcp harness host status`, and the approved
|
|
201
|
+
copy stays in force until you approve again.
|
|
202
|
+
|
|
203
|
+
`approve` refuses without an interactive terminal, when `PMCP_PTY_*` or a
|
|
204
|
+
coding agent's session variables are set, and when an ancestor process is a
|
|
205
|
+
coding agent or pmcp-pty. With `[host]` declared, the `shell.host_approval`
|
|
206
|
+
guard (deny by default; set `[hooks.guards.shell] host_approval` to change it)
|
|
207
|
+
blocks agents' commands that run `host approve` or touch the approvals
|
|
208
|
+
directory, and their edits there.
|
|
209
|
+
|
|
210
|
+
These checks run as your own user, like the agents themselves. They stop an
|
|
211
|
+
accident and an agent that was told to approve; they are not a security
|
|
212
|
+
boundary, since any process running as you can write the approvals directory
|
|
213
|
+
directly. A real boundary needs the approvals stored under a different user or
|
|
214
|
+
owned by root.
|
|
215
|
+
|
|
216
|
+
## Browser and desktop for agents
|
|
217
|
+
|
|
218
|
+
Claude Code and Codex offer browser and computer use only through their
|
|
219
|
+
desktop apps, not on a Linux server. Two MCP servers built from this
|
|
220
|
+
repository cover that ground for every runtime pmcp projects to:
|
|
221
|
+
|
|
222
|
+
- `pmcp-browser` (`crates/pmcp-plugin-browser-use`): an isolated Chromium,
|
|
223
|
+
headless, with a fresh profile per launch. It reaches public http(s) sites
|
|
224
|
+
only: every request goes through its own proxy, which refuses loopback,
|
|
225
|
+
private, link-local, metadata and CGNAT addresses and every port but 80 and 443. Local schemes such as `file:` are blocked in the page.
|
|
226
|
+
- `pmcp-desktop` (`crates/pmcp-plugin-computer-use`): an Xvfb desktop driven
|
|
227
|
+
through screenshots and XTEST input, for any X11 app.
|
|
228
|
+
|
|
229
|
+
Each runs in its own memory-capped systemd scope (2G and 512M by default),
|
|
230
|
+
and `pmcp-browser` allows two at a time on the host. Both have `doctor`
|
|
231
|
+
(read-only, with the exact fix) and `setup --plan`; root steps are printed,
|
|
232
|
+
never run. Both ship in the Linux platform package npm installs with PMCP
|
|
233
|
+
(glibc 2.35 or later), which does not put them on PATH. Declare them like
|
|
234
|
+
any MCP server with the bare name as `command`; `pmcp project` resolves it to
|
|
235
|
+
the installed binary, so pmcp.toml names no host path:
|
|
236
|
+
|
|
237
|
+
```toml
|
|
238
|
+
[mcp.pmcp-browser]
|
|
239
|
+
command = "pmcp-browser"
|
|
240
|
+
args = ["serve", "--approved", "<the directory pmcp harness host status reports>"]
|
|
241
|
+
|
|
242
|
+
[mcp.pmcp-desktop]
|
|
243
|
+
command = "pmcp-desktop"
|
|
244
|
+
args = ["serve", "--geometry", "1440x900x24"]
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
`pmcp doctor` reports where each resolved, or why not (no platform
|
|
248
|
+
package for this host, as on macOS); an unresolved name runs from PATH. An
|
|
249
|
+
absolute `command`, such as your own build, is kept as written.
|
|
250
|
+
|
|
251
|
+
The names avoid Claude Code's built-in `computer-use`. `--approved` is
|
|
252
|
+
optional: without it the browser is public-only and the desktop launches
|
|
253
|
+
nothing. `[host.browser] allow_private` and `[[host.desktop.launch]]` come
|
|
254
|
+
into force only through `pmcp harness host approve`. Running the browser
|
|
255
|
+
headed on the desktop's display also needs the managed Chromium policy that
|
|
256
|
+
`pmcp-browser setup --plan` prints for the operator to install.
|
|
257
|
+
|
|
258
|
+
## Claude permission rules
|
|
259
|
+
|
|
260
|
+
`[permissions.claude]` declares Claude Code permission rules. `pmcp project`
|
|
261
|
+
adds them to `permissions.allow`, `permissions.ask` and `permissions.deny` in
|
|
262
|
+
`.claude/settings.json` when `claude` is in `[targets] tools`:
|
|
263
|
+
|
|
264
|
+
```toml
|
|
265
|
+
[permissions.claude]
|
|
266
|
+
ask = ["Read(.env)", "Read(**/*.bak.*)", "Bash(git push:*)", "Bash(git stash:*)"]
|
|
267
|
+
deny = ["WebFetch(domain:internal.example)"]
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
| Table | Keys |
|
|
271
|
+
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
272
|
+
| `[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. |
|
|
273
|
+
|
|
274
|
+
Each rule is a Claude permission expression: a tool name (`Bash`, `Read`,
|
|
275
|
+
`Edit`, `Write`, `Glob`, `Grep`, `WebFetch`, `WebSearch`, `Agent`, `Task`,
|
|
276
|
+
`Skill` and the other built-in tools), optionally followed by a specifier in
|
|
277
|
+
parentheses, or an MCP name such as `mcp__docs` or `mcp__docs__search`.
|
|
278
|
+
`WebFetch` takes `domain:<host>`; a `Bash` prefix `:*` must end the specifier.
|
|
279
|
+
pmcp checks only this structure. It never expands globs or rewrites paths, so
|
|
280
|
+
`Read(.env)` stays `Read(.env)`.
|
|
281
|
+
|
|
282
|
+
pmcp owns only the entries it inserted, and records them in `pmcp.lock`. A rule
|
|
283
|
+
that was already in the list is borrowed: it satisfies the declaration but
|
|
284
|
+
stays unmanaged and survives when the declaration goes. Entries pmcp did not
|
|
285
|
+
write are never removed or reordered, and `defaultMode` and every other
|
|
286
|
+
setting are left alone. A missing table declares nothing; an empty list, a
|
|
287
|
+
removed list or a removed table removes the entries pmcp owns in that list.
|
|
288
|
+
|
|
289
|
+
`pmcp project --check` reports `drift` for a declared rule that is missing and
|
|
290
|
+
for an owned rule that is no longer declared. It reports `conflict` when an
|
|
291
|
+
owned entry was edited or removed by hand, or when the list is not a list of
|
|
292
|
+
strings; `pmcp project` then refuses to write until the native file is
|
|
293
|
+
reviewed. `pmcp doctor` shows how many entries each list owns and borrows, or
|
|
294
|
+
`none declared`.
|
|
295
|
+
|
|
296
|
+
A declared rule that also sits unmanaged in another list, for example a hand
|
|
297
|
+
written `deny` for a rule declared in `ask`, is an `overlap`. Claude's own
|
|
298
|
+
precedence decides it, so `--check` and `doctor` show it as a warning and
|
|
299
|
+
nothing is removed or refused. `pmcp project` also refuses to write when
|
|
300
|
+
`.claude/settings.json` changed while it was planning; run it again.
|
|
301
|
+
|
|
302
|
+
Codex is never written: its native command rules are a separate feature, and
|
|
303
|
+
the hook guards stay its enforcement.
|
|
304
|
+
|
|
67
305
|
## Unified project MCP configuration
|
|
68
306
|
|
|
69
307
|
Antigravity receives a native project plugin at .agents/plugins/pmcp-mcp with
|
|
@@ -101,7 +339,8 @@ timeout = 120000
|
|
|
101
339
|
url means Streamable HTTP; Gemini receives httpUrl. Legacy SSE is not imported
|
|
102
340
|
as HTTP. headers contains literal nonsecret headers, header_env maps header
|
|
103
341
|
names to environment variable names, and bearer_token_env_var references a
|
|
104
|
-
token without writing its value.
|
|
342
|
+
token without writing its value. With auth = "native" (the default), each runtime
|
|
343
|
+
retains its own OAuth session.
|
|
105
344
|
Antigravity HTTP header projection is not qualified and is rejected; explicitly
|
|
106
345
|
limit those servers to supported targets. tools maps to Gemini includeTools and
|
|
107
346
|
Codex enabled_tools; it is not a cross-runtime security boundary. Native timeout
|
|
@@ -181,8 +420,586 @@ See the [OpenCode MCP configuration](https://opencode.ai/docs/mcp-servers/),
|
|
|
181
420
|
[Agent Skills](https://opencode.ai/docs/skills/) and
|
|
182
421
|
[configuration precedence](https://opencode.ai/docs/config/).
|
|
183
422
|
|
|
423
|
+
## Shared remote MCP authentication
|
|
424
|
+
|
|
425
|
+
Use `auth = "pmcp"` to let Claude, Codex, Gemini, Antigravity, Grok and
|
|
426
|
+
OpenCode share one remote MCP login (only the Claude and Codex entries have run
|
|
427
|
+
live):
|
|
428
|
+
|
|
429
|
+
```toml
|
|
430
|
+
[mcp.remote]
|
|
431
|
+
url = "https://example.com/mcp"
|
|
432
|
+
auth = "pmcp"
|
|
433
|
+
targets = ["claude", "codex"]
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
Run `pmcp project`, then `pmcp mcp login remote`. The projected stdio entries
|
|
437
|
+
run `pmcp project exec-mcp remote`; the proxy connects to the declared Streamable
|
|
438
|
+
HTTP endpoint. The login command prints an authorization URL without opening
|
|
439
|
+
a browser. Complete the loopback callback or paste the callback URL or code.
|
|
440
|
+
For a later completion, use `pmcp mcp login remote --no-wait`, then
|
|
441
|
+
`pmcp mcp login remote --code <callback-url-or-code>`. Issuers must support
|
|
442
|
+
PKCE S256 and dynamic client registration, or supply `--client-id` for a
|
|
443
|
+
pre-registered public client. Discovery follows the resource's OAuth metadata.
|
|
444
|
+
|
|
445
|
+
For bearer authentication, declare `bearer_token_env_var` and run login with
|
|
446
|
+
that variable set, or pass `--bearer-env <variable-name>`. The value is stored
|
|
447
|
+
privately and is never projected into runtime configuration or printed.
|
|
448
|
+
`pmcp mcp status remote` reports only credential presence, UTC expiry and scopes.
|
|
449
|
+
`pmcp mcp logout remote` clears the local credentials and requests remote
|
|
450
|
+
revocation when the issuer advertises it.
|
|
451
|
+
|
|
452
|
+
Credentials live in `$XDG_STATE_HOME/pmcp/credentials/<name>.json`, defaulting to
|
|
453
|
+
`~/.local/state/pmcp/credentials/`. Files use mode 0600 and the credential
|
|
454
|
+
directory uses mode 0700. Credentials are bound to the declared server URL.
|
|
455
|
+
Processes reread credentials under an OS lock before refreshing; refresh-token
|
|
456
|
+
rotation is stored atomically. This implementation requires the `flock` command.
|
|
457
|
+
An expired or revoked session reports an authentication error rather than
|
|
458
|
+
starting interactive login inside the MCP connection.
|
|
459
|
+
|
|
460
|
+
The CLI must be installed in the project or available as `pmcp` on PATH.
|
|
461
|
+
Codex receives environment-name references for `XDG_STATE_HOME` and any declared
|
|
462
|
+
header environment variables. `auth = "native"` preserves existing entries,
|
|
463
|
+
OAuth ownership and env_from behavior. Provider authentication remains native.
|
|
464
|
+
|
|
465
|
+
## Hooks
|
|
466
|
+
|
|
467
|
+
`pmcp project` compiles `[hooks]`, `[sessions]`, `[git]` and `[logging]` into
|
|
468
|
+
`.agents/pmcp-hooks/policy.json`, copies the hook beside it as `hook.mjs` (a
|
|
469
|
+
small loader) and `hook-body.mjs`, and registers `hook.mjs` in
|
|
470
|
+
`.claude/settings.json` and `.codex/hooks.json` for the events the declared
|
|
471
|
+
features use. Gemini, Antigravity, Grok and OpenCode are opt-in: name them in
|
|
472
|
+
`[hooks] targets` and pmcp registers the same hook in their files (see
|
|
473
|
+
[Runtime support](#runtime-support)). `pmcp.lock` pins the hash of `policy.json`; the hook refuses to
|
|
474
|
+
act on a policy that does not match it, so every policy change is a reviewed
|
|
475
|
+
projection. Codex shows changed entries under `/hooks` as needing review;
|
|
476
|
+
untrusted hooks do not run. Each Codex, Claude and Grok entry carries a
|
|
477
|
+
`statusMessage` such as `pmcp session start` or `pmcp before tool`: Codex
|
|
478
|
+
lists hooks under that name, and Claude and Grok show it while the hook runs.
|
|
479
|
+
Gemini entries keep their `name` (`pmcp-<event>`), which is part of the
|
|
480
|
+
identity Gemini trusts.
|
|
481
|
+
|
|
482
|
+
The hook keeps two per-user caches under `$XDG_CACHE_HOME/pmcp` (default
|
|
483
|
+
`~/.cache/pmcp`), never in the project: Node's compile cache for the body
|
|
484
|
+
(`hook-compile/`) and the last integrity verdict per `policy.json`
|
|
485
|
+
(`hook-verified.json`). A verdict is reused only while neither `policy.json`
|
|
486
|
+
nor `pmcp.lock` has been written since. Either cache can be missing or
|
|
487
|
+
unwritable without changing a decision; `PMCP_HOOK_COMPILE_CACHE=off` turns the
|
|
488
|
+
compile cache off.
|
|
489
|
+
|
|
490
|
+
Every feature is opt-in: a table that is missing turns its feature off, and a
|
|
491
|
+
declared table, even an empty one, turns it on. The exceptions are documented
|
|
492
|
+
where they apply: `[git]` features detect git (`enabled = "auto"`),
|
|
493
|
+
`[git.shared_checkout]` is on in any git checkout once the bundle exists, and
|
|
494
|
+
logging falls back to its defaults rather than to no logging. The bundle is
|
|
495
|
+
projected only when `[hooks]` declares guards or checks, a `[sessions.*]`
|
|
496
|
+
feature table is declared, `[git.shared_checkout]` or `[git.worktrees.sync]` is
|
|
497
|
+
declared, or `[git.mainline.deliver]` keeps `refuse_direct_push`.
|
|
498
|
+
|
|
499
|
+
### `[hooks]`
|
|
500
|
+
|
|
501
|
+
| Key | Type | Default | Meaning |
|
|
502
|
+
| -------------------- | ------------ | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
503
|
+
| `targets` | list | `[targets] tools` limited to `claude`, `codex` | Runtimes that receive the hook bundle: `claude`, `codex`, `gemini`, `antigravity`, `grok`, `opencode`. The last four are used only when listed here. |
|
|
504
|
+
| `ask_fallback` | string | `"deny"` | What an ask becomes on a runtime without ask (Codex, Gemini, Antigravity, Grok, OpenCode): `deny`, `warn`, or `refuse` to make projection fail while any guard may ask. |
|
|
505
|
+
| `error_log` | bool or path | `true` | `true` writes JSONL logs under the state directory's `logs/`; a project-relative path writes one file there instead; `false` turns hook logging off. |
|
|
506
|
+
| `emergency_off_file` | path | none | While this file exists every guard passes. `~`, `$HOME/` and absolute paths are allowed; other paths are relative to the project. |
|
|
507
|
+
|
|
508
|
+
### `[hooks.guards.<group>.<name>]`
|
|
509
|
+
|
|
510
|
+
Each built-in guard is one table. `mode` is the only key the option-less
|
|
511
|
+
guards take; an unknown option is an error. Modes: `deny` and `ask` replace
|
|
512
|
+
the guard's verdict with that mode, `warn` turns the reason into context the
|
|
513
|
+
agent reads, `off` drops the guard, and `graded` keeps the guard's own split
|
|
514
|
+
between ask and deny.
|
|
515
|
+
|
|
516
|
+
| Table | Default mode | Modes | Refuses |
|
|
517
|
+
| ------------------------------------------ | ------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
|
518
|
+
| `[hooks.guards.shell.in_place_edit]` | deny | deny, ask, warn, off | `sed -i`, `perl -i`, `awk -i inplace`: edits without a diff. |
|
|
519
|
+
| `[hooks.guards.shell.heredoc]` | deny | deny, ask, warn, off | Heredocs and here-strings, whose body the shell expands silently. |
|
|
520
|
+
| `[hooks.guards.shell.stdin_interpreter]` | ask | deny, ask, warn, off | An interpreter reading its program from stdin (`python3 -`, `cat x.py \| python3`). |
|
|
521
|
+
| `[hooks.guards.shell.compose_teardown]` | deny | deny, ask, warn, off | `docker compose down`, and `stop`, `rm` or `kill` with no service named: they hit every service. |
|
|
522
|
+
| `[hooks.guards.shell.secret_exfiltration]` | graded | deny, ask, warn, off, graded | Reading a credential asks; sending one over the network, or changing a live one, denies. |
|
|
523
|
+
| `[hooks.guards.shell.host_approval]` | deny | deny, ask, warn, off | `host approve`, and commands or edits touching the host approvals directory. On by itself when `[host]` is declared. |
|
|
524
|
+
| `[hooks.guards.git.push_without_verify]` | deny | deny, ask, warn, off | `git push --no-verify`. |
|
|
525
|
+
| `[hooks.guards.git.forced_branch_move]` | deny | deny, ask, warn, off | Forcing a branch that is checked out in another working tree. |
|
|
526
|
+
| `[hooks.guards.git.gate_bypass_env]` | deny | deny, ask, warn, off | Setting a named gate-bypass variable where it takes effect, and optionally `--no-verify` on any git command. |
|
|
527
|
+
| `[hooks.guards.git.stage_all]` | deny | deny, ask, warn, off | `git add -A`, `git add .`, `git commit -a` and similar; stage explicit paths. |
|
|
528
|
+
|
|
529
|
+
Options:
|
|
530
|
+
|
|
531
|
+
- `[hooks.guards.shell.secret_exfiltration]`: `extra_secret_paths` (list of
|
|
532
|
+
case-insensitive regular expressions, default `[]`), and
|
|
533
|
+
`[[hooks.guards.shell.secret_exfiltration.value_commands]]` entries for a
|
|
534
|
+
CLI that prints or publishes secret values: `binary` (required), `read`
|
|
535
|
+
(verbs that print a value, so reading asks) and `publish` (verbs that change
|
|
536
|
+
a live value, so they deny). Built in are `.env` files, `.dev.vars`, private
|
|
537
|
+
keys, `.npmrc`, `.netrc`, `auth.json` and service-account files; a file whose
|
|
538
|
+
name merely contains "secret" or "credential" is not one, so list such files
|
|
539
|
+
in `extra_secret_paths`. Only a file a command reads counts: a search
|
|
540
|
+
pattern, a sed or awk script, a jq filter or `-e` code that mentions `.env`
|
|
541
|
+
does not.
|
|
542
|
+
- `[hooks.guards.git.gate_bypass_env]`: `names` (variable names, default `[]`)
|
|
543
|
+
and `no_verify` (boolean, default `true`).
|
|
544
|
+
|
|
545
|
+
A mention is not a match: commands are parsed into steps, so
|
|
546
|
+
`git commit -m "never git push --no-verify"` and `echo 'cat <<EOF'` pass. A
|
|
547
|
+
command the parser cannot read is judged by a conservative pattern instead.
|
|
548
|
+
|
|
549
|
+
### `[[hooks.guards.custom]]`
|
|
550
|
+
|
|
551
|
+
A project script under `.agents/guards/` that decides like a built-in guard.
|
|
552
|
+
|
|
553
|
+
| Key | Type | Default | Meaning |
|
|
554
|
+
| ------------ | --------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
555
|
+
| `name` | string | required | `^[a-z0-9][a-z0-9-]*$`, unique across custom, shell and edit entries. |
|
|
556
|
+
| `command` | argv list | required | The first or second element is the script, which must exist inside `.agents/guards/`; its sha256 is pinned in `policy.json`. |
|
|
557
|
+
| `targets` | list | required | Any `[hooks] targets` runtime. A runtime in `[hooks] targets` runs it in the hook bundle; otherwise Codex, Gemini and Antigravity use the shell adapter, and Claude, Grok and OpenCode are an error. |
|
|
558
|
+
| `timeout_ms` | integer | `15000` | 100 to 60000. |
|
|
559
|
+
| `on` | string | `"before_shell"` | `before_shell` or `after_edit`. |
|
|
560
|
+
|
|
561
|
+
The script receives the JSON contract described under
|
|
562
|
+
[Operator shell guards](#operator-shell-guards). Custom guards have no `mode`.
|
|
563
|
+
|
|
564
|
+
### `[hooks.checks.after_edit]` and `[hooks.checks.on_stop]`
|
|
565
|
+
|
|
566
|
+
Checks report through context and never block; a check that cannot run is
|
|
567
|
+
logged and stays quiet.
|
|
568
|
+
|
|
569
|
+
| Table | Key | Type | Default | Meaning |
|
|
570
|
+
| --------------------------- | ------------------ | --------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
571
|
+
| `[hooks.checks.after_edit]` | `validator_glob` | glob | required | Validator scripts inside the project; after an edit, only the validators whose directory owns an edited path run. |
|
|
572
|
+
| | `command` | argv list | required | Must contain `{validator}`, replaced by the validator's path. Runs directly, never through a shell. |
|
|
573
|
+
| | `debounce_seconds` | number | `60` | One run per validator per window. |
|
|
574
|
+
| | `report` | string | `"context"` | The only value. |
|
|
575
|
+
| `[hooks.checks.on_stop]` | `project_check` | boolean | `true` | After a turn that edited files, run `pmcp project --check` and report drift. |
|
|
576
|
+
| | `report` | string | `"context"` | The only value. |
|
|
577
|
+
|
|
578
|
+
The stop check runs the checkout's own pmcp (`node_modules`), else the CLI that
|
|
579
|
+
last projected this checkout on this machine (recorded in the state directory
|
|
580
|
+
as `projector.json`), and only at the version `pmcp.lock` records. A pmcp on
|
|
581
|
+
`PATH` is never used. When none matches, the session hears
|
|
582
|
+
`projecting pmcp not available` once instead of a drift report.
|
|
583
|
+
|
|
584
|
+
### Runtime support
|
|
585
|
+
|
|
586
|
+
From the measured capability files in `docs/hooks/capabilities/` (Claude Code
|
|
587
|
+
2.1.303, Codex 0.163.0, including live sessions). `pmcp doctor` prints the same
|
|
588
|
+
table for your project, with Codex trust.
|
|
589
|
+
|
|
590
|
+
| Feature | Claude Code | Codex |
|
|
591
|
+
| ---------------------------------------------------------------------------------------------- | -------------------------- | ---------------------------------------- |
|
|
592
|
+
| sessions registry, pause, leases, broadcast | measured | measured |
|
|
593
|
+
| `[sessions.roles.<name>]` | works; not live-measured | unsupported: Codex sends no `agent_type` |
|
|
594
|
+
| `[git.shared_checkout]`, `[git.worktrees.sync]`, `[git.mainline.deliver]` | measured | measured |
|
|
595
|
+
| heredoc, compose_teardown, push_without_verify, forced_branch_move, gate_bypass_env, stage_all | measured | measured |
|
|
596
|
+
| in_place_edit, stdin_interpreter, secret_exfiltration (ask) | ask not measured | ask lowered by `ask_fallback` |
|
|
597
|
+
| host_approval | works; not live-measured | works; not live-measured |
|
|
598
|
+
| `[hooks.checks.after_edit]` | measured | measured |
|
|
599
|
+
| `[hooks.checks.on_stop]` | measured, in the same turn | at the next prompt |
|
|
600
|
+
| `[[hooks.guards.custom]]` | not measured | not measured |
|
|
601
|
+
| `[ui.claude]` | Claude only | not applicable |
|
|
602
|
+
|
|
603
|
+
Codex limits that shape the projection:
|
|
604
|
+
|
|
605
|
+
- Codex has no ask. An ask becomes `ask_fallback` (`deny` by default).
|
|
606
|
+
- Codex sends no `agent_type`, so roles cannot apply there.
|
|
607
|
+
- Codex rejects context on Stop, so Stop notices are delivered at the next
|
|
608
|
+
prompt.
|
|
609
|
+
- Codex clamps a SessionEnd hook to 3 s; pmcp projects at most 3 s for it.
|
|
610
|
+
- Codex has no Notification event.
|
|
611
|
+
- Codex's own command filter rejects a fully quoted executable before any hook
|
|
612
|
+
runs; use the ordinary unquoted form.
|
|
613
|
+
|
|
614
|
+
Gemini CLI 0.63.0, Antigravity (`agy`) 1.4.2, Grok 1.0.62 and OpenCode 1.18.33
|
|
615
|
+
are opt-in `[hooks] targets`. The pmcp bundle ran live on each in the same
|
|
616
|
+
thirteen scenarios as Claude Code and Codex, judged from each runtime's own
|
|
617
|
+
transcript; the `live` block of each capability file names the runs. A context
|
|
618
|
+
a runtime does not deliver at an event is held and delivered at the next event
|
|
619
|
+
that does, and that was measured live too. On OpenCode, prompt context goes
|
|
620
|
+
into the system prompt, which OpenCode does not store, so its delivery is shown
|
|
621
|
+
by a probe rather than by the prompt scenario. agy runs prompt policies on
|
|
622
|
+
every turn: its counter resets per turn.
|
|
623
|
+
|
|
624
|
+
| Feature | Gemini | Antigravity | Grok | OpenCode |
|
|
625
|
+
| ------------------------------------------- | ---------------------------- | ----------------------------- | ---------------------------- | ---------------------------- |
|
|
626
|
+
| refusing a tool call (guards, pause, git) | measured deny | measured deny | measured deny | measured (thrown error) |
|
|
627
|
+
| context (broadcast, warnings) | start, prompt, after tool | first model call, Stop | tool events, Stop | start, prompt, after tool |
|
|
628
|
+
| `[sessions.registry]` | every event | tool events, first call, Stop | every event | every event |
|
|
629
|
+
| `[sessions.roles.<name>]` | unsupported: no `agent_type` | unsupported: no `agent_type` | unsupported: no `agent_type` | unsupported: no `agent_type` |
|
|
630
|
+
| ask (in_place_edit, stdin_interpreter, ...) | lowered by `ask_fallback` | lowered by `ask_fallback` | lowered by `ask_fallback` | lowered by `ask_fallback` |
|
|
631
|
+
| `[hooks.checks.on_stop]` | at the next delivering event | Stop continues once | in the same turn | at the next prompt |
|
|
632
|
+
| `[[hooks.guards.custom]]` | not measured | not measured | not measured | not measured |
|
|
633
|
+
|
|
634
|
+
Where each runtime's projection goes, and what it needs:
|
|
635
|
+
|
|
636
|
+
- Gemini: `.gemini/settings.json` `hooks`, timeouts in milliseconds. Gemini
|
|
637
|
+
ignores project settings in a folder the user has not trusted, and records
|
|
638
|
+
each new hook in `~/.gemini/trusted_hooks.json`; `pmcp doctor` reads both
|
|
639
|
+
and reports them, and never writes them. Trusting the folder is the user's
|
|
640
|
+
step in an interactive `gemini` session.
|
|
641
|
+
- Antigravity: one named set `pmcp` in `.agents/hooks.json`, beside the shell
|
|
642
|
+
adapter's `pmcp-shell`. agy denies a tool call whose hook names no decision,
|
|
643
|
+
so pmcp always writes one. agy has no session or prompt event: the first
|
|
644
|
+
model call of a conversation is the session start, the first of a later
|
|
645
|
+
turn the prompt. Whether that counter resets for a later prompt in an
|
|
646
|
+
interactive session is not measured. No trust step.
|
|
647
|
+
- Grok: grok also runs `.claude/settings.json` hooks, so with `claude` in
|
|
648
|
+
`[hooks] targets` pmcp writes only the Claude file and the hook recognises a
|
|
649
|
+
grok call by its payload; with Grok alone it writes `.grok/hooks/pmcp.json`.
|
|
650
|
+
Never both, or every check would run twice. Project hooks run only after
|
|
651
|
+
the user runs `/hooks-trust`; `pmcp doctor` reads
|
|
652
|
+
`~/.grok/trusted_folders.toml` without writing it.
|
|
653
|
+
- OpenCode: there are no shell hooks, so pmcp writes `.opencode/plugins/pmcp.js`,
|
|
654
|
+
a small plugin pinned in `pmcp.lock` that passes each call to the hook. A
|
|
655
|
+
refusal is thrown as an error; Stop (`session.idle`) only updates the
|
|
656
|
+
registry. No trust step.
|
|
657
|
+
|
|
658
|
+
`auth = "pmcp"` MCP servers project through `pmcp project exec-mcp` for every
|
|
659
|
+
runtime above.
|
|
660
|
+
|
|
661
|
+
## Sessions
|
|
662
|
+
|
|
663
|
+
Sessions coordinate agents working in one repository and its worktrees. State
|
|
664
|
+
lives in one directory shared by every checkout of the repository.
|
|
665
|
+
|
|
666
|
+
| `[sessions]` key | Type | Default | Meaning |
|
|
667
|
+
| ---------------- | ------ | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
668
|
+
| `store` | string | `"files"` | The only store. |
|
|
669
|
+
| `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 desk share one state. Outside git it is relative to the directory holding `pmcp.toml`. The hooks, the mod and the git commands resolve it the same way; so does `[git.mainline.gate] tree`. |
|
|
670
|
+
|
|
671
|
+
`store` and `state_dir` alone enable nothing; each feature has its own table:
|
|
672
|
+
|
|
673
|
+
| Table | Keys | Effect |
|
|
674
|
+
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
675
|
+
| `[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. |
|
|
676
|
+
| `[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 land 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. |
|
|
677
|
+
| `[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. |
|
|
678
|
+
| `[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 it lands. |
|
|
679
|
+
| `[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. |
|
|
680
|
+
|
|
681
|
+
These tables have no `mode`, except pause. Without `[sessions.registry]` no
|
|
682
|
+
session is recorded, and `[ui.claude]` refuses to project.
|
|
683
|
+
|
|
684
|
+
### `[sessions.mailbox]`
|
|
685
|
+
|
|
686
|
+
Addressed messages between sessions and the operator. A missing table leaves
|
|
687
|
+
the mailbox off; a declared one, even empty, turns it on.
|
|
688
|
+
|
|
689
|
+
| Key | Type | Default | Meaning |
|
|
690
|
+
| --------------- | ------ | ------- | --------------------------------------------------------------------------- |
|
|
691
|
+
| `enabled` | bool | `true` | `false` keeps the table but turns the mailbox off. |
|
|
692
|
+
| `ttl_minutes` | number | `1440` | Default lifetime of a message; `--ttl` overrides it per message. |
|
|
693
|
+
| `max_delivered` | number | `5` | At most this many new messages are shown at once, plus a count of the rest. |
|
|
694
|
+
| `audit` | bool | `true` | Append a line per sent, delivered, acked and expired event. |
|
|
695
|
+
| `wake` | bool | `false` | Wake idle recipients on every send, as `--wake` does for one message. |
|
|
696
|
+
|
|
697
|
+
Each message is one file, `<state>/messages/<id>.json`, created atomically and
|
|
698
|
+
never rewritten: `id`, `from` (session and alias), `to`, `subject`, `body`,
|
|
699
|
+
`createdAt`, `expiresAt`, `replyTo`, `once`. `to` lists selectors: `all`,
|
|
700
|
+
`session:<id>` (a prefix of at least eight characters works), `alias:<name>`,
|
|
701
|
+
`role:<name>` (a `[sessions.roles]` name or the agent type), or `desk:<path>`
|
|
702
|
+
(the desk's path, or its directory name). A message to `all` reaches the
|
|
703
|
+
sessions that were running when it was sent; a session the registry records
|
|
704
|
+
later does not get earlier broadcasts. Delivery and acknowledgement are
|
|
705
|
+
empty markers under `<state>/inbox/<session>/`, so a message is never edited
|
|
706
|
+
for them. `<state>/messages.jsonl` is the append-only audit.
|
|
707
|
+
|
|
708
|
+
The hooks deliver each unacknowledged message addressed to a session once,
|
|
709
|
+
through that runtime's context channel; on a runtime that does not show
|
|
710
|
+
context at an event, the notice is held for the next one that does. Later
|
|
711
|
+
events notice only messages that arrived since, with a count of earlier
|
|
712
|
+
unacknowledged ones. Delivery is recorded and never counts as an
|
|
713
|
+
acknowledgement. A message sent with `--once` says it is a one-time request,
|
|
714
|
+
so the recipient does not keep its instructions as standing rules.
|
|
715
|
+
|
|
716
|
+
```sh
|
|
717
|
+
pmcp sessions send --to alias:reviewer --to role:lander --subject deploy --once "Hold the deploy until 14:00"
|
|
718
|
+
echo "longer body" | pmcp sessions send --to all -
|
|
719
|
+
pmcp sessions inbox [--session <id>] [--all] [--json]
|
|
720
|
+
pmcp sessions ack <id>... [--session <id>]
|
|
721
|
+
pmcp sessions reply <id> "Done"
|
|
722
|
+
pmcp sessions send --wake --to alias:reviewer "CI is green again"
|
|
723
|
+
pmcp sessions sweep
|
|
724
|
+
```
|
|
725
|
+
|
|
726
|
+
A recipient that is idle sees mail only at its next event. With `--wake`, or
|
|
727
|
+
`wake = true` in the table, `send` and `reply` also start a turn in each idle
|
|
728
|
+
recipient whose runtime allows it, and the woken session's hooks then deliver
|
|
729
|
+
the mail as usual; the wake itself carries only a count, the subjects and one
|
|
730
|
+
exact command to run, `pmcp sessions inbox --session <id>`. Each attempt is an
|
|
731
|
+
audit line (`woken`, with the transport and channel), and `pmcp doctor` shows
|
|
732
|
+
each live session's last wake.
|
|
733
|
+
|
|
734
|
+
- Any runtime hosted by pmcp-pty: the session-start hook records the host's
|
|
735
|
+
socket, session and instance from `PMCP_PTY_*` when the host is the
|
|
736
|
+
runtime's parent or grandparent (a runtime started from a hosted session's
|
|
737
|
+
shell inherits the variables but is not recorded). `send --wake` asks the
|
|
738
|
+
host for one short `turn`; the host picks the channel (Claude inbox, OpenCode
|
|
739
|
+
server, Codex queue, Grok leader or a guarded screen write) and its receipt
|
|
740
|
+
is in `send --json`. A refused turn, such as one behind an open dialog,
|
|
741
|
+
leaves the mail for the next event. The same hooks report each turn's start
|
|
742
|
+
and end (with the last assistant message) and permission notices to the
|
|
743
|
+
host, which ends a turn on that before trusting the screen. A hosted
|
|
744
|
+
session gets mail only on the wake turn itself (a prompt starting
|
|
745
|
+
`pmcp mail:`): as context on other prompts the notice took over turns
|
|
746
|
+
pmcp-pty sent. The two items below are for sessions pmcp-pty does not host.
|
|
747
|
+
- Claude Code: through the session's documented
|
|
748
|
+
[cross-session inbox](https://code.claude.com/docs/en/cross-session-messaging),
|
|
749
|
+
found in `~/.claude/sessions/<pid>.json`, which pmcp only reads. The target's
|
|
750
|
+
own inbound controls apply: a session in `bypassPermissions` without
|
|
751
|
+
`crossSessionInbound = "accept"` holds the wake for approval, and a wake can
|
|
752
|
+
approve nothing.
|
|
753
|
+
- OpenCode: `POST /session/<id>/prompt_async` on the server the session runs
|
|
754
|
+
on, which the generated plugin records; HTTP basic auth from
|
|
755
|
+
`OPENCODE_SERVER_PASSWORD` (user `OPENCODE_SERVER_USERNAME`, default
|
|
756
|
+
`opencode`).
|
|
757
|
+
- Codex, Gemini, Antigravity and Grok outside pmcp-pty have no supported way to
|
|
758
|
+
start a turn in a running session; their mail waits for the next event.
|
|
759
|
+
`pmcp sessions status` and `pmcp doctor` show which live sessions can be
|
|
760
|
+
woken.
|
|
761
|
+
|
|
762
|
+
`--session <id>` acts as that session and `--by <name>` as a named sender
|
|
763
|
+
outside one; the notice a session receives spells out its commands with its
|
|
764
|
+
own `--session`. Those commands, and the wake text, say `pmcp` only when the
|
|
765
|
+
`pmcp` on PATH is the CLI that projects this checkout (its own install, else
|
|
766
|
+
the one that last projected it); otherwise they name that CLI as
|
|
767
|
+
`node '<path>/dist/cli.js'`, and `pmcp doctor` warns. Without either, a command run inside a runtime acts as that
|
|
768
|
+
runtime's session: the live session whose runtime process is its nearest
|
|
769
|
+
ancestor, else the id the runtime exposes to tool commands
|
|
770
|
+
(`CLAUDE_CODE_SESSION_ID`, `CODEX_THREAD_ID`, `ANTIGRAVITY_CONVERSATION_ID`,
|
|
771
|
+
`GROK_SESSION_ID`; Gemini and OpenCode expose none). When it cannot tell, it
|
|
772
|
+
warns and acts as `operator`. `sweep` also deletes expired messages and their
|
|
773
|
+
markers.
|
|
774
|
+
|
|
775
|
+
`pmcp sessions status` and `pmcp doctor` name live sessions that should be
|
|
776
|
+
restarted to get the current hooks: one started under an older (or untracked)
|
|
777
|
+
`policy.json`, which matters when new hook events were added, and a Codex
|
|
778
|
+
session started before `.codex/hooks.json` last changed, since Codex reads its
|
|
779
|
+
hook file only when a session starts.
|
|
780
|
+
|
|
781
|
+
With the mailbox on, `pmcp sessions broadcast` also sends its text as a
|
|
782
|
+
message to `all`, and the mailbox delivers it instead of
|
|
783
|
+
`[sessions.broadcast]`; `broadcast.json` and each session's `seenBroadcast`
|
|
784
|
+
are still written, so `pmcp sessions status`, the fleet snapshot and the
|
|
785
|
+
Claude status band read broadcasts as before. `unbroadcast` withdraws those
|
|
786
|
+
messages too.
|
|
787
|
+
|
|
788
|
+
## Git workflow
|
|
789
|
+
|
|
790
|
+
| `[git]` key | Type | Default | Meaning |
|
|
791
|
+
| ----------- | --------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
|
|
792
|
+
| `enabled` | `"auto"`, true, false | `"auto"` | `auto` turns the git features on when the project is a git checkout; `false` turns all of them off. |
|
|
793
|
+
| `remote` | string | `origin` if present, else the first remote | |
|
|
794
|
+
| `mainline` | string or table | the remote's HEAD branch, else `main` | A string names the branch; a table (`[git.mainline]` with `branch`) also holds gate, deliver and sync. |
|
|
795
|
+
|
|
796
|
+
`[git.shared_checkout]` warns a session working in the main checkout of a
|
|
797
|
+
repository that also has worktrees (desks), tracks the files it edits there,
|
|
798
|
+
and names unlanded leftovers, because they block syncing the shared main for
|
|
799
|
+
everyone. Keys: `enabled` (`"auto"` default, following `[git] enabled`, or a
|
|
800
|
+
boolean), `warn_on_session`, `track_edits`, `warn_claimants` (booleans, default
|
|
801
|
+
`true`). It is on in any git checkout without a table, once something else
|
|
802
|
+
enables the hook bundle.
|
|
803
|
+
|
|
804
|
+
`[git.worktrees]` configures desks for `pmcp git worktree`:
|
|
805
|
+
|
|
806
|
+
| Key | Type | Default |
|
|
807
|
+
| ---------------- | --------- | -------------------------- |
|
|
808
|
+
| `root` | string | `".claude/worktrees"` |
|
|
809
|
+
| `branch_prefix` | string | `"worktree-"` |
|
|
810
|
+
| `alias_pattern` | regex | `"^[a-z][a-z0-9-]{1,30}$"` |
|
|
811
|
+
| `bootstrap` | argv list | none |
|
|
812
|
+
| `link_from_main` | list | `[]` |
|
|
813
|
+
|
|
814
|
+
`[git.worktrees.sync]` (opt-in) keeps each desk on the mainline when moving it
|
|
815
|
+
loses nothing: `on_session_start` (`"fetch_and_move"` default, `"move"`,
|
|
816
|
+
`"off"`), `between_prompts` (`"move_if_light"` default, `"off"`: move only when
|
|
817
|
+
no install is needed), `install_after_move` (`"off"` default, `"background"`,
|
|
818
|
+
`"foreground"`) and `notice_paths` (paths whose change is announced to the
|
|
819
|
+
session). Installs never block a session.
|
|
820
|
+
|
|
821
|
+
`[git.mainline.gate]`: `command` (argv; no gate when missing), `tree` (the
|
|
822
|
+
gate's worktree, default `<state dir>/gate/tree`; a relative path is relative to
|
|
823
|
+
the main checkout, like `state_dir`), `lock_wait_seconds`
|
|
824
|
+
(default `5400`).
|
|
825
|
+
|
|
826
|
+
`[git.mainline.deliver]` enables `pmcp git deliver`, which replays commits onto
|
|
827
|
+
the fetched mainline, runs the gate, and pushes one delivery at a time:
|
|
828
|
+
`attempts` (default `3`), `refuse_direct_push` (default `true`: a hook refuses
|
|
829
|
+
`git push` from any checkout of this repository, so the mainline moves only
|
|
830
|
+
through delivery), `during_pause` (`"refuse"` default or `"allow"`),
|
|
831
|
+
`lease_wait_seconds` (default `3600`) and `notify` (argv run after a
|
|
832
|
+
delivery).
|
|
833
|
+
|
|
834
|
+
`[git.mainline.sync]` enables `pmcp git sync`, which moves the main checkout to
|
|
835
|
+
the mainline: `install` (argv), `install_when_changed` (paths; when no
|
|
836
|
+
`[sessions.leases]` are declared, these become an implicit `lockfile` lease),
|
|
837
|
+
`keep_identical_files` and `refuse_with_unlanded` (booleans, default `true`).
|
|
838
|
+
|
|
839
|
+
`[git.submodules]`: `follow = "clean_pins"` (the default when the table is
|
|
840
|
+
present) moves submodules to the pinned commit when they are clean; `"off"`
|
|
841
|
+
leaves them. Without the table submodules are not followed.
|
|
842
|
+
|
|
843
|
+
## Logging
|
|
844
|
+
|
|
845
|
+
| `[logging]` key | Type | Default | Allowed |
|
|
846
|
+
| --------------- | ------ | ------------------------------------------------ | ----------------------------------------- |
|
|
847
|
+
| `level` | string | `"info"` | `error`, `warn`, `info`, `debug`, `trace` |
|
|
848
|
+
| `format` | string | `"jsonl"` | `jsonl` only |
|
|
849
|
+
| `max_file_mb` | number | `20` | greater than 0 |
|
|
850
|
+
| `keep_days` | number | `14` | greater than 0 |
|
|
851
|
+
| `redact` | list | `["secret_values", "prompt_text", "env_values"]` | any subset |
|
|
852
|
+
| `components` | table | `{}` | `<component> = "<level>"` |
|
|
853
|
+
|
|
854
|
+
The `PMCP_LOG` environment variable overrides the level. `[hooks] error_log`
|
|
855
|
+
switches hook logging on or off. Read the logs with `pmcp logs`.
|
|
856
|
+
|
|
857
|
+
## Claude session panes
|
|
858
|
+
|
|
859
|
+
`[ui.claude]` installs the session panes into Claude Code: `sessions_pane`,
|
|
860
|
+
`status_band`, `commands` and `hold_foreign_edits`, all booleans defaulting to
|
|
861
|
+
`true`. `hold_foreign_edits` asks before editing a file another live session
|
|
862
|
+
edited. It needs `[sessions.registry]`, and is written only when `claude` is
|
|
863
|
+
in `[targets] tools`. Without the table nothing is installed. `pmcp doctor`
|
|
864
|
+
shows the projected switches, or a failure until `pmcp project` writes them; it
|
|
865
|
+
cannot tell whether a running Claude Code loaded the mod.
|
|
866
|
+
|
|
867
|
+
## A complete example
|
|
868
|
+
|
|
869
|
+
A project with two runtimes, the full guard set, sessions, the git workflow and
|
|
870
|
+
a team marketplace:
|
|
871
|
+
|
|
872
|
+
```toml
|
|
873
|
+
[catalog]
|
|
874
|
+
workspaces = [".", "packages/*"]
|
|
875
|
+
|
|
876
|
+
[targets]
|
|
877
|
+
tools = ["claude", "codex"]
|
|
878
|
+
|
|
879
|
+
[mcp.skills]
|
|
880
|
+
command = "node"
|
|
881
|
+
args = ["${PROJECT_ROOT}/node_modules/@modootoday/pmcp/dist/cli.js", "serve"]
|
|
882
|
+
|
|
883
|
+
[skills.deploy]
|
|
884
|
+
invocation = "user"
|
|
885
|
+
|
|
886
|
+
[agents.reviewer.claude]
|
|
887
|
+
tools = "Read, Grep, Glob"
|
|
888
|
+
model = "inherit"
|
|
889
|
+
effort = "high"
|
|
890
|
+
|
|
891
|
+
[hooks]
|
|
892
|
+
targets = ["claude", "codex"]
|
|
893
|
+
ask_fallback = "deny"
|
|
894
|
+
|
|
895
|
+
[hooks.guards.shell.in_place_edit]
|
|
896
|
+
mode = "ask"
|
|
897
|
+
|
|
898
|
+
[hooks.guards.shell.heredoc]
|
|
899
|
+
|
|
900
|
+
[hooks.guards.shell.stdin_interpreter]
|
|
901
|
+
|
|
902
|
+
[hooks.guards.shell.compose_teardown]
|
|
903
|
+
|
|
904
|
+
[hooks.guards.shell.host_approval]
|
|
905
|
+
|
|
906
|
+
[hooks.guards.shell.secret_exfiltration]
|
|
907
|
+
mode = "graded"
|
|
908
|
+
|
|
909
|
+
[[hooks.guards.shell.secret_exfiltration.value_commands]]
|
|
910
|
+
binary = "secrets-cli"
|
|
911
|
+
read = ["read", "env get"]
|
|
912
|
+
publish = ["deploy", "secret put", "secret delete"]
|
|
913
|
+
|
|
914
|
+
[hooks.guards.git.push_without_verify]
|
|
915
|
+
|
|
916
|
+
[hooks.guards.git.forced_branch_move]
|
|
917
|
+
|
|
918
|
+
[hooks.guards.git.stage_all]
|
|
919
|
+
|
|
920
|
+
[hooks.guards.git.gate_bypass_env]
|
|
921
|
+
names = ["ALLOW_DIRECT_PUSH", "GATE_LOCK_HELD"]
|
|
922
|
+
|
|
923
|
+
[[hooks.guards.custom]]
|
|
924
|
+
name = "source-formatting"
|
|
925
|
+
command = ["node", ".agents/guards/source-formatting.mjs"]
|
|
926
|
+
targets = ["codex"]
|
|
927
|
+
on = "after_edit"
|
|
928
|
+
|
|
929
|
+
[hooks.checks.after_edit]
|
|
930
|
+
validator_glob = ".agents/skills/*/scripts/validate.ts"
|
|
931
|
+
command = ["node", "{validator}"]
|
|
932
|
+
|
|
933
|
+
[hooks.checks.on_stop]
|
|
934
|
+
|
|
935
|
+
[sessions]
|
|
936
|
+
state_dir = ".pmcp-state"
|
|
937
|
+
|
|
938
|
+
[sessions.registry]
|
|
939
|
+
|
|
940
|
+
[sessions.pause]
|
|
941
|
+
|
|
942
|
+
[sessions.broadcast]
|
|
943
|
+
|
|
944
|
+
[sessions.mailbox]
|
|
945
|
+
ttl_minutes = 1440
|
|
946
|
+
max_delivered = 5
|
|
947
|
+
|
|
948
|
+
[sessions.leases.lockfile]
|
|
949
|
+
path = "package-lock.json"
|
|
950
|
+
blocks = [["npm", "install"], ["npm", "ci"], ["pmcp", "git", "deliver"]]
|
|
951
|
+
|
|
952
|
+
[sessions.roles.lander]
|
|
953
|
+
allow_commands = [["pmcp", "git", "deliver"], ["git", "log"], ["git", "status"]]
|
|
954
|
+
|
|
955
|
+
[git]
|
|
956
|
+
remote = "origin"
|
|
957
|
+
|
|
958
|
+
[git.mainline]
|
|
959
|
+
branch = "main"
|
|
960
|
+
|
|
961
|
+
[git.mainline.gate]
|
|
962
|
+
command = ["npm", "test"]
|
|
963
|
+
|
|
964
|
+
[git.mainline.deliver]
|
|
965
|
+
|
|
966
|
+
[git.mainline.sync]
|
|
967
|
+
install = ["npm", "ci"]
|
|
968
|
+
install_when_changed = ["package-lock.json"]
|
|
969
|
+
|
|
970
|
+
[git.worktrees]
|
|
971
|
+
bootstrap = ["node", "scripts/worktree-bootstrap.mjs"]
|
|
972
|
+
link_from_main = [".env"]
|
|
973
|
+
|
|
974
|
+
[git.worktrees.sync]
|
|
975
|
+
install_after_move = "background"
|
|
976
|
+
notice_paths = ["AGENTS.md", "pmcp.toml"]
|
|
977
|
+
|
|
978
|
+
[git.submodules]
|
|
979
|
+
|
|
980
|
+
[logging]
|
|
981
|
+
level = "warn"
|
|
982
|
+
|
|
983
|
+
[ui.claude]
|
|
984
|
+
|
|
985
|
+
[permissions.claude]
|
|
986
|
+
ask = ["Read(.env)", "Bash(git push:*)"]
|
|
987
|
+
|
|
988
|
+
[marketplaces.team]
|
|
989
|
+
source = { github = "example/team-marketplace" }
|
|
990
|
+
|
|
991
|
+
[marketplaces.team.plugins]
|
|
992
|
+
review = { targets = ["claude", "codex"] }
|
|
993
|
+
```
|
|
994
|
+
|
|
184
995
|
## Operator shell guards
|
|
185
996
|
|
|
997
|
+
Deprecated: `[[hooks.shell]]` and `[[hooks.edit]]` still work, and `pmcp project`
|
|
998
|
+
warns. Declare `[[hooks.guards.custom]]` instead, with `on = "before_shell"` or
|
|
999
|
+
`on = "after_edit"`, and list its runtimes in `[hooks] targets`: every runtime
|
|
1000
|
+
now has a hook bundle adapter, and this separate shell adapter will be removed
|
|
1001
|
+
in a later major release.
|
|
1002
|
+
|
|
186
1003
|
Declare a project-owned guard explicitly to project it into Codex, Gemini or
|
|
187
1004
|
Antigravity's native hooks. Without a declaration, pmcp generates no hooks.
|
|
188
1005
|
|