Skip to content

graff — a fast agentic coding harness in Zig: multi-provider, MCP, workflows, DGM evolution loop, TS/Python SDKs

Python
4.3 KB
Raw Blame

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 Cursor local/<name>/ is visible (OpenCode globs named skill trees; grok-build lists immediate children). cache/ and marketplaces/ are not walked. Cache installs come from Claude/Cursor installed_plugins.json installPath entries, the same index grok-build reads. Codex does not write that file: enabled ids in ~/.codex/config.toml ([plugins."name@marketplace"]) resolve to plugins/cache/<marketplace>/<name>/<version> (prefer local, else the last sorted version). We still recognize .codex-plugin/plugin.json first (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's commands/, or a root SKILL.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-demand skill catalog. Claude commands/*.md and a plugin-root SKILL.md (when there is no skills/ tree) load the same way. Manifest skills / commands / agents paths and inline or path-valued mcpServers are honored; ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PROJECT_DIR} expand in MCP strings. Bodies still load only when the model calls skill. Project .harness/skills still wins.
  • Plugin agents/ join the fleet after personal ~/.harness/agents and before project .harness/agents. Codex custom agents (~/.codex/agents, .codex/agents, *.toml or *.md) load in the matching personal/project slot before .harness/agents, so a graff file of the same name wins.
  • Plugin .mcp.json / mcp.json plus Claude/Cursor/Grok MCP files (~/.claude.json, ~/.cursor/mcp.json, .cursor/mcp.json, …) fill missing server names only. graff's ~/.codegraff/mcp.json and .mcp.json still win. Consent is unchanged (/mcp trust / --yolo).
  • GRAFF_NO_PLUGINS=1 disables the scan. /plugins and graff plugins list origin; /plugins load <name> shows one tree. Do not vendor grok-build. Do not auto-run plugin hooks. Do not add plugin bin/ 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. /plugins and the interactive boot line print wall time so a slow home directory is visible. A plugin that lives only under cache/ and is missing from installed_plugins.json (Claude/Cursor) or config.toml (Codex) is invisible until the other harness records it.
  • Revisit if a user needs to disable one plugin without GRAFF_NO_PLUGINS.