graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs
Python
0007. Plugins and foreign MCP are read in place
Status: accepted 2026-08-18
Context
Grok-build feels like it "just works" with Claude/Codex/Cursor because it
reads their trees where they already live. graff's first-run adopt copies
MCP and skills into ~/.codegraff/ once, then ignores anything installed
after that marker. A skill cannot see a plugin that was never copied. MCP
added to ~/.claude.json after the first graff session never connected.
Copying also duplicates secrets and drifts from the other harness's live config.
Decision
- Discover plugin roots in place:
~/.cursor/plugins/,~/.claude/plugins/,~/.grok/plugins/,~/.codex/plugins/,~/.codegraff/plugins/, and the project.cursor/.claude/.grok/.codex/.harness/plugins/trees. Parent dirs are listed two levels deep so Cursorlocal/<name>/is visible (OpenCode globs named skill trees; grok-build lists immediate children).cache/andmarketplaces/are not walked. Cache installs come from Claude/Cursorinstalled_plugins.jsoninstallPathentries, the same index grok-build reads. Codex does not write that file: enabled ids in~/.codex/config.toml([plugins."name@marketplace"]) resolve toplugins/cache/<marketplace>/<name>/<version>(preferlocal, else the last sorted version). We still recognize.codex-plugin/plugin.jsonfirst (Codex's manifest order) and do not list the cache tree. A directory is a plugin if it has.codex-plugin/plugin.json,.cursor-plugin/plugin.json,.claude-plugin/plugin.json,.grok-plugin/plugin.json,plugin.json,.mcp.json,mcp.json,skills/,agents/, Claude'scommands/, or a rootSKILL.md. The listing name comes from the registry key or the manifest (Cursor cache folders are content hashes). Cap 32. - Skills from those trees (and
~/.agents/skills,~/.grok/skills,~/.codex/skills,~/.cursor/skills-cursor,~/.cursor/skills) join the existing on-demandskillcatalog. Claudecommands/*.mdand a plugin-rootSKILL.md(when there is noskills/tree) load the same way. Manifestskills/commands/agentspaths and inline or path-valuedmcpServersare honored;${CLAUDE_PLUGIN_ROOT}and${CLAUDE_PROJECT_DIR}expand in MCP strings. Bodies still load only when the model callsskill. Project.harness/skillsstill wins. - Plugin
agents/join the fleet after personal~/.harness/agentsand before project.harness/agents. Codex custom agents (~/.codex/agents,.codex/agents,*.tomlor*.md) load in the matching personal/project slot before.harness/agents, so a graff file of the same name wins. - Plugin
.mcp.json/mcp.jsonplus Claude/Cursor/Grok MCP files (~/.claude.json,~/.cursor/mcp.json,.cursor/mcp.json, …) fill missing server names only. graff's~/.codegraff/mcp.jsonand.mcp.jsonstill win. Consent is unchanged (/mcp trust/--yolo). GRAFF_NO_PLUGINS=1disables the scan./pluginsandgraff pluginslist origin;/plugins load <name>shows one tree. Do not vendor grok-build. Do not auto-run plugin hooks. Do not add pluginbin/to PATH.
Consequences
- A plugin installed after first-run adopt is visible next session.
- Project plugin MCP is not more trusted than project
.mcp.json; it is less. - Discover classifies with one readdir per visited directory (not a stat per
marker) and stores skill/agent dirs on the plugin so later merges do not
inspect again. MCP merge only opens plugin trees that already have MCP.
The skill catalog reads an 8 KB frontmatter prefix (name + description),
sorts by name, and omits file paths so the system-prompt prefix is
byte-stable for prompt cache (Codex's rule: the old prompt is an exact
prefix of the new one). Bodies stay on disk until
skill name=. A named load hits the session catalog and then reads that one file; a miss or a list still rescans without rewriting the prefix. Production caches the first walk (MCP + fleet + skills share it); tests do not./pluginsand the interactive boot line print wall time so a slow home directory is visible. A plugin that lives only undercache/and is missing frominstalled_plugins.json(Claude/Cursor) orconfig.toml(Codex) is invisible until the other harness records it. - Revisit if a user needs to disable one plugin without
GRAFF_NO_PLUGINS.